Jijibora Architecture — Design Thesis in Developer Terms

Scope: Jijibora as a composition over the platform planes — control loop (observe → react → log), building/event reflex model, claim-records backbone, ontology package + governance hooks, composed patterns. Focus: where new logic lives, how Jijibora composes shipped engines, and what is explicitly non-goal. (Source: Jijibora GTM 04; Government Trial 04; platform-map system D-01.) Status: as of 2026-11-09 Blueprint sources: docs/jijibora-gtm/04_AI_DRIVEN_INTERFACE_AND_ORCHESTRATION.md; docs/jijibora-gtm/01_MARKET_AND_CUSTOMER.md; docs/jijibora-government-trial/04_UNIFIED_ONTOLOGY_AND_REACTIVE_GOVERNANCE.md; Architecture — Design Thesis and Planes (Developer Concept Doc); Data Fabric — Message Bus and Engine Interfaces (Developer Concept Doc); Claims Plane — Processing Claims, Guarded Transitions, and Declarative Packs; Apache Camel Compliance Gateway (compliance-camel, :8181); datasets/lookups/lookup.jijibora..json; datasets/scenarios/scenario.jijibora..json; apps/agent-bff/src/jijibora-event-ontology.js; apps/agent-bff/src/building-reflex-routes.js

What this means for you

Jijibora does not add a forked vertical. It composes the headless planes — claims, truth fabric, event spine, integration gateway, identity — via declarative packs (lookup + scenario) and the canonical envelope. If you are building a Jijibora feature, your job is to declare a pack and consume existing planes, not to add a new table or a branch on Jijibora claim types.

Details (features/interfaces)

1. Thesis — headless-first composable platform

PROBLEM — vertical sprawl defeats reuse. Teams repeatedly build bespoke front-to-back verticals with their own tables, glue code, and delivery paths; cross-vertical collaboration becomes point-to-point wiring that cannot be governed or audited as one platform. (Source: platform-map/system/D-01-ARCHITECTURE.md §0.)

MECHANISM — logic lives in headless engines; surfaces are optional. Durable logic — identity, claims, leases, escrows, optimisation, event delivery — runs in headless background engines. Customers keep existing frontends and consume through narrow, stable interfaces: REST, GraphQL, WebSocket, WhatsApp, or USSD. Turnkey clients are optional consumers, never owners of the logic. (Source: platform-map/system/D-01-ARCHITECTURE.md §0.)

INVARIANTS — compose-first, declarative-first, fail-closed. Prefer seeding and composing shipped engines over creating new capabilities. Coding is reserved for generalised processors or genuinely impractical cases; persistence of delivery, event binding, subject routing, and handler dispatch stays declarative. When an engine is unavailable the platform fails closed with a typed error and never returns a synthetic success. (Source: platform-map/system/D-01-ARCHITECTURE.md §0; Data Fabric — Message Bus and Engine Interfaces (Developer Concept Doc) §2.)

Jijibora inherits this thesis directly: the market thesis positions it for small, self-governing communities with a legal entity, a budget, and 50–5,000 households, in four archetypes (master-planned developments, retirement, golf/lifestyle, bedroom/commuter estates), not for "cities." (Source: docs/jijibora-gtm/01_MARKET_AND_CUSTOMER.md §1.)

2. The control loop — observe → react → log

Ontology in developer terms: Ontario the control loop names the per-event runtime shape. Every Jijibora reflex is a three-phase loop over the same envelope, not three separate systems.

The loop's governance is expressed as three plane composition facts:

