Service Template

Rule: All 17 markdown docs must exist under the documentation repository (services/<name>/ there) before any service code is written in the application monorepo. Stubs are acceptable for an early service (headings only), but every file is present and owned.

Repository layout (read this first)

Repository	Path (example)	What lives there
Documentation	D:\GhasiTech\ghasi-e-documentation\Ghasi-edTech	The 17 markdown files for each service under services/<name>/ (this folder name matches the service name; it is not the NestJS code tree).
Application (code)	D:\GhasiTech\Ghasi-edTech	NestJS code under services/<name>/. The scaffold-service playbook in that repo generates code only — it does not create or regenerate these 17 specs.

If a single clone combines both, still keep the separation: specs in the documentation repo path; runnable code in the application monorepo.

17 required docs (alphabetical; existing services may use NN-NAME.md prefix)

#	File	Owns
1	SERVICE_OVERVIEW.md	Purpose, bounded context, responsibilities, aggregates, dependencies, diagram, key decisions
2	DOMAIN_MODEL.md	Aggregates, entities, value objects, invariants, domain events (names + payloads)
3	APPLICATION_LOGIC.md	Use cases, commands, queries, ports, orchestration flows
4	API_CONTRACTS.md	REST endpoints: path, method, auth, headers, request/response schema, error codes, pagination
5	EVENT_SCHEMAS.md	Events produced + consumed, versions, payload schemas, retention class
6	DATA_MODEL.md	TS interfaces + Postgres schema + indexes + RLS policies + ID prefix convention
7	SYNC_CONTRACT.md	Per-aggregate conflict policy (server_authoritative / append_only / crdt_yjs / lww / lww+diff / max-of)
8	AI_INTEGRATION.md	Every AI call: purpose, prompt template, moderation policy, HITL flow, AIProvenance touch points
9	SECURITY_MODEL.md	RBAC/ABAC matrix, encryption class, audit events, GDPR participation, data residency
10	OBSERVABILITY.md	SLIs/SLOs, dashboards, alerts, runbook links
11	TESTING_STRATEGY.md	Unit/integration/contract/e2e coverage targets + scenario list
12	DEPLOYMENT_TOPOLOGY.md	Runtime (Node/Go/Python), replicas, scaling, regions, dependencies
13	FAILURE_MODES.md	Failure catalog: what breaks, user impact, detection, mitigation
14	LOCAL_DEV_SETUP.md	docker compose up recipe, seed data, common commands
15	SERVICE_READINESS.md	Readiness gate checklist (must be green before prod)
16	SERVICE_RISK_REGISTER.md	Known risks, owners, mitigations
17	MIGRATION_PLAN.md	How legacy data / existing tenants migrate in

Directory skeleton

Specs (documentation repo only): services/<name>/ at the root of the documentation repository contains the 17 markdown files listed above.

Code (application monorepo):

services/<name>/
├── README.md                     optional pointer to documentation repo `services/<name>/`
├── package.json                  { "name": "@ghasi/service-<name>", "version": "0.0.1" }
├── tsconfig.json                 extends ../../tsconfig.base.json
├── vitest.config.ts
├── .env.example                  never commit a real .env
├── openapi.json                  generated from controllers
├── drizzle.config.ts             drizzle-kit config (schema path, out dir, driver)
├── src/
│   ├── domain/
│   │   ├── <aggregate>.ts
│   │   ├── <value-object>.ts
│   │   ├── events/
│   │   ├── errors/
│   │   ├── __builders__/         (test utilities colocated)
│   │   └── index.ts
│   ├── application/
│   │   ├── ports/                <name>.port.ts
│   │   ├── use-cases/            <name>.use-case.ts
│   │   ├── dtos/
│   │   └── mappers/
│   ├── infrastructure/
│   │   ├── adapters/             <name>.adapter.ts
│   │   ├── config/               env schema (Zod), DI wiring
│   │   └── events/               outbox-relay, inbox-dedupe
│   ├── presentation/
│   │   ├── controllers/          <name>.controller.ts
│   │   ├── guards/
│   │   └── dtos/                 response shapes
│   ├── app.module.ts
│   └── main.ts                   initializes @ghasi/telemetry BEFORE NestFactory
└── test/
    ├── unit/
    ├── integration/
    │   ├── tenant-isolation.spec.ts      (mandatory)
    │   ├── outbox.spec.ts                (mandatory)
    │   └── inbox.spec.ts                 (mandatory)
    ├── contract/
    │   ├── <endpoint>.pact.spec.ts
    │   └── <event>.schema.spec.ts
    └── e2e/

Scaffolding workflow (for AI assistants)

When the user asks for a new service <name>:

1. Confirm the bounded context against docs/02-ddd-bounded-contexts.md. A service maps 1:1 to a bounded context.
2. Confirm the service exists in the catalog: docs/03-microservices/. If not, user must approve adding it.
3. Create the 17 docs first under the documentation repo (services/<name>/ there). Even as stubs with headings. Do not write application code until the docs exist and the user has reviewed SERVICE_OVERVIEW.md, DOMAIN_MODEL.md, API_CONTRACTS.md, EVENT_SCHEMAS.md.
4. In the application monorepo, run /scaffold-service (see commands/scaffold-service.md) to generate code only — tests, NestJS layers, configs — not the 17 markdown files.
5. Wire up the four layers with a minimal "hello world" use case that exercises the full path: controller → use case → port → adapter → domain. This catches layering violations early.
6. Add the three mandatory integration tests: tenant-isolation, outbox, inbox — all passing before any feature work.
7. Commit with conventional commit: feat(<name>): scaffold service with required docs and skeleton (documentation repo) and/or chore(<name>): scaffold service skeleton and mandatory tests (code monorepo).

Required per-service checks in CI

• ESLint: domain layer import-restriction passes.
• Typecheck: strict, zero errors.
• Unit + integration + contract tests green.
• OpenAPI diff gate: no breaking changes without major version bump.
• Pact consumer tests green against Pact broker.
• Event schema conformance green against schema registry.

Service readiness gate

A service is ready for production only when:

• All 17 docs complete (not stubs).
• Coverage thresholds met (see DEFINITION_OF_DONE.md).
• test/integration/tenant-isolation.spec.ts passes.
• OpenTelemetry instrumentation verified in staging (traces + logs + metrics visible in Grafana).
• SLOs declared + alerts configured with runbooks.
• Canary deploy completed (5% / 30 min) in staging; rollback verified.
• On-call rotation assigned.
• SERVICE_READINESS.md signed off by tech lead + SRE.