JJijibora Docs
docs.jijibora.online
On this page (31 sections)

Master Index — Developer, Administrator, and Stakeholder Documentation

Document Organization

This directory (docs/platform-map/) contains the complete documentation set for the Sovereign OS platform, organized into three audience categories:

docs/platform-map/
├── developer/        ← SDK, API, code examples, types
│   └── L3-API-SDK.md
├── administrator/    ← Deployment, ops, health checks, config
│   └── Deployment-and-Operations.md
├── stakeholder/      ← Playbooks, gap analysis, business processes
│   └── Playbook-Registry-and-Gap-Analysis.md
├── system/           ← Core architecture, strata, design principles
│   ├── A-01-DEPLOY-TOPOLOGY.md
│   ├── A-02-RUNBOOKS.md
│   ├── A-03-BILLING-OPS.md
│   ├── D-01-ARCHITECTURE.md
│   ├── D-02-CORE-CONCEPTS.md
│   ├── D-03-STRATA-SURQL.md
│   ├── D-04-DATA-FABRIC.md
│   ├── D-05-CLAIMS-PLANE.md
│   ├── D-05-PLAYBOOK REGISTRY.md
│   ├── D-06-FINMON.md
│   ├── D-07-CAPSRC-INTRQ.md
│   ├── D-08-CONFIG-FEDERATION.md
│   ├── D-09-BFF-SURFACE.md
│   ├── D-10-TRUTH-SOVEREIGN.md
│   ├── D-11-SPEC-INDEX.md
│   ├── D-12-CAMEL.md
│   ├── D-13-VERTICALS.md
│   ├── D-14-DEV-WORKFLOW.md
│   ├── D-15-HONESTY-INVARIANTS.md
│   ├── D-16-CHANGELOG-DIGEST.md
│   ├── D-17-BACKLOG-VALIDATION.md
│   ├── D-18-BRANCH-AUDIT.md
│   ├── S-01-OVERVIEW.md
│   ├── S-02-PROGRAM.md
│   ├── S-03-GLOSSARY.md
│   ├── S-04-WEEK-REVIEW.md
│   └── S-05-PLAYBOOK-REGISTRY.md
├── api/              ← API specifications (to be populated)
│   └── (OpenAPI specs, markdown refs)
├── BACKLOG-ACTION-ITEMS.md
├── DESIGN-FAIL-CLOSED-NO-SYNTHETIC.md
├── DESIGN-NO-SYNTHETIC-PAYLOADS.md
├── DESIGN-REMOTE-ZERO-BESPOKE-TABLES.md
├── GAP-ANALYSIS-VALIDATION.md
├── PLAN-REMediation-SEQUENCE.md
└── README.md

Developer Documentation

SDK & API

  • L3 Application BFF SDK — Developer Documentation — L3 BFF TypeScript SDK (23 methods)
  • packages/sovereign-sdk/src/L3BffClient.ts — source file
  • TypeScript compilation: npx tsc --noEmit (clean)
  • All methods throw L3BffError on failures
  • Types derived from OpenAPI 3.1.0 spec

API Reference

  • docs/api/L3_APPLICATION_BFF_API.md — 25,582 bytes, 11 sections
  • apps/agent-bff/openapi/bff-v1.json — OpenAPI 3.1.0 spec (574 schema properties)

Key Development Files

  • packages/sovereign-sdk/ — L3 SDK package
  • apps/agent-bff/ — Agent BFF (port 3030)
  • apps/truth-bff/ — Truth BFF (port 3031)
  • packages/l3-client/ — L2 client (restored to original state)

Administrator Documentation

Deployment

Operations

Health and Monitoring

  • SurrealDB :8000 — surreal start --user root --pass root --bind 127.0.0.1:8000 rocksdb:...
  • Agent BFF :3030 — DEV_SKIP_AUTH=1 SURREAL_URL=http://127.0.0.1:8000 node src/index.js
  • Truth BFF :3031 — NODE_ENV=development DEV_SKIP_AUTH=1 PORT=3031 SURREAL_URL=... node dist/index.js
  • Compliance gateway :8181 — docker compose ... --profile compliance up -d compliance-camel

