Platform Traceability Matrix
Version: 1.1 Status: Approved Owner: Platform Architecture Team Last Updated: 2026-04-19 References: system.md §1–10, AGENT.md §1–17 Machine-readable: traceability_matrix.csv | traceability_matrix.json
Change log
- v1.1 (2026-04-19) — Identity rebaselined (Keycloak base/default + pluggable IdP provider abstraction for tenant external OIDC/SAML SSO). Compliance Layer requirements added. Firebase-specific requirement and ADR retargeted.
Platform Requirements Traceability
| ID | Requirement | Source | Epic | Feature | User Story | Test Level | Test Reference | Observability Signal | Status |
|---|---|---|---|---|---|---|---|---|---|
| PLT-REQ-001 | TypeScript strict mode enforced across all services | AGENT.md §1.1 | — | — | — | unit | tsconfig.json strict check | log | Draft |
| PLT-REQ-002 | No shared databases between microservices | AGENT.md §5.2 | — | — | — | contract | cross-service-db.contract.test | log | Draft |
| PLT-REQ-003 | All REST APIs follow OpenAPI 3.1 with /v1/ versioning | AGENT.md §6.1 | — | — | — | contract | openapi-validation.contract.test | log | Draft |
| PLT-REQ-004 | UUID primary keys on all database tables | AGENT.md §7.1 | — | — | — | integration | db-schema.integration.test | log | Draft |
| PLT-REQ-005 | All services expose /health/live and /health/ready | AGENT.md §12.1 | — | — | — | integration | health-endpoints.integration.test | metric | Draft |
| PLT-REQ-006 | Prometheus metrics exposed on /metrics for all services | AGENT.md §12.1 | — | — | — | integration | metrics-endpoint.integration.test | metric | Draft |
| PLT-REQ-007 | OpenTelemetry tracing in all services | AGENT.md §12.1 | — | — | — | integration | otel-tracing.integration.test | trace | Draft |
| PLT-REQ-008 | NATS consumers must be durable with explicit acks | AGENT.md §9.1 | — | — | — | integration | nats-durable.integration.test | metric, log | Draft |
| PLT-REQ-009 | Dead-letter queues for all NATS consumers | AGENT.md §9.1 | — | — | — | integration | nats-dlq.integration.test | metric, log | Draft |
| PLT-REQ-010 | No fire-and-forget NATS publishing | AGENT.md §9.2 | — | — | — | unit | nats-client.unit.test | log | Draft |
| PLT-REQ-011 | Keycloak is the base/default IdP for platform users; auth-service issues the platform JWT | system.md §2 + ADR-0002 | AUTH-EPIC-001 | Keycloak baseline | — | integration | auth-keycloak.integration.test | log, trace | Draft |
| PLT-REQ-011a | auth-service exposes an IdentityProvider port with pluggable providers (Keycloak default, Tenant-OIDC, Tenant-SAML, Firebase-legacy); downstream services are IdP-agnostic | ADR-0002 | AUTH-EPIC-002 | IdP provider abstraction | — | unit+integration | identity-provider-port.unit.test, idp-dispatch.integration.test | log, trace | Draft |
| PLT-REQ-011b | Tenant organisations can federate their own external IdP (OIDC or SAML 2.0) for SSO, brokered via Keycloak IdP mappers | ADR-0002 | AUTH-EPIC-003 | Tenant external SSO | — | e2e | tenant-external-sso.e2e.test | log, trace | Draft |
| PLT-REQ-011c | SCIM 2.0 inbound provisioning endpoint for enterprise tenant IdPs | ADR-0002 | AUTH-EPIC-004 | SCIM | — | integration | scim.integration.test | log | Draft |
| PLT-REQ-011d | Firebase retained only as a legacy provider for existing customers; no new tenant onboarding | ADR-0002 | AUTH-EPIC-005 | Firebase retirement | — | integration | auth-firebase-legacy.integration.test | log | Draft |
| PLT-REQ-012 | API Key authentication for programmatic access | system.md §2 | — | — | — | integration | auth-apikey.integration.test | log, trace | Draft |
| PLT-REQ-013 | HMAC signatures for all webhook payloads | AGENT.md §11.1 | — | — | — | unit | hmac-signing.unit.test | log | Draft |
| PLT-REQ-014 | Secrets stored in Vault or K8s Secrets — never plaintext | AGENT.md §11.1 | — | — | — | — | Manual audit | log | Draft |
| PLT-REQ-015 | RBAC with admin, customer, operator roles | system.md §2 | — | — | — | integration | rbac.integration.test | log, trace | Draft |
| PLT-REQ-016 | All sms_messages partitioned by month in Postgres | AGENT.md §7.1 | — | — | — | integration | db-partitioning.integration.test | metric | Draft |
| PLT-REQ-017 | Redis used for rate limiting, idempotency, and caching only | AGENT.md §8 | — | — | — | integration | redis-usage.integration.test | metric | Draft |
| PLT-REQ-018 | SMPP 3.4 with enquire_link heartbeat and operator failover | system.md §2 | — | — | — | integration | smpp-connector.integration.test | metric, log | Draft |
| PLT-REQ-019 | Domain layer contains zero framework imports | AGENT.md §4.2 | — | — | — | unit | domain-isolation.unit.test | — | Draft |
| PLT-REQ-020 | Conventional commits enforced in CI | AGENT.md §16 | — | — | — | — | commitlint CI step | log | Draft |
| PLT-REQ-021 | All APIs input-validated with Zod | AGENT.md §6.1 | — | — | — | unit | zod-validation.unit.test | log | Draft |
| PLT-REQ-022 | HTTPS everywhere — no plaintext HTTP in production | AGENT.md §11.1 | — | — | — | — | Manual + Cloudflare config | log | Draft |
| PLT-REQ-023 | Pino structured logging in all services | AGENT.md §12.1 | — | — | — | integration | logging.integration.test | log | Draft |
| PLT-REQ-024 | console.log forbidden in production | AGENT.md §12.2 | — | — | — | unit | no-console.lint.rule | — | Draft |
| PLT-REQ-025 | Monorepo pnpm workspace structure as defined in system.md §1 | system.md §1 | — | — | — | — | CI workspace validation | log | Draft |
| PLT-REQ-026 | Every outbound SMS is evaluated by the Compliance Layer (gRPC EvaluateCompliance) before routing; pipeline is fail-closed | ADR-0003 | COMP-EPIC-001 | Compliance evaluation | — | integration+e2e | compliance-evaluate.integration.test, compliance-fail-closed.e2e.test | metric, log, trace | Draft |
| PLT-REQ-027 | Compliance verdicts: ALLOW / FLAG / HOLD / BLOCK; non-ALLOW messages never reach a carrier | ADR-0003 | COMP-EPIC-001 | Verdict enforcement | — | integration | compliance-verdict.integration.test | log, trace | Draft |
| PLT-REQ-028 | Hold queue with manual review (release/reject) in admin-dashboard; async tenant notifications via notification-service | ADR-0003 | COMP-EPIC-002 | Hold queue | — | e2e | compliance-hold-queue.e2e.test | log | Draft |
| PLT-REQ-029 | Tenant compliance scoring (0–100) and risk tiering drives automated enforcement thresholds | ADR-0003 | COMP-EPIC-003 | Tenant scoring | — | integration | compliance-score.integration.test | metric, log | Draft |
| PLT-REQ-030 | Compliance audit log is immutable, append-only, retained ≥ 13 months (regulatory evidence) | ADR-0003 | COMP-EPIC-004 | Audit retention | — | integration | compliance-audit-retention.integration.test | log | Draft |
| PLT-REQ-031 | Compliance AI classification runs on a local LLM with external LLM fallback governed by data residency | ADR-0003 | COMP-EPIC-005 | AI classification | — | integration | compliance-ai.integration.test | metric, log | Draft |
Architecture Decision Records
| ID | Decision | Rationale | Source | Status |
|---|---|---|---|---|
| PLT-ADR-001 | NestJS as default backend framework (NestJS allowed) | Performance, plugin ecosystem, TypeScript-first | AGENT.md §1.2 | Approved |
| PLT-ADR-002 | NATS JetStream as primary async bus (not Kafka) | Lower operational overhead, built-in JetStream persistence | system.md §4 | Approved |
| PLT-ADR-003 | PostgreSQL only — no MongoDB, no MySQL | Relational integrity required for billing, auditability | AGENT.md §7.2 | Approved |
| PLT-ADR-004 | Superseded by PLT-ADR-009. Originally: Firebase Authentication (not Auth0, not custom) | Early-stage decision; no multi-IdP need at the time | system.md §2 | Superseded |
| PLT-ADR-009 | Keycloak as base / default IdP with pluggable IdentityProvider port in auth-service — tenant external OIDC/SAML SSO brokered via Keycloak IdP mappers. Firebase retained only as a legacy provider. | Multi-provider is required to land enterprise tenants with corporate SSO (Azure AD, Okta, Google, ADFS); Keycloak avoids vendor lock-in and is deployable in regulated regions | 01-enterprise-architecture §3.1, auth-service SERVICE_OVERVIEW §5 | Approved |
| PLT-ADR-010 | Compliance Layer as first-class architectural tier implemented by compliance-engine — synchronous gRPC evaluation in the orchestrator's NATS consumer, fail-closed, non-ALLOW verdicts never reach a carrier | Regulatory exposure, tenant abuse potential, and need for immutable evidence demand a dedicated compliance tier, not ad-hoc checks in orchestration | 01-enterprise-architecture §3.2 and §4, compliance-engine SERVICE_OVERVIEW | Approved |
| PLT-ADR-005 | gRPC for Routing Engine sync calls (latency-sensitive) | REST overhead unacceptable for <50ms routing decisions | system.md §2 | Approved |
| PLT-ADR-006 | SMPP Connector as StatefulSet (not Deployment) | SMPP sessions require stable pod identity | infra baseline | Approved |
| PLT-ADR-007 | Domain-Driven Design across all microservices | Enforces clean architecture, testability | AGENT.md §4 | Approved |
| PLT-ADR-008 | OpenTelemetry for all tracing (not Jaeger SDK directly) | Vendor-neutral; OTel Collector routes to any backend | AGENT.md §12 | Approved |