MASTER PRODUCTION PLAN — Sovereign OS / Jamii Online Console & Vertical Ecosystem

Date: 9 Nov 2026
Branch: program-backlog
Status: Design for implementation by another agent. Every file path, route name, API contract, and component spec below is concrete enough to build from without further discovery.
Relationship to backlog: Implements lanes in Consolidated Program Backlog (VF, MARS-CFG, FCT) and Vertical Fabric backlog (VF) (VF-01 through VF-26). Honesty invariants per Honesty Invariants apply to every line below.

0. EXECUTIVE SUMMARY

Goal: Ship a production "Jamii Online" console that presents the whole Sovereign OS ecosystem — Jamii (V9), Jijibora (V3), MARS ICE (V4/V5), Materra (V1), Sokobora (V2), Kazi (V8), Afiyalink (V6), Kujenga (V7) — through one simple UI, one API surface, one Dokku deployment, with core integrations (OpenMaint, Plane.io, ERPNext, Fleetbase, Kill Bill, Kutuma).

The answer in one line: One console shell (sovereign-console) → one BFF surface (agent-bff :3030 + jamii-bff :3000 facade) → canonical SurrealDB primitives (claim, truth_node/edge, resource/edge, integration_entity) → Camel/Kestra orchestration. Every vertical is a configuration of the same fabric, not a fork. The UI is defined below as a route-by-route spec so an implementing agent can build unchecked.

Design constraints (non-negotiable, from AGENTS.md — Sovereign OS / Cosmic Circuit mandates + D-15):

• Zero bespoke tables. Everything maps into claim, truth_node/edge, resource/edge, integration_entity.
• Declarative-first: lookups, thresholds, packs, maps live in NATS KV (SOVEREIGN_LOOKUPS/SOVEREIGN_SCENARIOS/SOVEREIGN_TEMPLATES). Runtime never reads disk.
• Fail-closed: infrastructure errors → 502/503/422/throw. Never synthetic "OPTIMAL"/"APPROVED".
• Soft≠LIVE honesty: live_gate_met/invent_refuse_live are real probe results, never env-flag fakes.
• Price honesty: no invented prices/savings percentages; pilot SKU prices unpublished until a real product decision.
• Event-spine honesty: nats_outbox is the durable write; NATS publish is best-effort relay, never blocking.

1. MARKET ANALYSIS & VERTICAL STRUCTURE

1.1 The nine verticals (from Sovereign OS: Commercial Verticals & Packaging Catalog)

1.2 Product families → sellable packs

1.3 What sells vs. what defers

• Sells: HOA starter desk, gate/billing, property reflex, sourcing with escrow, ICE dispatch — all with PoCE receipts.
• Defers (by design, per GTM): FIPS, Daraja live payments, city-wide federation, AI autonomy without human approval.

2. END-STATE UI — Jamii Online Console (implementable spec)

2.1 Shell principles

• App: apps/sovereign-console (Vite/React, :10300). Rebranded to Jamii Online (index.html title + CommunityHubPage.tsx header).
• Auth: Keycloak (jamii realm) via RequireAuth; ActiveCommunityProvider scopes every query to the active community.
• Event backbone: EventStreamProvider (WebSocket /ws on agent-bff) multiplexes NATS + outbox → UI. No polling.
• One pattern per screen: header (community + property + status pill) → list → detail → action buttons (primary) → receipts. No nested tabs.
• Color: Jamii green #1F7A4D primary, ink #101820, paper #FFFFFF.
• All mutations go through BFF; no direct Surreal/Supabase calls from the browser.

2.2 Route map (implementable spec)

