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)Accepted2026-02-20
ADR-0004CopilotKit v1 API with v2 Migration PlanSuperseded by ADR-00132026-02-20
ADR-0005STATE_SNAPSHOT over STATE_DELTA for AG-UIAccepted2026-02-20
ADR-0006PEPPOL Verify as Synchronous REST APIAccepted2026-02-20
ADR-0007Belgian Data Layer, Country Routing, and PEPPOL UIImplemented2026-02-23
ADR-0008Raw SQL via SQLAlchemy text() for Database AccessAccepted2025-12-15
ADR-0009Minimal Error Handling with Silent Recovery for PoCAccepted2025-12-15
ADR-0010React useState/useEffect for Frontend State ManagementAccepted (PoC) — effectively superseded by TanStack React Query v52025-12-15
ADR-0011Authentication Deliberately Deferred for PoCSuperseded 2026-04-18 — Keycloak OIDC implemented2025-12-15
ADR-0012Hybrid Scraping Tool Selection per Data SourceImplemented2026-01-15
ADR-0013CopilotKit v2 MigrationAccepted (supersedes ADR-0004)2026-02-01
ADR-0014Neo4j Knowledge Graph (CQRS Read Layer)Implemented2026-02-25
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 RequirementsAccepted2026-03-20
ADR-0019Multi-Agent OSINT Pipeline with Country RoutingAccepted2026-03-21
ADR-0020EBA Risk Matrix with Weighted-Max AggregationAccepted2026-03-22
ADR-0021Evidence Bundle System for EU AI ActAccepted2026-03-22
ADR-0022Neo4j Knowledge Graph with 20-Step ETLAccepted2026-03-25
ADR-0023PostgreSQL Row-Level Security for Multi-Tenant IsolationAccepted2026-03-25
ADR-0024Entity Matching with Blocking Keys and Trust-Weighted SurvivorshipAccepted2026-03-26
ADR-0025Network Intelligence Hub with ReactFlowAccepted2026-03-28
ADR-0026Prompt Centralization with DB-First RegistryAccepted2026-03-29
ADR-0027GoAML Export with Three-Layer PipelineAccepted2026-03-20
ADR-0028White-Label Branding with WCAG AA EnforcementAccepted2026-03-08
ADR-0029Cost-Optimized Model Tiers for Agent FleetAccepted2026-03-31
ADR-0030Social Intelligence via BrightData MCPAccepted2026-04-01
ADR-0031Regulatory Segment Profiles with Declarative YAML CompilerAccepted2026-04-02
ADR-0032Circuit Breakers for OSINT Pipeline ResilienceAccepted2026-04-06
ADR-0033Document Gap Analysis EngineAccepted2026-04-02
ADR-0034Multi-Country Registry ArchitectureAccepted2026-04-03
ADR-0035Atlas Reference Documentation within DocusaurusAccepted2026-04-07
ADR-0036PII Classification ArchitectureAccepted2026-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 CompaniesAccepted2026-04-17
ADR-0042Czech Regulatory + Professional Registry CoverageAccepted2026-04-17
ADR-0043Cross-Country Registry Parity (decoders, director shapes, KBO packed-layout fix)Accepted2026-04-17
ADR-0044Withdrawn during review — number reservedWithdrawn—
ADR-0045Sanctions False-Positive Suppression (evidence-based, tenant-scoped, always visible)Proposed2026-04-18
ADR-0046NBB CBSO CSV Endpoint Degradation and Honest Data-Gap SurfacingAccepted2026-04-22
ADR-0047Async Docling Extraction (Option B — background activity, idempotent MinIO writes)Accepted2026-04-23
ADR-0048Financial Analysis Agent (ratios + distress models + peer benchmarks)Accepted2026-04-22
ADR-0049Cross-Reference Registration-Number Identity-Mismatch DetectionAccepted2026-04-22

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