• Standing order (s117) + Geo gate (s352) + Compliance gate (s350) = reactive entity. The declarative example in the GTM doc shows when: event = weather.flooding.high, s2_cell, river_gauge > 2.1m / then: open shelter, notify marshals, pump → auxiliary power, SMS alert, bus re-route, escrow lock. It fires via JetStream push (no polling), with a default causation_depth guard (4 → DLQ + human review), NATS leaf nodes per facility. (Source: docs/jijibora-gtm/04_AI_DRIVEN_INTERFACE_AND_ORCHESTRATION.md §3.1.)
• Solver as the brain. For each reactive event, the Solver Gateway (:3070) runs a deadline-bounded chain (3–5 sec): Timefold/CP-SAT/VROOM → MiniZinc/MILP → greedy. The checker (checkers.py) independently validates (slump life, weight rating, curfew, noise); invalid → 502 checker_rejected; infeasible → MUS auto-repair in plain English. Every decision closes the loop with PoCE verification. (Source: docs/jijibora-gtm/04_AI_DRIVEN_INTERFACE_AND_ORCHESTRATION.md §3.3.)
• AI proposes, named humans decide — AI is a compiler and narrator, never an authority. Five governance hops enforce it: Tier A eligible-provider set, scope pre-retrieval (predicate in WHERE clause so AI sees only the requesting community's docs), Decision Gates (ALL_APPROVED / MAJORITY / QUORUM(n of m) / SEQUENTIAL), break-glass (dual approval, TTL, audit), and cost reconciliation (no optimisation on unreconciled actuals). (Source: docs/jijibora-gtm/04_AI_DRIVEN_INTERFACE_AND_ORCHESTRATION.md §1.)

The loop sequence at the user level is: Resident (WhatsApp) → Akili classifies → Truth Graph (bylaws, assets, credentials) → Solver (optimal assignment) → Standing order fires (weather) → Decision Gate (human approves) → Camel/Kestra actuates (Fleetbase, OpenMaint, SMS, escrow) → PoCE receipt seals the loop. The user sees only the outcome with proof. (Source: docs/jijibora-gtm/04_AI_DRIVEN_INTERFACE_AND_ORCHESTRATION.md §4.)

3. Building/event reflex model

Jijibora's "buildings respond to events" is implemented as a declarative playbook + standing-order pair, not bespoke code:

Orchestration examples by community type are declarative orders per type: retirement home (heat wave → pre-cool, hydration check-ins, family notify), golf (storm → irrigation off, buggy park, bunker crews rostered), bedroom (blackout → generator auto-start, gate on battery, shuttles rerouted), estate/SEZ (flood → shelter opens, pumps lock, buses reroute, marshals dispatched). (Source: docs/jijibora-gtm/04_AI_DRIVEN_INTERFACE_AND_ORCHESTRATION.md §3.2.)

Two engine conventions lock the model:

• The canonical envelope is the only wire shape: { correlation_id, trace_id, voyage_id, envelope_subject, payload, headers?, signature?, proof? } on platform.criteria.v1.* subjects. (Source: Data Fabric — Message Bus and Engine Interfaces (Developer Concept Doc) §1.)
• The ontology module apps/agent-bff/src/jijibora-event-ontology.js implements canonical-envelope v1 validation (E_ENVELOPE_INVALID, E_SCHEMA_VERSION, E_PIPELINE_DEPTH_EXCEEDED, E_PIPELINE_CYCLE), max pipeline depth 8, stage subjects (broadcast, phase, stage.*, child, flush, dlq), and outbox-anchor construction — explicitly no bespoke tables, no direct JetStream publish from stage handlers. (Source: apps/agent-bff/src/jijibora-event-ontology.js header.)

4. The claim-records backbone

Every Jijibora fact — ticket, due, announcement, visitor pass, building event, sourcing requirement — is a claim under the claims plane. (Source: Architecture — Design Thesis and Planes (Developer Concept Doc) §2; Claims Plane — Processing Claims, Guarded Transitions, and Declarative Packs.)

Key backbone facts:

• The plane is a single generalised processing-claim primitive: the data plane enforces the lifecycle, the runtime resolves declarative policy values from value groups and scenario packs from scenario groups, and the transactional outbox carries lifecycle events to the spine consumer. (Source: Claims Plane — Processing Claims, Guarded Transitions, and Declarative Packs Facts.)
• Packs supply values only; the runner never branches on claim type, and swapping a value group changes refusal rules with zero code change. A referenced-but-missing value fails closed, never an invented default. (Source: Claims Plane — Processing Claims, Guarded Transitions, and Declarative Packs Facts.)
• The data plane enforces an eight-state lifecycle: draft → submitted/cancelled; submitted → validation/rejected/cancelled; validation → approved/rejected/disputed; approved → settled/disputed; rejected → disputed/cancelled; disputed → validation/cancelled; settled and cancelled are terminal. Guarded runner evaluates gate, quorum, separation, evidence, and external-verdict stages in order and refuses on any failing stage. Finalisation accepts only approved/settled/rejected claims and requires an execution session. (Source: Claims Plane — Processing Claims, Guarded Transitions, and Declarative Packs §1.)
• Creation dual-maps to the canonical claim through a deterministic universal name and a mint path, with no domain-specific extension fields ever added. (Source: Architecture — Design Thesis and Planes (Developer Concept Doc) §2.)
• The community starter pack declares cns://claim/type/community/ticket, due, announcement, visitor_pass over channels whatsapp, sms, email and governed actions dispatch, complete. Sourcing declares cns://claim/type/community/sourcing_requirement, offer, binding with governed actions solve, bind, complete. (Source: datasets/lookups/lookup.jijibora.community.starter.v1.json; datasets/lookups/lookup.jijibora.community.sourcing.v1.json.)

5. Ontology package + its governance hooks

The unified ontology is a single shared town registry: one dictionary where every department uses the same names for everything. The failure it solves is five departments filing the same physical borehole under five different names. (Source: docs/jijibora-government-trial/04_UNIFIED_ONTOLOGY_AND_REACTIVE_GOVERNANCE.md §1.)

What the package gives a developer:

The platform invariant behind runtime refusal is a loaded check: Vanta-class GRC tools collect evidence for a SOC 2; Jijibora refuses a widening child at compose time and logs federation decisions instead. (Source: docs/jijibora-gtm/01_MARKET_AND_CUSTOMER.md §5.)

6. Patterns composed

7. Non-goals (explicit)

Open items / gaps

• Orchestration facade "remains proposed optional ergonomics over existing engines rather than shipped code." (Source: platform-map/system/D-01-ARCHITECTURE.md Gaps and honesty limits.)
• Ceiling digest is not yet carried in the PoCE receipt; approved-digest recomputation is not yet in the seeder; break-glass elevation does not yet open proof or file corrective action and stays bounded by short TTL + expiring roles. (Source: platform-map/system/D-01-ARCHITECTURE.md Gaps and honesty limits.)
• Customer-held seal, customer certification, and customer-held signing root are not yet enforced. (Source: platform-map/system/D-01-ARCHITECTURE.md Gaps and honesty limits.)
• Master-plan pillars beyond the declared Done boundary — enterprise messaging, commercial operations, notarisation, trade, lifecycle mesh, parts of external engines — remain gaps and must not be inferred as shipped. (Source: platform-map/system/D-01-ARCHITECTURE.md Gaps and honesty limits.)
• Community-starter / building-reflex surfaces read NATS KV at runtime (SOVEREIGN_LOOKUPS, SOVEREIGN_SCENARIOS); disk copies under datasets/ are seed-only, not runtime reads. (Source: apps/agent-bff/src/community-starter.js header; apps/agent-bff/src/jijibora-event-ontology.js header.)