Ghasi-SMS-Gateway — Documentation Population Report

Generated: 2026-04-18 Author: Platform Engineering (documentation sprint) Branch: master

---

1. Summary

This report documents the documentation work completed in the 2026-04-18 documentation sprint for the Ghasi-SMS-Gateway platform. All 13 service stub directories have been populated with full 17-doc sets, a Kong ADR has been provisioned, architecture docs updated, and Jira-ready epics/stories generated for every service.

Totals

Category	Count
Services fully documented (17 docs each)	13
Total service documentation files created/updated	221
Jira-ready epics created	58
Jira-ready user stories created	~270
ADRs created	1
Architecture docs updated	2
Platform-level docs updated	1

---

2. ADR Provisioned

ADR-0001 · Kong Edge API Gateway

File: docs/architecture/ADR-0001-kong-edge-api-gateway.md

Decision: Retire the custom NestJS api-gateway service and replace it with Kong Gateway as the north-south edge for all HTTP traffic.

Key implications:

• Kong owns: TLS termination, JWT validation (RS256 via JWKS from auth-service), API key authentication (custom ghasi-api-key-lookup plugin), rate limiting, correlation ID injection
• sms-orchestrator absorbs: HTTP submit endpoint, Zod validation, Idempotency-Key storage, NATS publish
• auth-service publishes: /.well-known/jwks.json (no Kong route; Kong polls cluster-internally)
• Custom Kong Lua plugin: ghasi-api-key-lookup — hashes X-API-Key header, calls auth-service internal lookup, injects tenant headers

---

3. Architecture Documents Updated

File	Version	Change
docs/01-enterprise-architecture.md	v1.0 → v1.1	Container view: api-gateway pod replaced with Kong Gateway. Sequence diagrams updated. Redis namespace updated for Kong rate limiting.
docs/03-platform-services.md	v1.0 → v1.1	Ingress layer: NGINX + api-gateway pod → Kong Deployment (2–6 replicas). Traffic flow updated.

---

4. Services Populated

4.1 Edge & Access

api-gateway (Kong Configuration Layer)

Status: Fully documented (17 docs + _report.md) Bounded context: Edge gateway — TLS, auth, rate limiting, routing to upstream services New vs. updated: All documents newly generated from ADR-0001 and Kong architecture

Epics created:

Epic ID	Title	Stories	Points
EP-KONG-01	Adopt Kong as edge gateway	US-KONG-001 – US-KONG-005	~25
EP-KONG-02	Migrate authentication to Kong plugins	US-KONG-010 – US-KONG-015	~30
EP-KONG-03	Migrate rate limiting to Kong	US-KONG-020 – US-KONG-023	~15
EP-KONG-04	Kong observability and SRE readiness	US-KONG-030 – US-KONG-034	~16
EP-KONG-05	Cutover and decommission custom api-gateway	US-KONG-040 – US-KONG-043	~18

---

auth-service

Status: Fully documented (17 docs + _report.md) Bounded context: Identity — JWT issuance (RS256), JWKS publication, API key lifecycle, user/account management Key integration: Publishes JWKS for Kong JWT plugin; provides internal API key lookup endpoint for ghasi-api-key-lookup Kong plugin

Epics created:

Epic ID	Title	Stories	Points
EP-AUTH-01	Kong JWT Integration (JWKS Publisher)	US-AUTH-001 – US-AUTH-005	26
EP-AUTH-02	API Key Lifecycle & Kong Plugin Integration	US-AUTH-010 – US-AUTH-015	34
EP-AUTH-03	User & Account Management	US-AUTH-020 – US-AUTH-025	28
EP-AUTH-04	Session Management & Token Refresh	US-AUTH-030 – US-AUTH-034	20
EP-AUTH-05	Security Hardening & Observability	US-AUTH-040 – US-AUTH-044	18

---

4.2 Messaging Core

sms-orchestrator

Status: Fully documented (17 docs + _report.md) Bounded context: Outbound messaging pipeline — HTTP accept through carrier-bound publish Key change: Absorbed HTTP submit API from retired api-gateway per ADR-0001

Epics created:

Epic ID	Title	Stories	Points
EP-ORCH-01	HTTP Submit API (Kong-Fronted)	US-ORCH-001 – US-ORCH-006	34
EP-ORCH-02	Outbound Pipeline Orchestration	US-ORCH-010 – US-ORCH-016	40
EP-ORCH-03	Idempotency & Deduplication	US-ORCH-020 – US-ORCH-023	18
EP-ORCH-04	Retry & Dead-Letter Handling	US-ORCH-030 – US-ORCH-034	22
EP-ORCH-05	Observability & Readiness	US-ORCH-040 – US-ORCH-044	16

---

routing-engine

