Developer Portal (developer-portal-service) — Service Overview

Version: 1.0 Status: Draft Owner: Product + Developer Relations (DevRel) Last Updated: 2026-04-20 Companion: DOMAIN_MODEL · API_CONTRACTS · EVENT_SCHEMAS · AI_INTEGRATION Related ADR: ADR-0004 National-Backbone Resilience §6 (developer ecosystem)

1. Purpose — The Front Door for Developers Building on the National SMS Backbone

The Developer Portal is the canonical, public-facing surface through which every external developer — start-up engineer, bank integrator, government solutions architect, NGO field worker, large-tenant DevOps team — discovers, learns, evaluates, and adopts the Ghasi SMS Gateway. It is conceptually equivalent to the developer surfaces of Twilio, Vonage, MessageBird, Infobip, and Plivo.

Where the customer-portal is the operational tenant console (billing, dashboards, support tickets), the Developer Portal is the technical adoption surface. It owns:

Documentation — versioned API reference (rendered from OpenAPI), conceptual guides, tutorials, migration notes, regulator-compliance primers.
Sandbox environment — a fully-functional, no-cost, non-deliverable replica of the production SMS, Voice, WhatsApp, and Verify pipelines that returns realistic DLRs without touching MNO networks.
Self-serve API key & SDK credentials — developers can generate, rotate, scope, and revoke API keys without filing a ticket; portal calls auth-service and propagates revocations within ≤ 60 s.
Consumption analytics for developers — per-key request volumes, error rates, latency percentiles, and segment counts surfaced as charts and CSV exports, sourced from analytics-service.
Official server-side SDKs — Node, Python, Java, .NET, Go, PHP — with synchronised semver release pipelines.
Mobile SDKs — native Android (Kotlin), iOS (Swift), and Flutter — for OTP capture, in-app messaging, and Verify flows.
Postman / OpenAPI / code-snippet generator — pre-baked Postman collections, downloadable OpenAPI 3.1 specs, and a per-endpoint snippet generator that produces idiomatic copy-paste code in 10+ languages.
Verify API — a managed OTP product equivalent to Twilio Verify, abstracting SMS / Voice / WhatsApp / email channel fallback behind a single POST /v1/verify call.

Every capability is delivered with product-grade UX, regulator-aware copy, and Pashto / Dari / English localisation.

2. Position in the Platform — The Adoption Funnel

                            ┌────────────────────────────────────────────┐
                            │    External Developer / Tenant Engineer     │
                            └────────────────────┬───────────────────────┘
                                                 │  https://developers.ghasi.af
                                                 ▼
                  ┌──────────────────────────────────────────────────────────┐
                  │              developer-portal-service                     │
                  │                                                           │
                  │  ┌──────────────┐  ┌──────────────┐  ┌────────────────┐ │
                  │  │ Docs site    │  │ Sandbox API  │  │ SDK / snippet  │ │
                  │  │ (Next.js)    │  │ proxy        │  │ generator      │ │
                  │  └──────────────┘  └──────────────┘  └────────────────┘ │
                  │  ┌──────────────┐  ┌──────────────┐  ┌────────────────┐ │
                  │  │ Key self-    │  │ Consumption  │  │ Verify API     │ │
                  │  │ serve UI     │  │ analytics    │  │ orchestrator   │ │
                  │  └──────────────┘  └──────────────┘  └────────────────┘ │
                  └──────────────────────────────┬───────────────────────────┘
                                                 │
       ┌──────────────────────┬──────────────────┼──────────────────┬─────────────────┐
       ▼                      ▼                  ▼                  ▼                 ▼
 ┌────────────┐        ┌────────────┐     ┌────────────┐     ┌────────────┐    ┌────────────┐
 │ auth-      │        │ sms-       │     │ analytics- │     │ billing-   │    │ webhook-   │
 │ service    │        │ orchestr.  │     │ service    │     │ service    │    │ dispatcher │
 │ (keys/JWT) │        │ (Verify    │     │ (per-key   │     │ (sandbox    │    │ (sandbox  │
 │            │        │  + send)   │     │  metrics)  │     │  $0 meter)  │    │  DLR push)│
 └────────────┘        └────────────┘     └────────────┘     └────────────┘    └────────────┘

