BLACKSWAN Reference Architecture (BSRA)

Version: v0.2 — SKELETON (authored 2026-07-11; §2 graduated to DRAFT v0.1 on 2026-07-12) Sponsor: Mamadou Ly, Founder, Managing Partner & CEO Scope: This document is the technical reference architecture for the BLACKSWAN estate. It registers the discipline of a reference architecture across 14 technical areas and states the authority boundary of each. It is a SKELETON overall: §2 (Estate topology) has graduated to DRAFT v0.1, while every remaining technical section (§3–§15) registers its topic, names its authority boundary, and explicitly defers substance to a named future Wave. Read time: ~8 minutes.

0. Preface

Status: v0.2 — SKELETON (overall). SKELETON is the honest label for a document that registers 14 substantial technical areas without pretending to have solved them all. Sections graduate independently: §2 (Estate topology) has graduated to DRAFT v0.1 as a curation of the shipped stack, while §3–§15 remain SKELETON stubs. The document stays SKELETON overall until every §2–§15 section is non-skeleton, at which point it reaches v1.0 FROZEN (see §17).

Authored: 2026-07-11. §2 graduated: 2026-07-12.

Sponsor: Mamadou Ly, Founder, Managing Partner & CEO.

Changelog

v0.1 — 2026-07-11 — initial SKELETON: 14 technical sections (§2–§15) registered with Intent · Scope · Non-scope · Current state · Authority · Deferred to, each deferring substance to a named Wave.
v0.2 — 2026-07-12 (§2 DRAFT v0.1) — §2 Estate topology graduated from SKELETON to DRAFT v0.1: seven-node topology roster, node posture, deployment independence, hub-and-spoke interdependencies, estate-domain overlay, and verifier-tail parity — curated from Canon v1.1, BGXS v0.2, and Implementation Standards v0.1. No other section changed; document remains SKELETON overall.

Position in the governance stack

BLACKSWAN Estate Canon v2.2              ← constitutional governance (FROZEN v2.2 · 2026-08-30)
    ↓ referenced by
BLACKSWAN Reference Architecture v0.1     ← THIS DOCUMENT (technical reference architecture · SKELETON)
    ↓ referenced by
BLACKSWAN Gateway Experience Standard     ← BGXS v0.2 DRAFT (public gateway experience)
    ↓ consumes tokens from
BLACKSWAN Enterprise Design Language      ← BEDL v0.1 DRAFT (visual + interaction system)
    ↓ realised in
Implementation Standards v0.1             ← not yet shipped

BSRA sits beneath the Canon and above BGXS. The Canon governs the estate constitutionally; BSRA describes the technical architecture the estate operates within; BGXS specifies the public gateway experience within that architecture. Where BSRA and the Canon speak to the same subject, the Canon wins.

What a SKELETON status means

Every technical section registers the topic, states its authority boundary, and explicitly defers substance to a named future Wave. No section pretends completeness. A superficial 14-section technical document that pretended completeness would be architectural theatre; a skeleton with honest Deferred to markers gives the estate the governance-stack layer it needs while telling every consumer exactly what is and is not authoritative.

Versioning

v0.x — SKELETON evolution. Sections graduate independently; the version bumps as sections mature.
v1.0 — first substantive freeze, reached only when all 14 areas (§2–§15) are non-skeleton. See §17 for graduation criteria.

1. Reader's guide

This document is for solution architects, plane leads, and external reviewers who need the technical picture beneath the Canon's constitutional statements. The Canon says what the estate is; BSRA says how the estate is shaped as a distributed system. If you are looking for the public gateway experience, read BGXS. If you are looking for visual tokens, read BEDL. If you are looking for the plane roster, vocabulary, or prohibitions, read the Canon.

Each numbered section (§2–§15) has the same shape: Intent · Scope · Non-scope · Current state · Authority · Deferred to. Read Intent and Scope to know what the section governs; read Non-scope to know what it deliberately excludes; read Current state to know how much is settled today (most sections are SKELETON stubs); read Authority to know where BSRA is authoritative versus where the Canon or a plane retains authority; and read Deferred to to know where the real detail lives — or, for a SKELETON, where it will live once the named Wave delivers it.

2. Estate topology