Status: Fully documented (17 docs + _report.md) Bounded context: Operator selection — gRPC service for cost/priority/failover routing Key fact: P95 ≤ 50 ms latency budget; Redis-cached decisions; consumes operator.health from NATS

Epics created:

Epic ID	Title	Stories	Points
EP-RE-01	gRPC Service Foundation	US-RE-001 – US-RE-005	~26
EP-RE-02	Routing Rule Engine	US-RE-010 – US-RE-014	~22
EP-RE-03	Operator Health Cache Subscription	US-RE-020 – US-RE-022	~13
EP-RE-04	Observability & Operational Readiness	US-RE-030 – US-RE-033	~14

---

smpp-connector

Status: Fully documented (17 docs + _report.md) Bounded context: SMPP protocol layer — carrier connectivity, PDU transmission, DLR ingestion Key fact: Not fronted by Kong (SMPP is not HTTP); credentials from Vault via operator-management-service

Epics created:

Epic ID	Title	Stories	Points
EP-SC-01	SMPP Session Management	US-SC-001 – US-SC-00x	~20
EP-SC-02	PDU Transmission	US-SC-010 – US-SC-01x	~18
EP-SC-03	DLR Handling	US-SC-020 – US-SC-02x	~15
EP-SC-04	TPS Throttling and Failover	US-SC-030 – US-SC-03x	~15

---

dlr-processor

Status: Fully documented (17 docs + _report.md) Bounded context: Delivery receipt correlation — consumes sms.dlr.inbound, updates message status, triggers billing and webhooks

Epics created:

Epic ID	Title	Stories	Points
EP-DLR-01	Core DLR Processing Pipeline	US-DLR-001 – US-DLR-00x	~25
EP-DLR-02	Orphan Handling & Reconciliation	US-DLR-010 – US-DLR-01x	~10
EP-DLR-03	Downstream Event Publishing	US-DLR-020 – US-DLR-02x	~12
EP-DLR-04	Observability & Operations	US-DLR-030 – US-DLR-03x	~10
EP-DLR-05	Security & Compliance	US-DLR-040 – US-DLR-04x	~8

---

4.3 Commerce & Operations

webhook-dispatcher

Status: Fully documented (17 docs + _report.md) Bounded context: Reliable webhook delivery — HMAC-signed HTTP POST to customer endpoints with exponential backoff

Epics created:

Epic ID	Title	Stories	Points
EP-HOOK-01	Webhook Configuration Management	US-HOOK-001 – US-HOOK-00x	~15
EP-HOOK-02	Webhook Delivery Engine	US-HOOK-010 – US-HOOK-01x	~25
EP-HOOK-03	Observability & Operations	US-HOOK-020 – US-HOOK-02x	~10
EP-HOOK-04	Security	US-HOOK-030 – US-HOOK-03x	~8

---

billing-service

Status: Fully documented (17 docs + _report.md) Bounded context: Revenue & cost — billing event ingestion, pricing tiers, operator cost tracking, invoice generation

Epics created:

Epic ID	Title	Stories	Points
EP-BILL-01	Chargeable Event Ingestion	US-BILL-001 – US-BILL-00x	~20
EP-BILL-02	Invoice Generation	US-BILL-010 – US-BILL-01x	~18
EP-BILL-03	Pricing & Cost Administration	US-BILL-020 – US-BILL-02x	~15
EP-BILL-04	Usage Query API	US-BILL-030 – US-BILL-03x	~12
EP-BILL-05	Observability & Reliability	US-BILL-040 – US-BILL-04x	~10

---

notification-service

Status: Fully documented (17 docs + _report.md) Bounded context: Internal notifications — email/SMS alerts to users and admins from platform events

Epics created:

Epic ID	Title	Stories	Points
EP-NOTIF-01	Event Consumption & Routing	US-NOTIF-001 – US-NOTIF-00x	~15
EP-NOTIF-02	Preference Management & Suppression	US-NOTIF-010 – US-NOTIF-01x	~10
EP-NOTIF-03	Template Engine	US-NOTIF-020 – US-NOTIF-02x	~12
EP-NOTIF-04	Delivery Channels	US-NOTIF-030 – US-NOTIF-03x	~18
EP-NOTIF-05	Notification Audit Log	US-NOTIF-040 – US-NOTIF-04x	~8
EP-NOTIF-06	Observability & Reliability	US-NOTIF-050 – US-NOTIF-05x	~8

---

operator-management-service

Status: Fully documented (17 docs + _report.md) Bounded context: Operator configuration — SMPP operator CRUD, Vault credential management, routing rule management, health state authority

Epics created:

Epic ID	Title	Stories
EP-OPS-01	Operator Configuration Management	Full CRUD + Vault + routing rules + health

---

analytics-service

Status: Fully documented (17 docs + _report.md) Bounded context: Metrics aggregation — hourly/daily aggregates from billing and DLR events; internal read-only API for dashboards