Public:
/                              → HomePage (dashboard: today's community pulse)
/login                         → LoginPage
/register                      → RegisterPage
/forgot-password               → ForgotPasswordPage
/verify/share/:shareId         → ShareVerifyPage
/verify/materra/:batchId       → VerifyPageWrapper

Authenticated (RequireAuth → AuthenticatedShell):
/dashboard                     → ModulesHubPage (community pulse: dues, gate, tickets)
/community                     → CommunityHubPage     (estate overview)
/community/admin               → CommunityAdminPage   (members, units, roles)
/community/desk                → StarterDeskPanel     (GTM-01: messages → claims)
/community/properties          → PropertyDeskPage *NEW* (list properties; open property)
/community/properties/:id      → PropertyDetailPage *NEW* (events desk + reflex + standing orders)
/community/sourcing            → SourcingDeskPage *NEW* (requirements, offers, solve, bind)
/community/safety              → SafetyDeskPage *NEW* (incidents, dispatch, resolve, assign)
/community/billing             → BillingPage *NEW* (Kill Bill subscriptions, invoices)
/community/notifications       → NotificationsPage    (Kutuma inbox)
/community/settings            → SettingsPage + SystemPage

/jijibora                      → JijiboraReflexPage *NEW* (property playbook, standing orders)
/jijibora/sourcing             → JijiboraSourcingPage *NEW* (solver view)
/jijibora/emergency            → EmergencyPage *NEW* (ICE + MARS escalation)

/materra/inbox                 → MaterraInboxPage     (existing)
/materra/assets                → MaterraAssetsPage   (existing)
/materra/logs                  → MaterraLogsPage     (existing)
/materra/observations          → MaterraObservationsPage (existing)
/materra/map                   → MaterraMapPage      (existing)
/materra/plans                 → MaterraPlansPage    (existing)
/materra/inventory             → MaterraInventoryPage (existing)
/materra/chat                  → MaterraChatPage     (existing)
/materra/*                     → MaterraVirtualAppPage (existing catch-all)

/sokobora/*                    → Sokobora* pages (existing: merchant, standing-orders, supplier, store, jamii, enterprise, mesh, ops, driver, campaigns, accounting)
/afiya/*                       → HealthRecordsPage + VaultPage (existing)
/vault/*                       → VaultPage + VaultClaimPage (existing)
/inbox                         → InboxPage (existing)
/calendar                      → CalendarPage (existing)
/tasks                         → TasksPage (existing)
/fleet/*                       → Fleet* pages (existing)
/notifications                 → NotificationsPage (existing)
/modules/*                     → ModulesHubPage + all existing module routes (karibu, employment, forms, workflows, etc.)
/settings                      → SettingsPage
/system                        → SystemPage (health, live_gate_met)

2.3 Components to build (file paths + data contracts)

2.4 Components that already exist (do not rebuild)

Materia*, Sokobora*, KillBill*, Vault*, HealthRecords*, TruthGraph*, Fleet*, Forms*, WorkflowDesigner*, InboxPage, NotificationsPage, CalendarPage, TasksPage, CommunityAdminPage, OrganizationsPage, KaribuAdminPage, MateriaVirtualAppPage, SokoboraJamiiPage, etc.

3. API SURFACE — what exists, what to build

3.1 Existing routes (verified in apps/agent-bff/src/)

Community starter (GTM-01):

• POST /v1/community/starter/messages, GET /v1/communities/:orgId/starter/desk, POST /v1/community/starter/dispatch, POST /v1/admin/tenants/provision, POST /v1/ops/alerts/alertmanager, GET /v1/governance/divergences

Property playbook (GTM-12 generalized):

• POST /v1/community/properties/events, GET /v1/communities/:orgId/properties/:propertyId/events, POST /v1/community/properties/:id/playbook, POST /v1/community/properties/:id/events/:eventId/complete, GET /v1/community/properties/:id/events/:eventId, POST /v1/community/properties/events:batch, GET /v1/community/properties/:id/standing-orders, POST .../standing-orders/:orderId/arm, GET /v1/community/health, GET /v1/community/:orgId/stream (SSE), GET /v1/community/:domain/:id/poce, GET /v1/community/dlq

Sourcing:

• POST /v1/community/sourcing/requests, POST /v1/community/sourcing/offers, GET /v1/communities/:orgId/sourcing, POST /v1/community/sourcing/:id/solve, POST /v1/community/sourcing/:id/bind

Safety (MARS ICE):

• POST /v1/community/safety/sos, GET /v1/communities/:orgId/safety/incidents, POST /v1/community/safety/:incidentId/dispatch, POST .../resolve, POST .../assign

OpenAPI: apps/agent-bff/openapi/community-starter-v1.json (15 base + 7 new paths + components: CanonicalEnvelope, ErrorEnvelope, OutboxEnvelope)

3.2 To build (deliverables for the implementing agent)

3.3 Code libraries required (all exist or specified)

The implementing agent does not need to invent any library. If A1–A7 are missing, the plan above is the exact contract to add.

4. SUBSCRIPTIONS — how products are sold

4.1 Tier table (from Sovereign OS: Commercial Verticals & Packaging Catalog + Playbook Monetization — Subscriptions, Entitlements, Billing, Splits & Wallets)

Metering: $0.50 per reflex execution beyond 500/mo. Escrow is 0% in trial; % of GMV for Sokobora. All packs are config (fragments + KV + scenario), not code forks — turn on via subscription_plan + APF.

4.2 Monetization architecture (from Playbook Monetization — Subscriptions, Entitlements, Billing, Splits & Wallets)

• Law (CFG): offer_package, subscription_plan, entitlement_policy, deploy_plan, billing_adapter_binding — declarative sellable package, cadence, inheritance, deploy map, billing engine.
• Facts: commercial_subscription (s101) — durable subscription SoR. Ban bespoke service_subscription table.
• Hot access: NATS JetStream KV entitlement snapshot + entitlement.delta.v1 — use-time gate (sourcing G1–G4); freshness deny.
• Billing adapter: Kill Bill :3091 / Malipo / Stripe bridge — invoice & payment, not entitlement SoT.
• Org provider fee: ORG-SVC-10 — child deploy → commercial_invoice + platform fee line + outbox.
• Splits: contract_split_rule on sovereign_contract — BPS shares by layer ∈ {platform, pack_creator, parent_scope, community_treasury, reseller, cohort_operator}. Extend rule metadata, keep contract_split_rule + wallet credit events. No new SoR tables.
• Wallets: Wallet membership as claim + scope. Malipo / Sikasie ledger = balance SoR (not process-local Map). sikasie_wallet / tx types incl. REVENUE_SPLIT. Community treasury, escrow, savings.
• Rule: UI and BFF never invent balances. Wallet credit after split = adapter call or Surreal fn behind BFF that fails closed if Malipo/Surreal down.

4. DOKKU PRODUCTION DEPLOYMENT

4.1 Core stack (Dokku apps)

dokku apps:create sovereign-core        # SurrealDB (:8000), NATS (:4222), Redis (:6379)
dokku apps:create agent-bff             # :3030 (community + jijibora + ice + sourcing)
dokku apps:create jamii-bff             # :3000 (SQL proxy facade, existing)
dokku apps:create truth-bff             # :3031 (existing; leave as-is)
dokku apps:create sovereign-console     # :10300 (Jamii Online UI)
dokku apps:create dokku-solver-gateway  # :3070 (existing Dockerfile)
dokku apps:create dokku-bridges         # killbill, medusa, usafiri (existing Dockerfiles)
dokku apps:create dokku-superset        # BI (existing)
# Integrations (existing services, repointed to Dokku):
#   OpenMaint, Plane.io, ERPNext, Fleetbase, Kutuma (Novu), Keycloak (:8081), MinIO, OpenBao (:8200), Kestra (:8180), Camel (:8181)

4.2 Integration wiring (all via Camel :8181, no direct calls from UI)

4.3 Dokku runbook (ops)

dokku apps:create sovereign-console
git push dokku main
dokku config:set sovereign-console VITE_API_URL=https://api.example.com VITE_AGENT_BFF_URL=https://bff.example.com
dokku nginx:reload sovereign-console

4.4 Production checklist (VF-16/VF-18, from Production Gaps & Execution Roadmap)

• SurrealDB community_os deployed + deploy-truth-graph.ps1 + core strata (s0–s356)
• CNS type/interface/event catalogs imported (cns_type_catalog_*, cns_event_catalog_jijibora)
• NATS KV seeded (seed-nats-kv-declarative.mjs)
• Kestra flows deployed (jijibora.*, community_starter_dispatch)
• Camel routes active (building-reflex-actuate, community-sourcing-scatter, mars-ice-dispatch, openmaint-*, fleetbase-*)
• Keycloak jamii realm + kutuma client configured
• run-gtm-live-observe.mjs --require-live → live_gate_met:true
• check-criteria-subject-consistency.mjs → PASS; check-mars-freeze.mjs → PASS
• Tenant provisioning wizard (POST /v1/admin/tenants/provision already exists; automate sub-60s)
• Payment gateway live cutover (M-Pesa Daraja production, Stripe production keys — NOT sandbox)
• HA/DR: RocksDB snapshots to offsite MinIO, NATS 3-node cluster, documented RPO/RTO
• Observability: dashboards, alerting, SLA dashboards (not just raw exporters)
• Public SDKs & headless docs: OpenAPI specs published, TypeScript SDK docs

5. GAP-BRIDGING PLAN — current → end state

Implementation sequence:

1. Land A1–A7 APIs (§3.2) + tests (extend building-reflex-sourcing-mars.test.js).
2. Build §2.2 pages in order: PropertyDesk → PropertyDetail → SourcingDesk → SafetyDesk → BillingPanel → Jijibora sections.
3. Rebrand shell to Jamii Online; wire /kazi, /kujenga proxies.
4. Dokku deploy per §4; run §4.4 checklist.
5. Ship subscription gating (APF + subscription_plan) per §4.2.

6. GOVERNANCE & ACCEPTANCE (merge gates)

• No bespoke tables. Any new table needs MARS-CFG-00 absolute-necessity review (default refuse). Check with check-mars-freeze.mjs.
• Fail-closed. Engines down → 502/503, never invented success. Check with run-gtm-live-observe.mjs --require-live.
• One platform, many packs. Vertical packs are config (fragments + KV + scenario), not forks. Check with check-criteria-subject-consistency.mjs.
• Acceptance: node --test (20/20) + run-gtm-live-observe.mjs --require-live (live_gate_met:true) + check-* scripts PASS before merge to main.

7. STAKEHOLDER SUMMARY — what to say outside

"One governance fabric, many vertical packs." Jamii Online is the front door. Behind it is Sovereign OS — the same Surreal + NATS + Camel/Kestra fabric that powers property reflexes, sourcing, emergency dispatch, agriculture, labor, and health. You buy the fabric once and add packs as you grow. Every action leaves a receipt. No lock-in: your data, rules, and playbook stay yours.

8. NEXT STEPS

1. This plan reviewed by product/architecture.
2. Implementing agent picks up §2–§3 and builds the console + A1–A7 APIs on program-backlog.
3. Dokku deploy per §4; run §4.4 checklist.
4. Trial pilots per Document 00 — Stakeholder Proposal: JijiBora for Local Government (TZ/KE/GH/RW/UG/JM).
5. Scale packs per subscriptions in §4.1.