Architecture Documentation

Technical design, decisions, and system capabilities for Eko.

Documents

Overview

High-level system architecture: V2 fact engine data flow, database schema (32+ active tables), queue system (12 message types), workers, and AI model router.

Decisions

Architecture Decision Records (ADRs) capturing the "why" behind key design choices:

V2 Fact Engine:

  • ADR-013: Fact-First Architecture
  • ADR-014: Multi-Pipeline Convergence
  • ADR-015: Schema-Driven Fact Extraction
  • ADR-016: Cost-Bounded AI with Model Routing
  • ADR-017: Challenge Answer Isolation

vNext (historical):

  • ADR-009: Global URL Library
  • ADR-010: Write-Through Compatibility
  • ADR-011: History Gating by Subscription
  • ADR-012: URL Policy Enforcement

V1 (historical):

  • ADR-001 through ADR-008: URL-scoped execution, change-first output, scheduling, snapshots, rendering, non-substitutive intelligence, cost model, no prediction

Tools

V2 runtime capabilities: news ingestion, AI fact extraction, 4-phase validation, 20+ evidence APIs, image resolution, challenge generation, model router, observability.

Table Flow Diagram

Visual diagram of the V2 fact challenge system: 32 active tables, 6-phase data flow (ingestion → extraction → validation → challenge generation → sessions → feed), queue message routing.

Model Code Isolation

Model runtime isolation patterns for AI provider switching and cost control.

Monorepo Structure

Codebase layout with file counts, package dependencies, and directory tree.

Schema Naming Contracts

Database and API naming conventions for consistency across the codebase.

Brand Library Schema (V1 legacy)

V1 schema for curated brand identity data. Superseded by V2 brands, domains, and brand_categories tables.