Status: DRAFT v0.1 — graduated from SKELETON on 2026-07-12. This section is a curation of the shipped stack (Canon v1.1 §1/§6/§7/§8/§11, BGXS v0.2 §3.1, Implementation Standards v0.1 §4.3), not net-new specification. It is the first BSRA section to leave SKELETON; §3–§15 remain SKELETON stubs.

Intent: Describe the shape of the estate as a distributed system — plane count, plane deployment independence, gateway ↔ plane relationship, LCGX externality.

Scope: Plane deployment boundaries, cross-plane traffic patterns at the topological level.

Non-scope: Specific service instances, cluster sizing, region placements.

2.1 Topology node roster (the seven addressable nodes)

The estate draws as seven addressable topology nodes: the five OS planes, the Gateway, and Nexus. This is the topological view — the set of independently-deployed, independently-addressable surfaces a distributed-systems reader must reason about. It is not the constitutional plane roster: Canon §1 remains authoritative on the roster and states there are six top-level planes (five OS planes plus the constitutional plane LCGX), that Nexus is a launcher, not an OS plane, and that the Gateway is the SSO shell + marketing surface, not an OS plane. §2 does not promote Nexus or the Gateway to plane status; it registers them as topology nodes because they are deployed surfaces with their own repos, hosts, and verifiers.

#	Node	Canon role	Topology role	Canonical repo
1	CMOS (Falcon)	OS plane — Capital Markets Operating System	Spoke	`BlackswanCapitalMarketsOS`
2	PMOS (Swan Nest)	OS plane — Private Markets Operating System	Spoke	`BlackswanPrivateMarketsOS`
3	HSOS	OS plane — Hedge & Sovereign Operating System	Spoke (governed-nav — off the Nexus render per Canon §7)	`BlackswanHedgeSovereignOS`
4	AIOS	OS plane — AI Operating System (24-row registry)	Spoke + row-registry parent	`BlackswanAIOS`
5	TREICHTEC (Digital Swan DLT)	OS plane — DLT execution plane	Spoke	`BlackswanTreichtecDLT`
6	Gateway	SSO shell + marketing surface (not an OS plane)	Governance-document hub + SSO shell	`blackswan-gateway`
7	Nexus	Launcher + access-control plane (not an OS plane)	Launcher hub (4-card render)	`blackswan-os-spine` (`blackswan-nexus` reserved)

LCGX externality. LCGX (Lybrosis Capital · Global eXchange) is the constitutional plane per Canon §1 and sits outside the seven-node topology pipeline: it is referenced by AIOS row 24 but does not participate in normal delivery (Canon §8). It is intentionally absent from the seven-node roster above because it is not an addressable OS/launcher/gateway surface in the distributed-system sense — it is the external source of authority the other nodes reference. Its posture is terminal and does not advance.

2.2 Node posture

Per Canon §6, all OS planes and LCGX carry the posture STANDBY · IN-MEMORY ONLY · HOLD · NO-GO. The Gateway and Nexus are non-OS surfaces and therefore not enumerated in the Canon §6 posture line, but they inherit the same pre-production reality: nothing is in production, nothing is GA, and every deployed surface carries the Canon §6 prototype banner. No node's state may be phrased as live, GA, in production, or shipping. The posture describes a held state, not a graded one — it is neither a pass nor a clearance.

2.3 Plane deployment independence

Each OS plane ships from its own canonical repo (§2.1 table) with its own verifier tail and its own readiness-regression suite (Implementation Standards §4.1/§4.3). No plane deploys through another plane; a plane's CI gate, redirect allowlist, and .chain/ seals are plane-local. The shipped precedent is the CMOS Entra OIDC rhythm — EOC·00 through the P0 gates — where each ticket appended its own verifier assertion block and never mutated a prior one (the single documented exception is EOC·04, recorded in that ticket's scope doc). Deployment independence is what lets a plane rotate certificates, deploy, and revoke without cross-plane blast radius (BGXS §3.1 rationale 4).

2.4 Node interdependencies (hub-and-spoke)

The topology is hub-and-spoke with two hubs:

