# 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`: notification provider boundary for WeCom, Feishu, and 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:

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