Epics created:

Epic ID	Title	Stories
EP-ANLYT-01	Analytics Aggregation & Reporting Service	Full event consumption + aggregation + API

---

4.4 Frontends

customer-portal

Status: Fully documented (17 docs + _report.md) Type: Next.js 14 SPA — customer self-service (API keys, test SMS, message logs, webhooks, billing)

Epics created:

Epic ID	Title	Stories	Points
EP-CUST-01	Authentication & Account Management	US-CUST-001 – US-CUST-00x	10
EP-CUST-02	API Key Management	US-CUST-010 – US-CUST-01x	11
EP-CUST-03	Send Test SMS	US-CUST-020 – US-CUST-02x	5
EP-CUST-04	Message Logs	US-CUST-030 – US-CUST-03x	11
EP-CUST-05	Webhook Configuration	US-CUST-040 – US-CUST-04x	8
EP-CUST-06	Billing Overview	US-CUST-050 – US-CUST-05x	5

---

admin-dashboard

Status: Fully documented (17 docs + _report.md) Type: Next.js 14+ SPA — platform admin (operators, routing, monitoring, billing, user management)

Epics created:

Epic ID	Title	Stories	Points
EP-ADMDASH-01	Authentication & Access Control	US-ADMDASH-001 – US-ADMDASH-00x	8
EP-ADMDASH-02	Dashboard Overview & Real-time Monitoring	US-ADMDASH-010 – US-ADMDASH-01x	19
EP-ADMDASH-03	Operator Management	US-ADMDASH-020 – US-ADMDASH-02x	14
EP-ADMDASH-04	Routing Rules Management	US-ADMDASH-030 – US-ADMDASH-03x	8
EP-ADMDASH-05	Message Log Inspection	US-ADMDASH-040 – US-ADMDASH-04x	8
EP-ADMDASH-06	User Management	US-ADMDASH-050 – US-ADMDASH-05x	5
EP-ADMDASH-07	System Health View	US-ADMDASH-060 – US-ADMDASH-06x	5
EP-ADMDASH-08	Billing Oversight	US-ADMDASH-070 – US-ADMDASH-07x	5

---

5. Newly Generated Specifications (no prior source)

The following specifications were generated from first principles (no corresponding _sources/ document existed):

Service	Document	Basis
api-gateway	All 17 docs	ADR-0001 + Kong architecture
auth-service	SECURITY_MODEL, MIGRATION_PLAN	Kong integration requirements
sms-orchestrator	SERVICE_OVERVIEW, MIGRATION_PLAN	ADR-0001 responsibility transfer
All services	AI_INTEGRATION	Platform standard (not in source specs)
All services	SERVICE_READINESS	Platform standard checklist
All services	SERVICE_RISK_REGISTER	Risk analysis from architecture

---

6. Updated Existing Documentation

Item	Change
docs/01-enterprise-architecture.md	Kong replaces api-gateway in container view + sequence diagrams
docs/03-platform-services.md	Ingress layer updated; Kong service entry
docs/07-epics-and-user-stories.md	Populated with full epic index and ID prefix registry
docs/architecture/ADR-0001-kong-edge-api-gateway.md	Created (new ADR)

---

7. Retired / Archived Items

The following source materials from _sources/ directories were used to generate the new docs and are now superseded. They remain in place for reference but should not be treated as authoritative:

• All functional_requirements.md, api_design.md, solution_design.md, event_model.md files under services/*/​_sources/*/

---

8. Jira Import Checklist

• Create Jira projects for SMS-GATEWAY (or use existing project with service-prefixed epics)
• Import epics first (one Jira Epic per EP-{PREFIX}-NN)
• Import user stories, linking each to its parent epic
• Map acceptance criteria to Jira acceptance criteria custom field
• Map story points to Jira story points field
• Set priority: P0 epics (EP-PLAT-01, EP-PLAT-02) → Highest; P1 → High; P2 → Medium
• Assign sprint buckets based on dependency order in docs/07-epics-and-user-stories.md §4

---

9. Open Points Carried Forward

ID	Question	Owner
OP-PLAT-001	Outbox pattern for sms.events.status to guarantee at-least-once to billing/webhooks?	Architecture
OP-PLAT-002	orch.sms_messages 90-day partition retention: auto-drop or cold archive?	Data Engineering
OP-PLAT-003	Multi-region SMPP: active-active vs. active-passive?	Architecture
OP-PLAT-004	Validation failures: sms.outbound.deadletter or separate poison-pill queue?	Platform Engineering
OP-FR-001	(from sms-orchestrator source) Validation failures to DLQ or poison-pill queue?	Platform Engineering
OP-FR-003	(from sms-orchestrator source) Outbox pattern for domain events?	Architecture