devops-platform-api/RTK.md

Backend RTK

Architecture

• Framework: NestJS + TypeScript.
• Package manager: pnpm.
• Data access: Prisma Client and Prisma migrations.
• Default local behavior: seeded project configuration keeps APIs runnable while MySQL is not configured; production uses real Jenkins and Gitea clients when credentials are injected.

Module Map

• config: environment schema and validation.
• prisma: PrismaService and DB health boundary.
• health: runtime and dependency summary.
• projects: project configuration API and repository.
• deploy-runs: deploy run API, status model, BPMN step summary.
• integrations/jenkins: Jenkins API client boundary.
• integrations/gitea: Gitea API client boundary.
• notifications/wecom: current WeCom adapter boundary; notification provider abstraction is kept for future Feishu or generic webhook adapters.
• agent: LLM proxy client boundary for DevOps-only workflows.
• audit: sanitized audit record boundary.

Data Access Rules

1. Controllers call services.
2. Services call repositories and integration clients.
3. Repositories call Prisma.
4. Raw SQL is exceptional and repository-only.
5. Transactions are required for deploy run writes once persistence is enabled.

Environment Rules

• .env.example may contain placeholders only.
• .env is local-only and ignored by git.
• Missing external integration configuration should degrade to not_configured in health checks, not crash local development.

Verification

Run these before handing off backend changes when dependencies are available:

pnpm install
pnpm prisma:generate
pnpm lint
pnpm test
pnpm build