# 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.