genalpha-bss

Executive summary

genalpha-bss is a complete telecom BSS built the way TM Forum's Open Digital Architecture says systems should be built: as independent components, each exposing a standard TMF Open API, composed behind one gateway. It is vendor-neutral — any OIDC identity provider, any PostgreSQL, any Kafka-protocol broker — and multi-tenant to the bone: two demo operators, GenAlpha and Nova Telecom, run side by side on a single deployment with cryptographic identity isolation and database row-level security between them.

Three properties distinguish it from reference implementations and demo-ware:

• Everything is verified end-to-end in a real browser. Twenty-eight Playwright suites walk the storefront, guest checkout, both consoles, the mobile app, tenant isolation, role administration and campaign journeys on every change. The five core components also pass the official TM Forum conformance kits (CTK) with zero failures.
• Composability is real, not aspirational. Every optional module can be left out of a deployment; dependencies are enforced by a composer tool; the channels quietly hide any feature whose component is absent.
• The business loops actually close. Orders complete themselves through a thin production layer, usage becomes overage on real bills, promo codes become bill discounts, saved cards pay next month's invoice, and a network alarm becomes an outage banner an agent can see — all demonstrable in minutes.

The five-minute story

1. An anonymous visitor browses GenAlpha's storefront, configures a triple-play bundle (phone model, color, storage — the price follows each choice), applies promo code WELCOME10, and sees the discount before having any identity.
2. Checkout validates the address (TMF673 standardizes it), checks fiber serviceability (TMF679), books an installer slot (TMF646), reserves the phone from stock (TMF687), and authorizes payment (TMF676) — the visitor registers mid-flow and the interrupted checkout resumes itself.
3. A purely digital order needs nobody: the thin SOM (TMF641/640) activates it in seconds, draws a phone number from the tenant's pool (TMF685), and completes the order machine-side — provisioning inventory (TMF637), capturing payment, minting a 12-month commitment agreement (TMF651) and redeeming the promo (TMF671) on the way.
4. The network reports 12.3 GB of roaming (TMF635); the customer's meter shows 12.3 / 10 GB — over allowance. The monthly billing run (TMF678) puts the overage and the promo discount on one bill, which the customer pays with the card vaulted at checkout (TMF670) — one click, no retyping.
5. A critical alarm (TMF642) becomes a service problem (TMF656) and every agent's CSR console shows the outage banner; resolution clears it. Each event along the whole journey became a customer notification (TMF681).
6. Meanwhile Nova Telecom's customers do all of the same on shop.nova.localhost against Nova's own identity realm, Nova's own catalog and Nova's own number range — and neither operator can see one byte of the other's world.

The module catalog

Core commerce — always deployed

Optional components — compose per deployment

Production (OSS) — the layer below, thin but real

Channels — one build each, white-labeled per tenant by hostname

Architecture at a glance

Machine-to-machine calls (ordering → catalog/stock/payment/agreement/promotion, billing → inventory/usage/promotion, SOM → ordering, payment → vault) always use the acting tenant's client credentials, so downstream tenancy holds even for background work. Interactive diagrams: docs/architecture.md.

Multitenancy — the pool model with two locks

• Identity lock: a tenant is a verified OIDC issuer. Users cannot claim a tenant — their token's issuer, validated against per-tenant keys, decides it. Each tenant can bring its own IdP (a Keycloak realm in dev; a Cognito pool or Entra tenant in production works identically).
• Data lock: every domain row carries tenant_id, enforced in code on every query and by PostgreSQL Row-Level Security — services connect as restricted database roles that see zero rows without a session tenant, even for SQL with no predicate at all. Cross-tenant access reads as 404 everywhere: foreign ids never leak existence.
• White-labeling: anonymous traffic gets its tenant from the hostname at the gateway, so each operator's shop window shows only its own catalog, prices, promos and numbers. The same scoping stacks a level deeper: partner/business-unit agents are confined by an org claim within their tenant.

Composability