Nexus is the launcher hub. It renders the invariant 4-card grid falcon · swan-nest · digital-swan · ai (Canon §7), enforces entitlements, and hands the authenticated principal to the selected plane. HSOS and LCGX do not appear on the Nexus render (Canon §7); HSOS reaches its surface through governed-nav.
The Gateway is the governance-document hub and SSO shell. It hosts the estate governance stack (Canon, BSRA, BGXS, BEDL, Implementation Standards) in blackswan-gateway, and it hosts the SSO shell at access.blackswanpartnership.com. Every plane's authentication callback lives under its own subdomain (BGXS §3.1).
The five OS planes are spokes. Each has one production subdomain and callback (BGXS §3.1): falcon.…, swan-nest.…, digital-swan.…, ai.….

The identity flow across the hubs and spokes is Landing → Access → Institution Profile → Entitlements → Nexus → Plane (BGXS v0.2 §3.1; mirrored technically in BSRA §7). Three shipped CMOS precedents pin the interdependency contract:

EOC·02 — https://-only lock on production redirect entries.
EOC·03 — the ALLOWED_REDIRECT_HOSTS union that preserves prior default hosts, plus the sibling redirectAllowlistDev array for http://localhost dev entries.
EOC·04 — retention of the falcon landingActivation flag with no prior assertion block mutated.

2.5 Estate-domain overlay

Canon §11 defines seven Estate Domains as an orthogonal capability view over the deployment view of §2.1. Domains have no repos, no postures, and no deployments; every node implements a subset of Domains, and every Domain is implemented by one or more nodes. The overlay onto the topology (primary implementers per Canon §11.2):

Domain	Primary topology nodes
Identity	Gateway (SSO shell); every node consumes
Institution	PMOS, HSOS
Capital	PMOS, HSOS, CMOS
Settlement	CMOS, TREICHTEC
Risk	CMOS, HSOS, PMOS
Intelligence	AIOS (as row registry); consumed by every node
Governance	every node emits; Gateway curates estate-level evidence

The overlay does not change the Nexus 4-card render (§7) and never assigns a Domain a posture, a URL, or a Wave (Canon §11.3/§11.6).

2.6 Verifier-tail parity across nodes

The CMOS EOC/P0 verifier tail is the template every plane adopts as it matures. The canonical form (Implementation Standards §4.3) is a single stdout line:

<PLANE> <TICKET> <what-was-verified>: OK · <invariants-summary>

CMOS has exercised this across EOC·01 through EOC·04. §2 records the estate expectation that PMOS, HSOS, AIOS, and TREICHTEC adopt the same tail structure — one assertion block per ticket, prior blocks never mutated, one stdout integrity line per wave — as they leave STANDBY. For the non-CMOS planes this parity is (Prospective — first application TBD) until each ships its first verifier under this form.

Authority: BSRA §2 is authoritative on the topological view — the node roster, hub-and-spoke shape, and the domain overlay onto that shape. Canon §1 remains authoritative on the plane roster itself (six top-level planes, Nexus-is-not-a-plane, LCGX constitutional); Canon §6 on posture; Canon §7 on the Nexus render; Canon §11 on Domain names and roster; BGXS §3.1 on the gateway UX of the identity flow.

Deferred to: Wave-1 topology-doc per plane (plane-owned appendix) — the per-node deployment detail (hosts, cluster shape, region placement) remains out of scope here per §2 Non-scope.

3. Enterprise capabilities

Intent: Map Canon §11 Estate Domains onto system capabilities the estate provides.

Scope: Which Domain produces which capability, at what boundary, consumed by whom.

Non-scope: Implementation of any specific capability.

Current state: 7 Domains per Canon §11 (Identity, Institution, Capital, Settlement, Risk, Intelligence, Governance). Capability-to-plane mapping stubbed per Canon §11.2 table.

Authority: BSRA §3 is authoritative on the capability inventory. Canon §11 remains authoritative on Domain names and roster.

Deferred to: Wave-1 capability-catalogue per Domain (Domain-owned appendix).

4. Data movement

Intent: Classify inter-plane and gateway-to-plane data flows.

Scope: Flow taxonomy (event, RPC, batch, query, stream), directionality, trust boundary.

Non-scope: Specific schemas, transport protocols, serialisation formats.

Current state: SKELETON. Placeholder taxonomy: synchronous request/response, asynchronous event, batch feed, read-only projection. No flow inventory yet.

