Initial import

docs/architecture/system-overview.md

@@ -0,0 +1,34 @@
+# System Overview
+
+## Runtime components
+- `apps/web`: public site, user dashboard, admin UI, HTTP API handlers
+- `apps/worker`: background jobs for generation execution, reconciliation, cleanup, and health checks
+- `apps/bot`: Telegram admin bot runtime
+- `apps/cli`: operator commands executed on the server
+
+## Shared packages
+- `packages/config`: environment parsing and config contracts
+- `packages/db`: Prisma schema, migrations, data access helpers
+- `packages/domain`: business rules and state machines
+- `packages/providers`: external adapters for model APIs, payment processor, storage, email, and Telegram
+
+## Core request flow
+1. User submits a generation request from the chat UI.
+2. The web app validates auth, subscription, quota, and request shape.
+3. The app stores a `GenerationRequest` and enqueues work.
+4. The worker runs provider routing through the key pool.
+5. The worker persists `GenerationAttempt` rows for each key-level attempt.
+6. On the first success, the worker stores assets, marks the request succeeded, and consumes quota.
+7. The web app exposes polling endpoints until the result is ready.
+
+## Data boundaries
+- User-visible request lifecycle lives in `GenerationRequest`.
+- Key-level retries live in `GenerationAttempt`.
+- Quota accounting lives in `UsageLedgerEntry`.
+- Provider key health lives in `ProviderKey` plus status-event history.
+
+## Failure handling
+- Retryable provider failures are hidden from the user while eligible keys remain.
+- User-caused provider failures are terminal for that request.
+- Balance or quota exhaustion removes a key from active rotation.
+- Provider-key state transitions must be audited.