The ODA promise made operational: every optional module has an enabled flag in the Helm chart, the composer page enforces the dependency matrix (billing needs payment; appointment needs qualification; the vault needs payment…) and emits a ready-to-use values override, and the channels degrade gracefully — a deployment without the stock component simply has nothing stock-managed, without qualification nothing is serviceability-gated, without the vault the card form still works. Cross-component calls go through conditional clients with no-op fallbacks, so absent modules cost nothing at runtime.

How it is verified

• ~260 unit and integration tests, including real-PostgreSQL migration tests per component and an RLS proof that connects as the restricted role and demonstrates zero-visibility without a tenant.
• Twenty-one browser E2E suites (Playwright) driving the real stack: the storefront journey, guest checkout, both consoles, the business console (B2B: org boundary, consolidated invoicing, invitations, member my-page), plan change (same number, commitment guard), SIM self-care, the Family Max configurable bundle, value-added services (partner entitlement / security feature / billing-only), business rules and dynamic pricing, soft-bundle cardinality, two-operator tenant isolation including a full purchase in Norwegian with NOK, TMF672 role administration, number porting both directions, the mobile app, and the martech loop. The suites run after every change.
• Official TM Forum CTKs: eleven kits pass with zero failures (TMF620, 622, 632, 637, 666, 663, 669, 687, 635, 677, 678) — plus two components that fail their kits on purpose, with the reasons documented.
• The journey film — a 2:54 recording of a human using every surface, re-shot after every feature against the live stack; it has caught real bugs twice.
• CI builds and tests every component on every push.

Security & post-quantum readiness

The BSS embeds almost no cryptography of its own — identity, transport and payment crypto live behind the same seams as every other vendor dependency, which is precisely the crypto-agility that post-quantum migration guidance calls for. The full inventory is published in docs/pqc-readiness.md; the shipped state:

• Quantum-safe edge, today. The Helm chart ships an Ingress (TLS 1.3 only) plus controller values enabling X25519MLKEM768 hybrid key exchange (ML-KEM-768, FIPS 203, classical fallback preserved) — countering harvest-now-decrypt-later, the one quantum risk with a present-tense clock.
• Card secrets encrypted at rest. SIM PUKs are AES-256-GCM field-encrypted with the ICCID bound in as authenticated data; the key arrives from a KMS/secret store. AES-256 is post-quantum comfortable.
• A runtime that already speaks post-quantum. The fleet runs on a JVM carrying ML-KEM and ML-DSA, so the day any OIDC provider signs tokens post-quantum, verification follows via JWKS — a configuration change at the identity seam, not a rewrite.
• Honest remainder: today's token signatures are the IdP's RS256. That is the one quantum-vulnerable primitive left, and it is swappable without touching business code — which is the difference between a PQC rewrite and a PQC checklist.

Deployment

Local: mvn package → docker compose up (~27 containers, seeded demo data, both operators live). Kubernetes: a Helm chart carrying both realms, per-service RLS roles and per-tenant issuers, composed via the module picker; Terraform stacks target EKS and AKS. Dedicated single-tenant deployments (the “silo” tier for regulated customers) use the same chart with one tenant configured — the pool and silo models are one codebase.

Roadmap

• BankID step-up at checkout for offerings requiring verified identity (brokered IdP, no service changes — the vendor-neutral JWT model already carries it).
• Real PSP adapter (Stripe/Adyen) behind the existing payment seam.
• More intelligence: the AI platform now closes its own learning loop — the churn engine snapshots features daily (BSS + CSR + assurance signals), records outcomes, and trains a per-tenant logistic model in-service; operators with history import it and start production-grade. Deeper models (gradient boosting, network QoE features via TMF628) slot behind the same interfaces when real network data arrives.
• Deeper production internals where a concrete integration demands them: pluggable activation adapters, alarm correlation, TMF648 Quote for B2B.

genalpha-bss · TM Forum ODA implementation · Java 25 LTS / Spring Boot 3.5 · React + Vite · PostgreSQL + RLS · Kafka · Keycloak (dev IdP) · Helm/Terraform · This document prints cleanly — use your browser's Print → Save as PDF.