Authority: BSRA §4 will be authoritative on flow taxonomy and trust boundaries.

Deferred to: Wave-2 per-flow specification.

5. Security boundaries

Intent: Define the estate's zones of trust and the enforcement points at each boundary.

Scope: Zone taxonomy (public web · gateway · access · plane · plane-internal), enforcement type at each boundary (TLS, OIDC, RBAC, network policy).

Non-scope: Specific firewall rules, network diagrams, encryption at rest specifications.

Current state: SKELETON. Zones named. Enforcement type per boundary named. Specific policy TBD.

Authority: BSRA §5 will be authoritative on zone taxonomy. Plane security policies remain plane-owned.

Deferred to: Wave-2 zone specification and Wave-3 per-plane policy.

6. Trust zones

Intent: State the trust model between planes, between gateway and planes, and between the estate and external systems.

Scope: Trust-relationship taxonomy (peer, dependent, external, adversarial), assumptions at each relationship, break-glass conditions.

Non-scope: Specific credential exchange formats, MTLS certificate authority chains.

Current state: SKELETON. Default trust posture: gateway-to-plane trusts Entra-issued OIDC tokens only; plane-to-plane defaults to distrust; external systems always adversarial by default.

Authority: BSRA §6 is authoritative on trust posture defaults.

Deferred to: Wave-2 trust-decision matrix.

7. Identity flow

Intent: Describe end-to-end identity flow from public landing to plane session issue.

Scope: Chain of stages, artefact at each stage, principal enrichment.

Non-scope: Token formats, session cookie implementation, backend session storage.

Current state: The chain is Landing → Access → Institution Profile → Entitlements → Nexus → Plane per BGXS v0.2 §3.1. BSRA §7 mirrors this chain as the technical identity flow. Stage-artefact mapping stubbed:

Landing: no principal
Access: Entra OIDC id_token + access_token
Institution Profile: enrichment object (institution, entities, jurisdictions)
Entitlements: decision object (permitted planes + routes)
Nexus: rendered plane cards filtered by Entitlements
Plane: plane-issued session bound to Entra principal

Authority: BSRA §7 is authoritative on the technical identity flow. BGXS §3.1 is authoritative on the gateway UX of the flow.

Deferred to: Wave-1 stage-artefact specification (jointly owned with BGXS).

8. Event architecture

Intent: Classify the estate's event-driven surfaces (CC-era event ceiling per Canon §6).

Scope: Event-type taxonomy, event-emission rules, event-consumption rules, event-schema evolution policy.

Non-scope: Kafka partition counts, topic names, consumer group naming.

Current state: SKELETON. Constraint from Canon §6: CC-era event-type ceiling frozen at 8. Beyond this, TBD.

Authority: BSRA §8 is authoritative on event-type ceilings and taxonomy. Plane event schemas remain plane-owned.

Deferred to: Wave-2 event-type inventory per plane.

9. Integration patterns

Intent: Enumerate the integration patterns the estate uses (or does not use).

Scope: Pattern names, when each is appropriate, when each is forbidden.

Non-scope: Specific integration implementations.

Current state: SKELETON. Preliminary list: synchronous facade, event-driven propagation, batch reconciliation, read-model projection, outbox / inbox, saga (forbidden — no plane owns cross-plane sagas).

Authority: BSRA §9 is authoritative on which patterns are canonical and which are forbidden.

Deferred to: Wave-2 per-pattern specification.

10. AI interaction model

Intent: Describe how AI capabilities are surfaced across the estate.

Scope: AIOS-as-registry model per Canon §2, per-plane AI-row consumption, AI-substrate treatment per Canon §11 Intelligence Domain, AI in the ChatGPT/Codex/CI-agent sense (not model architecture).

Non-scope: Model selection, prompt engineering, inference cost.

Current state: AIOS is the row-registry (24 rows) per Canon §2. Each plane may consume rows without becoming AIOS. Intelligence Domain per Canon §11.2 is the capability view.

Authority: BSRA §10 is authoritative on AI-surfacing patterns. Canon §2 remains authoritative on the row-vs-plane hierarchy.

Deferred to: Wave-2 per-plane AI-row consumption pattern.

11. Azure deployment topology

Intent: Describe the Azure deployment shape (subscription, resource groups, regions, Entra tenant relationship).

