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.

At the end of each completed task, create a PR for the changes unless the user explicitly says not to.

Treat the remote Gitea repository as the source of truth for task tracking when the user refers to issues.
Before starting implementation, open the relevant Gitea issue and read its full problem statement and acceptance criteria instead of guessing from local notes.
If the user asks to "continue work" or pick the next task, inspect the open Gitea issues and choose the first one that is logically ready to implement.
After finishing the task, push the branch and create a Gitea PR linked to the issue, usually with Closes #<issue-number> in the PR body.
If Gitea access requires credentials or network escalation, use the configured repository environment and approved escalation flow instead of skipping the issue lookup.