AGENTS.md

Scope

This file governs the whole repository unless a deeper AGENTS.md overrides it.

Read these files before making architectural changes:

This repository is a TypeScript monorepo for nproxy, a crypto-subscription image gateway that:

serves a B2C web product;
routes image-generation requests to external providers;
maintains a pool of provider API keys with failover, cooldown, and balance tracking;
exposes admin operations through web admin and a Telegram bot;
deploys on a single VPS with Docker Compose.

apps/web: public site, user dashboard, admin UI, and HTTP API surface.
apps/worker: background jobs for generation, billing reconciliation, media cleanup, and key health checks.
apps/bot: Telegram admin bot runtime.
apps/cli: server-side operational CLI, including Telegram pairing commands.
packages/config: typed environment loading and shared config.
packages/db: Prisma schema, migrations, and database access helpers.
packages/domain: business rules, state machines, and use-case orchestration.
packages/providers: external provider adapters for image generation, payments, email, storage, and Telegram.
docs: architecture, product, and operations documents.
infra: deployment templates and reverse-proxy configuration.

Keep business rules out of UI components.
Keep provider-specific HTTP code out of domain services.
Model user request attempts separately from provider-key attempts.
Preserve the chosen deployment target: single VPS with Docker Compose.
Preserve the chosen billing model for MVP: manual crypto invoice renewal.
Preserve the chosen quota display contract: user-facing approximate buckets only.

If you change deployment assumptions, update docs/ops/deployment.md.
If you change Telegram admin auth, update docs/ops/telegram-pairing.md.
If you change failover, cooldown, or balance logic, update docs/ops/provider-key-pool.md.