Scope: Subscription topology, region strategy, Entra tenant configuration reference.

Non-scope: Terraform / Bicep specifics, per-plane infrastructure code.

Current state: SKELETON. Constraint from Canon §4: Azure + Entra + PostgreSQL canonical. Specific subscription and region topology TBD.

Authority: BSRA §11 is authoritative on Azure topology decisions. Plane-level infrastructure remains plane-owned.

Deferred to: Wave-1 Azure topology decision + Wave-3 per-plane infrastructure code.

12. Service contracts

Intent: Define the shape of inter-service contracts (both intra-plane and inter-plane).

Scope: Contract format (OpenAPI, AsyncAPI, protobuf), versioning policy, backward-compatibility rules, deprecation policy.

Non-scope: Specific service endpoints.

Current state: SKELETON. Preliminary: OpenAPI 3.1 for HTTP surfaces, AsyncAPI for event surfaces, semantic versioning per contract, backward-compatibility required within major version.

Authority: BSRA §12 is authoritative on contract format and versioning discipline.

Deferred to: Wave-2 per-service contract inventory.

13. Resilience patterns

Intent: Enumerate resilience patterns the estate expects planes to implement.

Scope: Pattern names (timeout, retry with backoff, circuit breaker, bulkhead, fallback), when each applies.

Non-scope: Specific library implementations.

Current state: SKELETON. Pattern names listed. Default posture: every cross-plane call MUST have timeout + retry; circuit breaker required at gateway boundaries.

Authority: BSRA §13 is authoritative on required patterns per boundary.

Deferred to: Wave-2 per-boundary resilience-pattern specification.

14. Observability

Intent: Define the observability surface the estate expects.

Scope: Three pillars (logs, metrics, traces), OpenTelemetry as the canonical instrumentation per Canon §4, cross-plane trace continuity.

Non-scope: Specific dashboards, alerting thresholds.

Current state: SKELETON. Canonical: OpenTelemetry SDK per plane, W3C trace context propagation across plane boundaries. Log format TBD. Metric ceiling TBD.

Authority: BSRA §14 is authoritative on instrumentation choice and trace continuity.

Deferred to: Wave-2 log format + metric ceiling + Wave-3 dashboard standards.

15. Disaster recovery and business continuity

Intent: State the recovery-time and recovery-point posture the estate assumes.

Scope: RTO/RPO defaults per plane class (constitutional LCGX, OS planes, gateway, AIOS registry), backup discipline, DR-drill cadence.

Non-scope: Specific backup implementations, DR test scripts.

Current state: SKELETON. Estate is STANDBY · IN-MEMORY ONLY · HOLD · NO-GO, so RTO/RPO are moot in production terms. Discipline still required for pre-production data (fixtures, artifacts, .chain/ files). Preliminary posture: .chain/ files MUST be backed up before any Wave transition.

Authority: BSRA §15 is authoritative on posture defaults. Plane-level DR remains plane-owned.

Deferred to: Post-HOLD RTO/RPO commitments.

16. What BSRA is NOT

Not the constitutional governance document (Canon is).
Not the public gateway experience specification (BGXS is).
Not the visual token system (BEDL is).
Not implementation standards (Implementation Standards v0.1 is).
Not authoritative on any plane's internal architecture — planes remain sponsor-owned deployment units per Canon §1.
Not a compliance framework — regulatory frameworks per plane per jurisdiction (Canon §4 tech stack + BSRA §5 zones + BSRA §11 Azure topology feed compliance, but BSRA is not itself a compliance document).

17. Graduation criteria (v0.x SKELETON → v1.0 FROZEN)

BSRA graduates to v1.0 FROZEN when every §2–§15 section has:

Removed its Deferred to: Wave-N marker
Populated its Current state with substantive content (not SKELETON stub)
Passed one external-review cycle
Been consumed by at least one shipped implementation (per plane or per Domain)

Until all 14 sections graduate, BSRA remains in v0.x SKELETON status. Sections may graduate independently — the version bumps as sections mature.

18. Sponsor line

BLACKSWAN Reference Architecture · v0.1 — SKELETON · authored 2026-07-11 · sponsor Mamadou Ly, Founder, Managing Partner & CEO.