# AGENTS.md

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

## Source of truth
Read these files before making architectural changes:
- `docs/plan/system-plan.md`
- `docs/architecture/system-overview.md`
- `docs/architecture/repository-layout.md`
- `docs/ops/deployment.md`
- `docs/ops/telegram-pairing.md`
- `docs/ops/provider-key-pool.md`

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

## Top-level boundaries
- `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.

## Guardrails
- 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: manual crypto invoice renewal.
- Preserve the chosen quota display contract: user-facing approximate buckets only.

## Required follow-up when changing key areas
- 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`.