The Developer Portal is not on the SMS data plane — it is a control-plane and presentation-plane surface that shapes how the data plane is consumed.

3. Bounded Context

Dimension	Value
Domain	Developer Experience / Product / Adoption
Owner squad	Product + Developer Relations (DevRel)
Deployment unit	Kubernetes `Deployment` — `developer-portal-service` (Next.js + NestJS API), plus a dedicated `developer-portal-sandbox` namespace
Communication style	Inbound: HTTPS (browser, SDK release CI) · Outbound: HTTPS / gRPC to `auth-service`, `sms-orchestrator`, `analytics-service`, `billing-service`
Storage	PostgreSQL schema `devportal` · Redis cache · S3-compatible object store (SDK release artifacts, OpenAPI bundles)
Failure mode	Fail-soft — docs are statically rendered and cacheable at edge; sandbox failure surfaces a status banner; production data plane is never affected by portal outage

4. Responsibilities

#	Responsibility
R1	Render versioned API documentation from the canonical OpenAPI 3.1 spec (`/openapi/v1.json`) using Redoc as the primary renderer and Swagger UI as the interactive try-it surface
R2	Operate a sandbox environment that mimics the production API surface 1:1 but returns simulated DLRs (no MNO traffic, no charges)
R3	Allow developers to self-serve API keys scoped per environment (sandbox / production), with revocation propagated to `auth-service` JWKS / key cache within ≤ 60 s
R4	Surface per-key consumption analytics (requests, errors, latency, segments) sourced from `analytics-service`, exportable to CSV/JSON
R5	Publish official server-side SDKs (Node, Python, Java, .NET, Go, PHP) with synchronised semver, tagged releases, and a single source-of-truth release pipeline
R6	Publish mobile SDKs (Android, iOS, Flutter) for OTP capture, Verify flows, and in-app messaging
R7	Maintain the Postman collection, the canonical OpenAPI bundle, and a per-endpoint code-snippet generator producing copy-paste examples in ≥ 10 languages
R8	Operate the Verify API (`POST /v1/verify/{channel}`) — a managed OTP product orchestrating SMS, Voice, WhatsApp, and email channels behind a single contract
R9	Localise documentation copy in English, Pashto, and Dari (UI chrome + curated guides; reference auto-translated only where reviewed)
R10	Emit `devportal.*` events for key creation, sandbox usage, Verify lifecycle, and SDK downloads; consumed by `analytics-service` and `billing-service`

5. Non-Responsibilities

Does not authenticate end users or own the identity store — delegates to auth-service.
Does not dispatch real SMS — sandbox uses an in-process simulator; production traffic flows through sms-orchestrator.
Does not own pricing or invoicing — surfaces read-only consumption from analytics-service; billing remains in billing-service.
Does not make routing or compliance decisions — those remain in routing-engine / compliance-engine.
Does not host the regulator portal — separate regulator-portal-service.

6. Upstream / Downstream Dependencies

Direction	Service	Protocol	Purpose
Inbound user	Browser (developer)	HTTPS	Docs, sandbox, key UI, analytics dashboards
Inbound machine	SDK release CI (GitHub Actions)	HTTPS (signed webhook)	Trigger SDK publish pipelines, OpenAPI artifact upload
Inbound integration	Tenant app (production traffic)	HTTPS	`POST /v1/verify/*` Verify API calls
Outbound	`auth-service`	gRPC (mTLS)	Create / rotate / revoke API keys; resolve developer accounts
Outbound	`sms-orchestrator`	HTTPS / gRPC	Verify API send fan-out (channel = SMS)
Outbound	`channel-router-service`	gRPC	Verify API channel fallback (SMS → WhatsApp → Voice)
Outbound	`analytics-service`	gRPC	Per-key consumption metrics, time-series analytics
Outbound	`billing-service`	gRPC	Sandbox-vs-production attribution; Verify spend metering
Outbound	S3-compatible object store	HTTPS	SDK release artifacts, OpenAPI bundles, Postman collections
Outbound events	NATS JetStream	TCP	`devportal.key.`, `devportal.verify.`, `devportal.sdk.*`

