57 lines
3.1 KiB
Markdown
57 lines
3.1 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`.
|
|
|
|
## Workflow
|
|
- At the end of each completed task, create a PR for the changes unless the user explicitly says not to.
|
|
|
|
## Gitea Workflow
|
|
- 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.
|