Specification Conventions
Version: 1.0
Status: Approved
Owner: Platform Architecture Team
Last Updated: 2026-04-12
References: system.md §1–10, AGENT.md §1–17
1. Document Header Template
Every specification file MUST begin with:
# <Document Title>
**Version:** 1.0
**Status:** Draft | Approved
**Owner:** <Team>
**Last Updated:** YYYY-MM-DD
**Service:** <Service Name> (<SHORT_CODE>)
**References:** [system.md](../../system.md) §<n>, [AGENT.md](../../AGENT.md) §<n>
2. Requirement ID Scheme
Platform-wide
| Prefix | Scope |
|---|---|
PLT-REQ-xxx | Platform-level requirement |
PLT-ADR-xxx | Architecture Decision Record |
Per-service
| Prefix | Artifact |
|---|---|
<CODE>-FR-xxx | Functional requirement |
<CODE>-NFR-xxx | Non-functional requirement |
<CODE>-TR-xxx | Technical requirement |
<CODE>-AR-xxx | Architectural requirement |
<CODE>-EPIC-xxx | Epic |
<CODE>-FEAT-xxx | Feature |
<CODE>-US-xxx | User story |
IDs are stable and never reused. Deprecated IDs are marked [DEPRECATED] in-place.
3. Service Short Codes
| Service | Code |
|---|---|
| api-gateway | GW |
| auth-service | AUTH |
| sms-orchestrator | ORCH |
| smpp-connector | SMPP |
| routing-engine | ROUTE |
| dlr-processor | DLR |
| billing-service | BILL |
| webhook-dispatcher | HOOK |
| analytics-service | ANLYT |
| notification-service | NOTIF |
| operator-management-service | OPS |
| admin-dashboard | ADMDASH |
| customer-portal | CUST |
4. Traceability Matrix Schema
All traceability matrices (.md, .csv, .json) share this schema:
| Field | Type | Description |
|---|---|---|
id | string | Stable REQ ID (e.g. GW-FR-001) |
requirement | string | Short requirement statement |
source | string | system.md §n or AGENT.md §n |
epic | string | Parent epic ID |
feature | string | Parent feature ID |
user_story | string | Parent story ID |
test_level | enum | unit, integration, contract, e2e |
test_reference | string | Test file or suite path/name |
observability_signal | string | metric, log, trace, or combination |
status | enum | Draft, Approved, Implemented, Verified |
5. Diagram Placement Rules
| File | Diagram type |
|---|---|
architectural_requirements.md | Structural: DDD layer, component, dependency graphs |
solution_design.md | Behavioural: sequence, state, flowcharts for flows |
architecture_baseline.md | Platform C4 context, container, NATS topology, DB ownership |
infrastructure_baseline.md | Deployment topology (local Docker Compose vs K8s prod) |
All diagrams use Mermaid embedded in Markdown code fences. No external image files.
6. Assumptions Section Template
Every spec file MUST include an "Assumptions and Open Points" section:
## Assumptions and Open Points
| ID | Assumption / Open Point | Owner | Resolution Date |
|----|------------------------|-------|----------------|
| A-001 | ... | ... | ... |
7. Status Lifecycle
Draft → In Review → Approved → Implemented → Verified
Changes to Approved documents require a version bump and change log entry.