nroxy/docs/architecture/system-overview.md

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.