Initial import

docs/architecture/repository-layout.md

@@ -0,0 +1,52 @@
+# Repository Layout
+
+## Tree
+```text
+.
+|- apps/
+|  |- web/
+|  |- worker/
+|  |- bot/
+|  `- cli/
+|- packages/
+|  |- config/
+|  |- db/
+|  |- domain/
+|  `- providers/
+|- docs/
+|  |- plan/
+|  |- architecture/
+|  `- ops/
+|- infra/
+|  |- compose/
+|  `- caddy/
+`- scripts/
+```
+
+## Directory responsibilities
+### `apps/web`
+Owns the browser-facing product and HTTP API entrypoints. It should not own core business rules.
+
+### `apps/worker`
+Owns asynchronous and scheduled work. It is the execution surface for image-generation jobs, cleanup, and health polling.
+
+### `apps/bot`
+Owns Telegram admin interaction only. Business decisions still belong to `packages/domain`.
+
+### `apps/cli`
+Owns operator-facing CLI commands such as `nproxy pair`, `nproxy pair list`, and `nproxy pair revoke`.
+
+### `packages/config`
+Owns typed environment contracts and config normalization.
+
+### `packages/db`
+Owns database schema, migrations, and data-access utilities.
+
+### `packages/domain`
+Owns subscription logic, quota logic, key state transitions, and orchestration rules.
+
+### `packages/providers`
+Owns provider-specific adapters and low-level HTTP calls. It should not decide business policy.
+
+### `infra`
+Owns deployment templates and reverse-proxy configuration for the single-VPS Docker Compose target.

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.