35 lines
1.6 KiB
Markdown
35 lines
1.6 KiB
Markdown
# 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.
|