Skip to content

ADR-010: Six Pillars Architecture for v1.5.0

Date: 2026-04-22 Status: Accepted Decision-makers: FCC core maintainers · SFBI (SAFe-FCC Bridge Interpreter) persona Consulted: Research Center — PI-2026-Q2 close alignment · AURORA, AOME, CONSTEL, PAOM (consumer readiness) Informed: All ecosystem partners

Context and Problem Statement

The v1.4.1 → v1.5.0 plan began as a multi-release session arc with five strategic ambitions competing for priority:

  • Real canonical seed data (so constellation verticals ship with real ICD-11 / FIGI / CIM / NIEM content, not synthetic placeholders).
  • GraphRAG over the FederatedKnowledgeGraph (so semantic retrieval can use graph structure, not just flat embeddings).
  • Real-time multi-user collaboration (so authoring workflows can coexist across collaborators without central-lock contention).
  • Advanced federation with bidirectional namespace sync (so cross-project entity resolution can propagate changes in both directions).
  • Performance optimization (so hot paths don't regress as the persona catalog + knowledge-graph footprint grow).
  • Internationalization scaffolding (so FR/ES/DE readers are not second-class).

Each ambition was large enough on its own to warrant a minor release. Shipping them serially would take six releases and delay the stable bridge promotion of POLARIS and LYRA. Shipping them in parallel required a coherent narrative — "what is v1.5.0?" — and explicit cross-pillar coordination so no pillar blocked another.

The problem was whether to sequence the six ambitions across six releases or deliver them as a single big-bang release with one coordinated story.

Decision Drivers

  • Narrative coherence. v1.5.0 needs a single answer to "what did this release add?" that consumers can reason about.
  • Cross-pillar dependencies. Pillar B (GraphRAG) depends on Pillar E (federation) stability; Pillar D (CRDT) depends on Pillar F (performance) — sequencing would stall multiple pillars.
  • Consumer readiness. PAOM, AOME, and CONSTEL had signalled they could absorb a coordinated big-bang release but could not absorb six consecutive minors.
  • Owner-approval gating. Seed data (Pillar A) and i18n translations (Pillar C) have legal and budget implications that must stay gated; the release can land their infrastructure even if the content stays behind a gate.
  • Plan completion deadline. The v1.4.1 → v1.5.0 plan is a five-stage arc; v1.5.0 is the terminal stage.

Considered Options

  1. Serial delivery (six releases v1.5.0 … v1.5.5). Low risk per release but 6× coordination + changelog overhead.
  2. Three-pair delivery (v1.5.0 + v1.6.0 + v1.7.0). Split by affinity: GraphRAG+federation, CRDT+performance, seed+i18n. Better narrative per release but loses the "six pillars" story.
  3. Big-bang v1.5.0 with owner-approval gating on Pillars A and C. All six pillars land in one release. Owner-approval-gated pillars land their infrastructure (Makefile targets, scaffolding, plugins) but defer the content-level actions (seed downloads, translations) until owner greenlight.
  4. Skip Pillars A + C entirely. Ship only the four non-owner-gated pillars. Incomplete story.

Decision

We adopt option 3: a big-bang v1.5.0 with six coordinated pillars, with Pillar A (seed data) and Pillar C (i18n translations) owner-approval-gated at the content level but fully scaffolded at the infrastructure level.

Pillar A — Real canonical seed data (owner-approval-gated). publications/scripts/seed_canonical.py (~300 LoC) with per-vertical seeders for ICD-11 (medical), FIGI (financial), NAICS (insurance), IEC 61970 CIM (energy), eIDAS + DCAT-US 3.0 (government). dry_run= True DEFAULT produces manifest.json with source URLs + licenses, does NOT download. Actual download requires --i-understand-external-license-implications flag; RuntimeError otherwise. make seed-canonical Makefile target (dry-run default).

Pillar B — GraphRAG over KnowledgeGraph + FederatedKG. src/fcc/rag/graphrag.py (682 LoC). GraphRAG class, GraphRAGResult frozen dataclass, assemble_context() helper. Pipeline: semantic retrieval → BFS graph-walk → zachman-cell filter (match-or-ancestor semantics) → persona-aware 3-signal deterministic scoring → LYRA augmentation via sentinel-guarded get_lyra_bridge(). Promoted to fcc.api.rag. See ADR-011.

Pillar C — i18n infrastructure (translations owner-approval-gated). mkdocs-static-i18n plugin configured for FR/ES/DE. i18next + react-i18next in frontend. frontend/src/i18n/locales/{en,fr,es,de}/ common.json. EN baseline; FR/ES/DE carry {{TRANSLATE_*}} markers pending owner-approved translation cycle. docs/i18n/glossary.csv flags R.I.S.C.E.A.R., Zachman, OTEL terms as "do not translate."

Pillar D — Real-time WebSocket multi-user collaboration. src/fcc/collaboration/crdt.py (507 LoC) + multi_user.py (458 LoC). CRDTBackend Protocol, InMemoryBackend (LWW + Lamport clock), optional YPyBackend. MultiUserSession (CRDT + presence + UXBus events) + MultiUserEngine (multi-tenant routing). CollabWebSocketBridge on /collab/{session_id} multiplex path. frontend/src/pages/Admin/ CollabLive.tsx 2-pane admin demo. See ADR-012.

Pillar E — Advanced federation (bidirectional namespace sync). src/fcc/federation/bidirectional.py (~400 LoC). BidirectionalSync extends ChangeTracker with per-namespace conflict policy (LWW / MANUAL_MERGE / DOMAIN_OWNER_AUTHORITY). Federation health dashboard at GET /api/v1/federation/health. See ADR-013.

Pillar F — Performance optimization. LRU caching on PersonaRegistry.get (size 512), KnowledgeGraph.get_node/get_edge (size 1024), ecosystem registry loader. clear_caches() for test isolation. src/fcc/search/incremental.py (~250 LoC) — IncrementalSearchIndex with differential update (only re-embed changed docs via SHA256 checksum). src/fcc/compliance/memoization.py (~150 LoC) — @memoize_compliance_replay decorator (scenario_id + content-SHA256 cache key, size 256). Benchmark harness scripts/benchmark_v145_vs_v144.py reports mean/p50/p95/p99; ≥20% improvement target met.

Cross-pillar coordination: all six ship together with a shared test-count envelope (+220 tests), a shared version bump (1.4.4 → 1.5.0, Helm 0.3.4 → 0.4.0), and a shared CHANGELOG section that maps each pillar back to its plan identifier.

Consequences

Positive

  • Single narrative. "v1.5.0 is the six-pillars release" is a story any consumer can remember.
  • Compressed coordination. One release train instead of six.
  • Owner-approval gating preserves legal posture. Seed data downloads and FR/ES/DE translation commits stay gated at the content level while infrastructure lands.
  • Plan completion. The v1.4.1 → v1.5.0 plan closes in five stages as planned.

Negative

  • Release-note density. The v1.5.0 CHANGELOG entry is unusually large (~150 lines). Mitigated by sub-section-per-pillar structure.
  • Cross-pillar debugging complexity. A regression could come from any of six pillars. Mitigated by 100% line + branch coverage on all new modules and deterministic test ordering.
  • Owner-gated work visible but unexecuted. Pillar A (seed downloads) and Pillar C (FR/ES/DE translation commits) ship as scaffolded-but-not-activated surfaces; reviewers must understand the gating rationale. Mitigated by CHANGELOG §Owner-approval-gated section.

Confirmation

  • 220+ new tests across the six pillars land green in CI; 100% line
  • branch coverage on all new modules.
  • Helm 0.3.4 → 0.4.0 bump + image tag 1.4.4 → 1.5.0 in charts/fcc/values.yaml.
  • src/fcc/__init__.py → 1.5.0.
  • docs/migrations/v1.5.0-api-additions.md documents the POLARIS + LYRA bridge promotion that accompanies the six pillars.

References

  • CHANGELOG [1.5.0] — 2026-04-22 — canonical delivery record
  • src/fcc/rag/graphrag.py — Pillar B
  • src/fcc/collaboration/crdt.py + multi_user.py — Pillar D
  • src/fcc/federation/bidirectional.py — Pillar E
  • src/fcc/search/incremental.py + compliance/memoization.py — Pillar F
  • publications/scripts/seed_canonical.py — Pillar A
  • mkdocs.yml + frontend/src/i18n/ — Pillar C
  • ADR-011 (GraphRAG detail), ADR-012 (CRDT detail), ADR-013 (bidirectional federation detail)
  • ADR-008 — POLARIS + LYRA stable-bridge promotion (accompanies v1.5.0)
  • ADR-009 — universal-services coordination doc (shipped with v1.5.0)
  • New personas: KGSE, LTAS, DAR (15 new across the v1.4.1 → v1.5.0 arc)