Skip to main content

Architecture Decision Records

Architecture Decision Records (ADRs) capture significant architectural decisions made during the development of Trust Relay. Each ADR documents the context that motivated a decision, the decision itself, and its consequences -- both positive and negative.

ADRs are immutable once accepted. If a decision is superseded, the original ADR is marked as such and a new ADR is created.

ADR Registry​

ADRTitleStatusDate
ADR-0001PydanticAI + AG-UI + CopilotKit as AI LayerAccepted2026-02-20
ADR-0002Temporal for Workflow OrchestrationAccepted2026-02-20
ADR-0003AGUIAdapter on FastAPI (not standalone AGUIApp)Accepted2026-02-20
ADR-0004CopilotKit v1 API with v2 Migration PlanSuperseded by ADR-00132026-02-20
ADR-0005STATE_SNAPSHOT over STATE_DELTA for Tier 1Accepted2026-02-20
ADR-0006PEPPOL Verify as Synchronous REST APIAccepted2026-02-20
ADR-0007Belgian Data Layer, Country Routing & PEPPOL UIImplemented2026-02-23
ADR-0008Raw SQL via SQLAlchemy text() for Database AccessPartially Superseded 2026-04-18 — ORM Repository pattern adopted for new code; existing text() usage retained as acceptable technical debt2026-02-24
ADR-0009Minimal Error Handling with Silent Recovery for PoCAccepted (PoC), Migration In Progress2026-02-24
ADR-0010React useState/useEffect for Frontend State ManagementAccepted (PoC)2026-02-24
ADR-0011Authentication Deliberately Deferred for PoCSuperseded 2026-04-18 — Keycloak OIDC implemented2026-02-24
ADR-0012Hybrid Scraping Tool Selection per Data SourceAccepted2026-02-24
ADR-0013CopilotKit v2 MigrationAccepted2026-02-28
ADR-0014Native Bi-Temporal Graph (Drop Graphiti)Accepted2026-03-02
ADR-0015Session-Based Investigation DiagnosticsAccepted2026-03-08
ADR-0016Shared Regulatory Corpus Without Tenant RLSAccepted2026-03-17
ADR-0017Trust Capsule Cryptographic ArchitectureAccepted2026-03-19
ADR-0018Dynamic Document Requirements — Pre-Investigation ResolutionAccepted2026-04-02
ADR-0019Multi-Agent OSINT Pipeline with Country RoutingAccepted2026-02-20 (date decision was originally made)
ADR-0020EBA Risk Matrix with Weighted-Max AggregationAccepted2026-03-31 (date decision was originally made)
ADR-0021Evidence Bundle System for EU AI Act Chain-of-Thought CaptureAccepted2026-03-06 (date decision was originally made)
ADR-0022Neo4j Knowledge Graph with Sequential ETL PipelineAccepted2026-02-25 (date decision was originally made)
ADR-0023PostgreSQL Row-Level Security for Multi-Tenant IsolationAccepted2026-03-08 (date decision was originally made)
ADR-0024Entity Matching with Blocking Keys and Trust-Weighted SurvivorshipAccepted2026-03-31 (date decision was originally made)
ADR-0025Network Intelligence Hub with ReactFlow Three-Perspective VisualizationAccepted2026-03-30 (date decision was originally made)
ADR-0026Prompt Centralization with DB-First Registry and Filesystem FallbackAccepted2026-03-17 (date decision was originally made)
ADR-0027GoAML Export with Three-Layer Pipeline and Country ProfilesAccepted2026-03-21 (date decision was originally made)
ADR-0028White-Label Branding with Logo Palette Extraction and WCAG AA EnforcementAccepted2026-03-08 (date decision was originally made)
ADR-0029Cost-Optimized Model Tiers for Agent FleetAccepted2026-03-31 (date decision was originally made)
ADR-0030Social Intelligence via BrightData MCP ExpansionAccepted2026-04-05
ADR-0031Regulatory Segment Profiles with Declarative YAML CompilerAccepted2026-04-06
ADR-0032Circuit Breakers for OSINT Pipeline ResilienceAccepted2026-04-06
ADR-0033Document Gap Analysis EngineAccepted2026-04-06
ADR-0034Multi-Country Registry ArchitectureAccepted2026-04-06
ADR-0035Atlas Reference Documentation within Trust Relay DocusaurusAccepted2026-04-06
ADR-0036PII Classification with Hybrid Annotations and Generated ManifestAccepted2026-04-07
ADR-0037Shared Python Packages for Atlas IntegrationAccepted2026-04-11
ADR-0038Shell Company Detection via Establishment Address ComparisonAccepted2026-04-14
ADR-0039Resilience Rollout Completion + KBC Acquiring Gap SignalsAccepted2026-04-14
ADR-0040Observability Metrics + Breaker State PersistenceAccepted2026-04-14
ADR-0041Pure-Mailbox Detection for Shell Companies Without Operational FootprintAccepted2026-04-17
ADR-0042Czech Regulatory + Professional Registry CoverageAccepted2026-04-17
ADR-0043Cross-Country Registry Parity — Decoders, Director Shapes, and the KBO Packed-Layout BugAccepted2026-04-17
ADR-0044(Withdrawn during review — number reserved, never reused)Withdrawn—
ADR-0045Sanctions False-Positive Suppression — Evidence-Based, Tenant-Scoped, Always VisibleAccepted (implemented 2026-04-22)2026-04-18
ADR-0046NBB CBSO CSV endpoint degradation and honest data-gap surfacingAccepted2026-04-22
ADR-0047Async Docling extraction (Option B)Accepted2026-04-23
ADR-0048Financial Analysis AgentAccepted2026-04-22
ADR-0049Cross-reference registration-number identity-mismatch detectionAccepted2026-04-22
ADR-0050Enforce RLS by running the app as a non-superuser roleAccepted2026-06-12
ADR-0051Tenant-scoped session selection for RLS-enforced accessAccepted2026-06-13
ADR-0052Dashboard Age filter defaults to "Any", not "Today"Accepted2026-06-15
ADR-0053UBO ownership computation engine (multi-path summation)Accepted2026-06-15
ADR-0054UBO via control — ControlEdge dimension (binary reachability)Accepted2026-06-15
ADR-0055UBO Senior Managing Official (SMO) fallbackAccepted2026-06-15
ADR-00561-to-many person/UBO verification modelAccepted2026-06-15
ADR-0057Min-2-independent-source verification gate (gate, not score)Accepted2026-06-15
ADR-0058Central register is cross-check only (require ≥1 non-central source)Accepted2026-06-15
ADR-0059Block approval on open UBO discrepancy + discrepancy SAR lifecycleAccepted2026-06-15
ADR-0060NaturalPerson AMLR fields — plural nationality, PEP classification/RCA, place_of_birthAccepted2026-06-16
ADR-0061Role-based LegalArrangement model + separate UBO determination pathAccepted2026-06-16
ADR-0062Typed SubjectEntity + PurposeProfile modelsAccepted2026-06-16
ADR-0063Typed persisted ScreeningResult (ongoing-monitoring evidence trail)Accepted2026-06-16
ADR-0064DB-enforced audit_events immutability (retention-first)Accepted2026-06-16
ADR-0065Dissolved-entity onboarding block-by-default (audited override)Accepted2026-06-16
ADR-0066Live risk-paced UBO re-screening + general-population monitoringAccepted2026-06-16
ADR-0067Fail-Closed Compliance Outputs & the "Not Assessed" ContractAccepted2026-06-26
ADR-0068Country-Capability Registry & Honest "Not Assessed for X"Accepted2026-06-26
ADR-0069Regulator-Ready Case-Pack Export & RetentionAccepted2026-06-26
ADR-0070Maker-checker / four-eyes control for high-risk decisionsAccepted2026-06-26
ADR-0071SAR/STR lifecycle + tipping-off controlsAccepted2026-06-26
ADR-0072EU AI Act conformity record (system-level, data-driven, honest)Accepted2026-06-26
ADR-0073Round-2 entity-resolution & signal hardening (name-collision guard, vertical/licence consistency, financials-ingestion gap, payment-account-outside-licence)Accepted2026-06-27
ADR-0074Role-based access control (RBAC) enforcement, phased (log-first)Accepted2026-06-27
ADR-0075Document-content adverse analysis (uploaded documents can RAISE risk)Accepted2026-06-28
ADR-0076SSO federation (per-tenant IdP brokering on Keycloak)Proposed (design only — NOT implemented)2026-06-28
ADR-0077Multi-provider adverse-media retrieval with native-language recallAccepted2026-06-28
ADR-0078Alias / brand / group expansion of the screened entity setAccepted2026-06-28
ADR-0079Estonian company financials via RIK e-Äriregister open dataAccepted2026-06-28
ADR-0080Signal.FINANCIAL_STATEMENTS jurisdiction-gated capabilityAccepted2026-06-28
ADR-0081Super-admin tenant impersonation over SSE via validated query parameterAccepted2026-06-30
ADR-0082Post-validation calibration & integrity hardening (OB Holding adversarial run)Accepted2026-06-30

The Docusaurus sidebar auto-includes every generated ADR page; this table is the hand-maintained landing index. Titles/status/date mirror the canonical docs/adr/ register (regenerated 2026-07-02). ADR-0044 was withdrawn during review — the number is reserved and never reused.

ADR Template​

New ADRs follow this structure:

# ADR-NNNN: Title

**Date**: YYYY-MM-DD
**Status**: Proposed | Accepted | Implemented | Superseded by ADR-XXXX
**Deciders**: Names

## Context
Why this decision is needed.

## Decision
What was decided.

## Consequences
### Positive
### Negative
### Neutral

## Alternatives Considered