74 lines
4.9 KiB
Markdown
74 lines
4.9 KiB
Markdown
# 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: <https://martin.kleppmann.com/2017/03/27/designing-data-intensive-applications.html>
|
|
|
|
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: <https://sre.google/sre-book/table-of-contents/>
|
|
|
|
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: <https://pragprog.com/titles/mnee2/release-it-second-edition/>
|
|
|
|
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: <https://www.anthropic.com/engineering/building-effective-agents>
|
|
|
|
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: <https://docs.avalai.ir:8443/en/>
|
|
|
|
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: <https://www.zarinpal.com/> 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: <https://svelte.dev/docs/kit/introduction>
|
|
- Go documentation: <https://go.dev/doc/>
|
|
|
|
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.
|
|
|
|
## Platform operations documentation
|
|
|
|
- Docker Compose application model: <https://docs.docker.com/compose/intro/compose-application-model/>
|
|
- Docker Compose startup order: <https://docs.docker.com/compose/how-tos/startup-order/>
|
|
- Docker Engine logging: <https://docs.docker.com/engine/logging/configure/>
|
|
- Docker rootless mode: <https://docs.docker.com/engine/security/rootless/>
|
|
- Nginx proxy module: <https://nginx.org/en/docs/http/ngx_http_proxy_module.html>
|
|
- Nginx TLS module: <https://nginx.org/en/docs/http/ngx_http_ssl_module.html>
|
|
- PostgreSQL backup and restore: <https://www.postgresql.org/docs/current/backup.html>
|
|
- PostgreSQL SQL dumps: <https://www.postgresql.org/docs/current/backup-dump.html>
|
|
- Gitea Actions overview: <https://docs.gitea.com/usage/actions/overview/>
|
|
- Gitea runner: <https://docs.gitea.com/runner/>
|
|
|
|
Applied in `PLATFORM-OPERATIONS-SPEC.md` through health-gated Compose startup, isolated networks and secrets, bounded container logs, TLS/SSE proxy behavior, logical PostgreSQL backup with guarded restore, and trusted-runner release orchestration. Exact product versions and runner capabilities remain explicit approval decisions rather than assumptions.
|
|
|
|
## Qlockify deployment reference
|
|
|
|
Local read-only source: `D:/Programing/Scripts/Qlockify/qlockify-deployment`
|
|
|
|
Applied as a proven three-repository, Compose, Nginx, ACME, nested-checkout, and encrypted off-host backup reference. ZarinPal deliberately hardens the pattern by deploying immutable image digests instead of resetting/building mutable server checkouts, excluding environment/secrets from database backup packages, separating migrations/import from application startup, guarding production restore, and omitting scheduled application workers.
|