diff --git a/docs/REFERENCES.md b/docs/REFERENCES.md new file mode 100644 index 0000000..c158c99 --- /dev/null +++ b/docs/REFERENCES.md @@ -0,0 +1,53 @@ +# Engineering References and Applied Principles + +Reference documents provide evidence and design guidance; they do not override approved project specs or agent rules. + +## Designing Data-Intensive Applications — Martin Kleppmann + +Source: + +Applied here through explicit reliability, scalability, and maintainability trade-offs; immutable import provenance; idempotent processing; derived-data rebuildability; and separating the logical data model from physical indexes/materializations chosen from measured access patterns. + +## Site Reliability Engineering — Google + +Source: + +Applied here through service-level objectives before operational tuning, actionable monitoring, release health checks, rollback readiness, capacity awareness, and restore rehearsal rather than backup existence alone. + +## Release It!, Second Edition — Michael T. Nygard + +Source: + +Applied here through bounded resources, timeouts, backpressure, failure isolation, explicit readiness/liveness, safe startup/shutdown, and treating production behavior as part of design rather than a deployment afterthought. + +## Building Effective Agents — Anthropic + +Source: + +Applied to the post-MVP AI capability: begin with deterministic analytics and the simplest bounded LLM workflow, add agentic autonomy only where evaluation demonstrates value, keep tools/data access explicit, and retain human-readable traces and budgets. + +## AI Agents and Cloud Patterns — course slides + +Local source: `C:/Users/Eight/Downloads/ai_agents_cloud_patterns_1405.pdf` + +Applied to future AI execution through durable job/session state, idempotency, queue boundaries, traceability, execution budgets, authentication/authorization, and an outbox-style handoff where cross-system delivery must be reliable. + +## AvalAI documentation + +Source: + +Applied as a post-MVP integration constraint: AvalAI credentials remain backend-only; provider/model configuration is environment-driven and pinned; requests receive timeouts and bounded retries; prompts receive minimized aggregate data; and provider responses cannot become the analytical source of truth. + +## ZarinPal visual references + +Source: plus the user-supplied authenticated desktop/mobile screenshots. + +Applied in the frontend repository's `DESIGN.md`: Persian RTL layout, right-side navigation/drawer, spacious light canvas, white cards, blue action/active states, dark ink surfaces, restrained yellow accent, rounded geometry, and responsive behavior. Proprietary assets/fonts are used only if legally supplied. + +## Framework documentation + +- SvelteKit introduction: +- Go documentation: + +Framework decisions remain subordinate to capability requirements. SvelteKit is used as a TypeScript application framework without assuming SEO/SSR; Go is used for the backend with architecture, DI, database access, and API choices approved through the specification process. +