Skip to content

Architecture Decision Records

Architecture Decision Records (ADRs) capture the key technical decisions made during the development of GEPA-ADK. Each ADR explains the context, decision, and consequences of a particular architectural choice.

Purpose

ADRs serve as living documentation that:

  • Explains why design decisions were made
  • Provides context for future developers
  • Evolves as the project grows
  • Guides implementation of new features

How to Use ADRs

When implementing a feature:

  1. Check which ADRs apply to your work
  2. Follow the patterns and principles documented
  3. If a new decision is needed, create a new ADR

ADR Index

ADR Title Status Summary
ADR-000 Hexagonal Architecture Accepted Ports & adapters pattern for dependency isolation
ADR-001 Async-First Architecture Accepted All I/O operations use async/await
ADR-002 Protocol-Based Interfaces Accepted Use typing.Protocol for structural subtyping
ADR-005 Three-Layer Testing Accepted Contract, unit, and integration test layers
ADR-006 External Library Integration Accepted Isolate external dependencies in adapters
ADR-008 Structured Logging Accepted Use structlog for observable logging
ADR-009 Exception Hierarchy Accepted All exceptions inherit from EvolutionError
ADR-010 Docstring Quality Accepted Google-style docstrings with 95%+ coverage
ADR-011 Cross-Platform Encoding Accepted Encoding-safe logging for Windows cp1252 consoles
ADR-012 Multi-Agent Component Addressing Accepted Dot-separated qualified names for multi-agent evolution

Core Principles

The ADRs establish five core principles that guide all development:

  1. Hexagonal Architecture (ADR-000): Strict layer boundaries between domain, ports, adapters, and engine
  2. Async-First Design (ADR-001): All I/O-bound operations must be async
  3. Protocol-Based Interfaces (ADR-002): Use protocols for flexibility without inheritance
  4. Three-Layer Testing (ADR-005): Contract, unit, and integration tests for every feature
  5. Observability & Documentation (ADR-008, 009, 010): Structured logging, exception handling, and docstring quality