47 lines
2.2 KiB
Markdown
47 lines
2.2 KiB
Markdown
# 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/mvp-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 for MVP: 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`.
|