Skip to content

Architecture Decision Records

This directory contains all Architecture Decision Records (ADRs) for the project.

What is an ADR?

An Architecture Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences. For more information about ADRs, see the template.

Decision Log

ADR # Title Status Date Summary
ADR-0001 Record Architecture Decisions ACCEPTED 2025-07-05 Establishes the use of ADRs for documenting architectural decisions
ADR-0002 Project Structure and Development Tools ACCEPTED 2025-07-05 Defines project layout with server/{libs,services,tools}, standardizes development tools (mypy, ruff, pytest, uv) and build processes
ADR-0003 Event-Driven Architecture Implementation PROPOSED 2025-07-05 Implements event-driven communication between services using message brokers for scalability and resilience
ADR-0004 Service Boundary Definition PROPOSED 2025-07-05 Defines domain-driven service boundaries for budget, cms, issues, and journal services with clear responsibilities
ADR-0005 Authentication and Authorization Strategy PROPOSED 2025-07-05 Establishes centralized IAM with JWT tokens, RBAC, and security measures for authentication and authorization
ADR-0006 Data Persistence Strategy PROPOSED 2025-07-05 Defines multi-faceted data persistence approach with service-specific databases, caching, and optimization strategies
ADR-0007 Testing Strategy PROPOSED 2025-07-05 Outlines comprehensive testing approach across unit, integration, and end-to-end levels for reliable service delivery
ADR-0008 CI/CD Platform Selection - GitHub Actions with Self-Hosted Runners ACCEPTED 2025-07-06 Establishes GitHub Actions with self-hosted runners as the CI/CD platform for simplified maintenance and efficient workflows
ADR-0009 Database Migration Strategy PROPOSED 2025-07-06 Defines forward-only migration approach with backup-based recovery for Release 0.1, with planned evolution to bidirectional migrations
ADR-0010 AI Tool Registry and Manifest Discovery PROPOSED 2026-02-14 Config-seeded tool registry with content-hash catalog revisions and run pinning for reproducibility
ADR-0011 AI Run Orchestration Model PROPOSED 2026-02-14 Async run orchestration with SSE streaming, cancellation, pinned tool catalogs, and safety limits
ADR-0012 Embedding Factory vs Vector Index Ownership PROPOSED 2026-02-14 Split embedding ownership along domain boundaries: AI owns conversation vectors, KB owns document vectors
ADR-0013 Web Ingestion in AI Service PROPOSED 2026-02-14 Basic web ingestion (HTML/PDF) in AI service for V1 with clear migration path to KB delegation
ADR-0014 Ollama Local Model Provider PROPOSED 2026-02-14 Ollama integration for local model inference with provider abstraction
ADR-0015 Centralized Embedding Store PROPOSED 2026-02-14 Centralized embedding storage with domain-scoped access for vector search
ADR-0016 Issue Tracking Service Architecture PROPOSED 2026-02-17 Eight architectural decisions for Space-scoped catalogs, LexoRank ordering, auto-walk transitions, boards, hierarchy, EAV custom fields, soft delete, and search delegation
ADR-0017 Background Job Strategy PROPOSED 2026-03-02 Lightweight in-process TaskScheduler with interval and cron scheduling for periodic background work
ADR-0019 Remove Legacy Application Generation ACCEPTED 2026-07-27 Establishes server/, ui/, and the current Compose topology as canonical and removes the obsolete top-level generation

Statuses

  • PROPOSED: A decision is being considered but hasn't been approved yet
  • ACCEPTED: A decision has been accepted and is currently active
  • DEPRECATED: A decision is no longer valid but wasn't explicitly replaced
  • SUPERSEDED: A decision has been replaced by a newer decision (reference the new ADR)

Creating a New ADR

  1. Copy template.md to create a new file named NNNN-title-with-dashes.md
    • Use the next available number in sequence for NNNN
    • Use lowercase letters and dashes for the title
  2. Fill in the template
  3. Add an entry to the Decision Log table above
  4. Submit a pull request for review

File Name Convention

ADR files should be named using the following format: NNNN-title-with-dashes.md

  • NNNN is a sequential number with leading zeros (0001, 0002, etc.)
  • title-with-dashes is a brief hyphen-separated title

Example: 0001-record-architecture-decisions.md