7. High-Level Flow — Verify API End-to-End

8. Key Design Decisions

Decision	Rationale
Redoc as the primary docs renderer; Swagger UI for interactive try-it; Stoplight Elements evaluated and rejected for v1 (heavier client bundle)	Redoc gives the cleanest read-only reference; Swagger UI's "Try it" is industry-standard and developers already know it. Two surfaces > one mediocre compromise.
OpenAPI 3.1 as the single source of truth for every public endpoint	All SDKs, Postman, snippet generator, and docs are generated from one spec. No drift possible.
Sandbox is a separate namespace + separate base URL (`api-sandbox.ghasi.af`)	Hard isolation prevents accidental production charges; matches Twilio / Vonage convention developers expect.
Sandbox returns deterministic synthetic DLRs (e.g. `+93700000001` always returns `DELIVERED`, `+93700000002` always returns `UNDELIV`, `+93700000003` always times out)	Predictable test fixtures enable CI/E2E without flakiness.
API key revocation propagates via NATS event + Redis pub/sub to `auth-service` JWKS cache	Ensures revocation is effective platform-wide within ≤ 60 s SLO; documented in API_CONTRACTS.md §3
Verify API orchestrates channels but does not own the channel implementations	Avoids re-building SMS/Voice/WhatsApp pipelines; reuses `sms-orchestrator`, `channel-router-service`, and channel adapters
Verify codes stored as HMAC-SHA-256(code, server-pepper), never plaintext, with constant-time compare	Prevents timing attacks and rainbow-table compromise of OTP store
Verify supports rate limiting (max 5 attempts / 10 minutes per `verificationId`; max 5 starts / hour per recipient)	Mitigates OTP-grinding and brute-force; aligns with `fraud-intel-service` rules
Snippet generator uses templated AST emitters per language, optionally augmented by AI for natural-language descriptions only (never for credentials or logic)	Deterministic snippets are auditable; AI's role is narrow and reviewable
SDK release pipeline uses a monorepo of generators (OpenAPI Generator + per-language post-processors) with required human review on every release	Avoids "auto-generated SDK feels machine-translated" syndrome — DevRel reviews ergonomics before publish
All docs and portal UI localise to English, Pashto, Dari	Afghan national platform must speak Afghan languages; reduces adoption friction for local engineers
Status page (`status.ghasi.af`) is a separate static site fed by analytics-service, linked from portal	Decoupling means portal outages don't take the status page down
No code execution of submitted snippets in the browser	Eliminates an entire XSS / RCE attack surface; "Try it" runs against sandbox via signed proxy only
Static export of docs to a CDN edge	LCP < 1.2 s globally; portal failure does not break docs

9. Runtime Topology

Component	Stack	Replicas (prod)	Notes
Docs (Next.js SSG + ISR)	Next.js 15 / React 19	3	Static export to CDN; ISR for OpenAPI rebuilds
Portal API (NestJS)	Node 22 / NestJS 11	3	Key management, Verify API, snippet generator endpoint
Sandbox API proxy	Node 22 / Fastify	4	Stateless proxy w/ deterministic DLR simulator
Verify worker	Node 22	2	Channel-fallback timers, attempt accounting
PostgreSQL	Postgres 16	1 primary + 2 replicas	`devportal` schema (keys metadata, Verify sessions, SDK metadata)
Redis	Redis 7 cluster	3 nodes	Verify session state, rate limits, key revocation pub/sub
Object store	S3-compatible	n/a	SDK artifacts, OpenAPI bundles, Postman collections

10. Aggregates Owned

