Coding Standards

Version: 1.0
Status: Approved
Owner: Platform Engineering
Last Updated: 2026-04-12
References: AGENT.md §1–17 (authoritative), system.md §9

---

1. Purpose

This document is an executive summary of the platform coding standards. The authoritative, binding source is AGENT.md. All engineers and AI code-generation tools MUST read AGENT.md before writing any code.

---

2. Non-Negotiable Rules

#	Rule	Source
1	TypeScript everywhere — no .js files	AGENT.md §1.1
2	strict: true in all tsconfig.json	AGENT.md §1.1
3	NestJS for all backend microservices — no Express, no raw Fastify	AGENT.md §1.2
4	@nestjs/platform-fastify used as HTTP adapter internally — never fastify directly in service code	Spec update
5	Next.js App Router for all frontends	AGENT.md §1.3
6	TailwindCSS + ShadCN UI — no other CSS frameworks	AGENT.md §1.3
7	Domain layer MUST have zero NestJS / Prisma / NATS imports	AGENT.md §4.2
8	No shared databases between services	AGENT.md §5.2
9	All APIs follow OpenAPI 3.1 with versioning /v1/...; use @nestjs/swagger decorators	AGENT.md §6.1
10	UUID primary keys everywhere	AGENT.md §7.1
11	Secrets in Vault / K8s Secrets — never plaintext	AGENT.md §11.1
12	Conventional commits required	AGENT.md §16

---

2a. NestJS Architecture Rules

Rule	Detail
Module structure	Each microservice MUST have a root AppModule with feature modules (SmsModule, AuthModule, etc.)
Guards	Authentication and authorisation via NestJS @Injectable() Guards — @UseGuards(JwtAuthGuard) (validates the Kong-forwarded platform JWT) and @UseGuards(ScopeGuard('sms:send')). No IdP-specific guards (e.g. FirebaseAuthGuard) in downstream services — identity is provider-agnostic by design.
Interceptors	Cross-cutting concerns (rate limiting, idempotency, logging, tracing) via NestJS Interceptor
Pipes	Input validation via NestJS ValidationPipe with class-validator DTOs
Filters	Global exception filter for consistent error response shape
Providers	Services, repositories, and publishers registered as NestJS providers with DI
No business logic in controllers	Controllers MUST delegate to application-layer use cases via injected services
OpenAPI	@nestjs/swagger decorators on all controllers and DTOs — @ApiOperation, @ApiResponse, @ApiProperty

---

3. File & Naming Conventions

Entity	Convention	Example
Files	kebab-case	sms-orchestrator.service.ts
Classes	PascalCase	SmsOrchestratorService
Variables / functions	camelCase	sendSmsMessage()
DB tables	snake_case	sms_messages
NATS subjects	<domain>.<action>.<event>	sms.outbound.request
Environment variables	UPPER_SNAKE_CASE	DATABASE_URL

---

4. DDD Folder Structure (per microservice)

/src
  /domain
    /entities
    /value-objects
    /services
    /events
    /repositories        ← interfaces only
  /application
    /use-cases
    /dto
    /mappers
  /infrastructure
    /http                ← NestJS controllers, guards, interceptors
    /nats                ← publishers, consumers
    /db                  ← Prisma repository implementations
    /config
  /tests
    /unit
    /integration
    /contract

---

5. Testing Requirements (summary)

Layer	Minimum coverage
Domain	90%
Application	80%
Infrastructure	60%

Full testing standards: solution_baseline_testing_standards.md

---

6. Commit Message Format

<type>(<scope>): <description>

Types: feat | fix | chore | docs | refactor | test | perf
Scope: service name or package (e.g. sms-orchestrator, shared-types)

Examples:
  feat(sms-orchestrator): add retry pipeline with exponential backoff
  fix(api-gateway): correct rate limit header validation
  chore(infra): update k8s HPA manifests

---

7. AI Code Generation Rule

If Cursor, GitHub Copilot, or any AI tool generates code that violates any rule in AGENT.md, the code MUST be regenerated until compliant. AGENT.md overrides all AI suggestions and framework defaults.

---

8. Assumptions and Open Points

ID	Assumption / Open Point	Owner	Resolution Date
A-001	ESLint config (shared-config package) to be published before service scaffolding begins	Platform Eng	TBD
A-002	Vitest is preferred over Jest; teams must not mix test frameworks within a service	QA Team	TBD