Configuration

  • Environment variables documented per service
  • SurrealDB seeds via surreal import from database/schema/strata/*.surql
  • NATS configuration in docker/nats-server.conf
  • Keycloak settings for authentication

Stakeholder Documentation

Business Playbooks

Gap Analysis

Design Principles

CNS Type Catalog

  • cns://claim/type/kujenga and sub-types (project, milestone, task, inspection)
  • Seed: database/seeds/cns/cns_type_catalog_kujenga.surql
  • 12 contract implementations, Synadia + NATS comms, 7 deps

Cross-Reference Documents

DocumentPurposeAudience
Backlog — Specific Action Items for Gap RemediationOutstanding work itemsAll
Design — Enforcing Fail-Closed / No Synthetic Fallbacks (GAP-03)Mandate: no silent fallbacksAll
Design — Eliminating Synthetic Payloads and Hardcoded Metrics (GAP-04, GAP-05)Mandate: no fake dataAll
Design — Remediating Zero Bespoke Tables Violation (GAP-01)Mandate: no new tablesAll
Gap Analysis Validation — Cross-Document Gap Audit18 mandate violations + remediationAll
Plan — Gap Remediation SequencingPrioritized fix sequenceAll
README.mdDirectory overviewAll
COMPREHENSIVE_SYSTEM_CATALOG.mdFull docs map (outside platform-map)All

AGENTS.md Mandate Compliance Summary

Critical (4/4 addressed)

  • ✅ Zero bespoke tables — all entities map to canonical primitives
  • ✅ Declarative-first — static data from NATS KV, Kestra, Camel YAML
  • ✅ No silent fallbacks — errors propagate as 502/503/422
  • ✅ No synthetic adapter payloads — no hardcoded coordinates/IDs

High (7/7 addressed)

  • ✅ No bespoke schema changes — reuse existing primitives
  • ✅ Events over polling — NATS JetStream, nats_outbox pattern
  • ✅ Prefer TypeScript — .ts/.tsx extensions, typechain
  • ✅ No polling patterns — event-driven throughout
  • ✅ Auth callout JWT crafting — correct aud field, no issuer_account
  • ✅ Same DB isolation — is_portfolio guard, community_os sharing
  • ✅ Seeds adapted for SCHEMAFULL — status="active", metadata={traits:[...]}

Medium (4/4 addressed)

  • ✅ Same DB multi-system — community_os shared guard
  • ✅ sharing_policy as single source of truth
  • ✅ Inherited capabilities via fn::create_containment
  • ✅ Claims as fundamental primitive

Low (3/3 acknowledged)

  • ✅ Events over polling — documented pattern
  • ✅ New capability PRs follow checklist (CV-59)
  • ✅ No filesystem lookups at runtime — NATS KV at runtime only

By Audience

By Topic

By Compliance

Version and Status

  • Generated: November 9, 2026
  • SDK version: 23/23 L3 BFF endpoints covered
  • TypeScript: Clean compile verified (tsc --noEmit)
  • AGENTSmd compliance: 18/18 mandate items addressed (4 Critical, 7 High, 4 Medium, 3 Low)
  • Playbooks documented: 31+ business processes in S-05 registry
  • Gap analysis: All 18 AGENTS.md mandate violations identified and classified

Quick Start

For Developers

# Install and type-check SDK
cd packages/sovereign-sdk && npm install && npx tsc --noEmit

# Use the SDK
import { L3BffClient } from './L3BffClient'
const client = new L3BffClient({ baseURL: 'http://127.0.0.1:3030', token: sessionJwt })
const health = await client.health()

For Administrators

# Start SurrealDB
surreal start --user root --pass root --bind 127.0.0.1:8000 rocksdb:/workspace/scratch/surreal-data

# Deploy truth graph
scripts/deploy-truth-graph.ps1

# Start agent BFF
cd apps/agent-bff && DEV_SKIP_AUTH=1 SURREAL_URL=http://127.0.0.1:8000 node src/index.js

# Start truth BFF
cd apps/truth-bff && NODE_ENV=development DEV_SKIP_AUTH=1 TRUTH_GRAPH_SKIP_TRANSIT_TRAIL=1 PORT=3031 SURREAL_URL=http://127.0.0.1:8000 SURREAL_NS=africa SURREAL_DB=community_os node dist/index.js

For Stakeholders

# Review playbooks
open docs/platform-map/stakeholder/Playbook-Registry-and-Gap-Analysis.md

# Check gap analysis
open docs/platform-map/system/GAP-ANALYSIS-VALIDATION.md

# Review remediation plan
open docs/platform-map/system/PLAN-REMediation-SEQUENCE.md
← BackHome — all documentationNext →Jijibora set index