DeveloperAccount (linked 1:1 with auth-service Account) — profile, default tenant, preferred language, MFA preference for portal login
ApiKey (metadata only; secret material lives in auth-service) — environment, scope, label, last-used timestamp
SandboxSession — short-lived sandbox usage record per developer
VerifySession — verificationId, hashed code, channel state machine, attempts, expiry
VerifyTemplate — approved Verify message templates (locale × channel matrix)
SdkRelease — version, language, artifact URI, changelog, signing certificate fingerprint
DocsArticle — markdown + frontmatter for guides/tutorials, locale variants

11. Standards & Compliance

OpenAPI 3.1 for spec authoring; CI-validated against spectral ruleset before publish
OAS-to-SDK generation pipeline (forked OpenAPI Generator) with per-language post-processors
W3C WCAG 2.2 AA for portal UI (DevRel runs axe-core on every PR)
NIST SP 800-63B AAL2 for portal MFA; AAL3 for Verify API consumers operating high-risk flows
GDPR / Afghan Data Protection principles for developer profile data — see SECURITY_MODEL.md §4

12. Cross-Service Contracts (summary)

Consumes auth-service CreateApiKey, RotateApiKey, RevokeApiKey gRPC RPCs; emits devportal.key.created/revoked events
Consumes sms-orchestrator POST /v1/sms/send for Verify SMS dispatch
Consumes channel-router-service RequestFallback gRPC for Verify multi-channel cascade
Consumes analytics-service QueryConsumption(keyId, range) for developer dashboards
Emits devportal.verify.requested, devportal.verify.approved, devportal.verify.failed, devportal.sdk.downloaded events

13. Out-of-Scope (v1.0)

AI-pair-programming "ask the docs" assistant — tracked for v1.1; will be a separate docs-assistant-service calling the AI gateway, not embedded in this service.
Marketplace for third-party integrations (Zapier, n8n, Make) — tracked for v1.2.
Embedded billing UI — customer-portal continues to own billing; portal links out.

14. Glossary

Term	Definition
Sandbox	Non-deliverable replica of production API; predictable synthetic DLRs
Verify API	Managed OTP product abstracting channel selection, code generation, attempt accounting
Snippet generator	Per-endpoint code emitter producing idiomatic samples in 10+ languages
OAS	OpenAPI Specification (3.1 in this service)
Pre-baked Postman	A Postman collection generated from OAS, signed and versioned per release

15. Companion documents

DOMAIN_MODEL.md — aggregates, value objects, invariants, domain events
APPLICATION_LOGIC.md — use cases for key issuance, Verify orchestration, SDK release
API_CONTRACTS.md — REST endpoints (/v1/keys, /v1/verify/{channel}, /v1/snippets/{endpoint})
EVENT_SCHEMAS.md — devportal.* event payloads
DATA_MODEL.md — Postgres schema, indexes, RLS policies
SECURITY_MODEL.md — RBAC, key handling, Verify code storage
OBSERVABILITY.md — SLIs/SLOs (key revocation propagation, Verify success rate)
TESTING_STRATEGY.md — coverage targets, scenario list
DEPLOYMENT_TOPOLOGY.md — replicas, scaling, regions
FAILURE_MODES.md — failure catalog and mitigation
LOCAL_DEV_SETUP.md — docker compose up recipe
SERVICE_READINESS.md — production-readiness gate
SERVICE_RISK_REGISTER.md — known risks & mitigations
MIGRATION_PLAN.md — onboarding existing tenants and pilot developers

1. Purpose — The Front Door for Developers Building on the National SMS Backbone​

2. Position in the Platform — The Adoption Funnel​

3. Bounded Context​

4. Responsibilities​

5. Non-Responsibilities​

6. Upstream / Downstream Dependencies​

7. High-Level Flow — Verify API End-to-End​

8. Key Design Decisions​

9. Runtime Topology​

10. Aggregates Owned​

11. Standards & Compliance​

12. Cross-Service Contracts (summary)​

13. Out-of-Scope (v1.0)​

14. Glossary​

15. Companion documents​