Skip to content

adr

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

adr

README.md

Architectural Decision Records (ADRs)

This directory contains all architectural decisions made during the development of logfile-mcp-server.

What are ADRs?

Architectural Decision Records document significant architectural choices made during project development. Each ADR captures:

  • Context: The problem or situation requiring a decision
  • Decision: The choice that was made
  • Consequences: The positive, negative, and neutral outcomes

ADRs help future contributors understand why decisions were made, not just what was implemented.

Active ADRs

ID Title Status Date
ADR-01 General Architectural Principles Accepted 2025-07-28
ADR-02 Adopt UV for Python Package Management Accepted 2025-07-28
ADR-03 Change chunk_size from Bytes to Lines Accepted 2025-07-28
ADR-04 Architectural Pattern Consistency Prevention Accepted 2025-07-28
ADR-05 Test Database Consolidation Accepted 2025-07-31
ADR-06 MCP Server Integration Architecture Accepted 2025-07-31
ADR-08 Systematic Test Coverage Assessment Accepted 2025-08-02

ADR Quick Reference

Development & Tooling

  • ADR-02: Why we use UV instead of pip for package management (10-100x faster)
  • ADR-08: Systematic test coverage process after major milestones

Architecture & Patterns

  • ADR-01: Foundational architectural principles (separate models, single process, modular design)
  • ADR-04: Why configuration must use dependency injection (no hardcoded patterns)
  • ADR-06: Single entry point with dual transport support (stdio + network)

Testing & Data

  • ADR-05: Shared test database factory pattern to eliminate duplication
  • ADR-03: Why chunk_size represents lines, not bytes (log entry integrity)

How to Use ADRs

When Reading Code

  • Wondering why a specific approach was chosen? Check relevant ADRs
  • ADRs are referenced in code comments and documentation
  • Use the Quick Reference above to find decisions by topic

When Making Changes

  • If you're changing architecture, create a new ADR (don't modify existing ones)
  • ADRs document the rationale, helping future contributors understand trade-offs
  • See DEVELOPMENT.md for ADR lifecycle rules

ADR Lifecycle Rules

  1. Never modify accepted ADRs - They're historical records
  2. Create new ADRs when decisions change - Mark old ADRs as "Superseded by ADR-XX"
  3. Reference ADRs in code comments and documentation
  4. Update status only (Proposed → Accepted, Accepted → Superseded)

ADR Naming Convention

Format: ADR_YYYYMMDD_NN_description.md

Examples:

  • ADR_20250728_01_general.md - General principles from July 28, 2025
  • ADR_20250731_06_mcp_server_integration.md - MCP server decision from July 31, 2025

Benefits:

  • Chronological ordering (date-based)
  • Easy to find latest decisions
  • Sequential numbering prevents conflicts

Creating New ADRs

See DEVELOPMENT.md for ADR template and creation guidelines.

Quick template:

# ADR_YYYYMMDD_NN: [Title]

## Status
Proposed | Accepted | Deprecated | Superseded by ADR-XX

## Date
YYYY-MM-DD

## Context
What problem are we solving? What constraints exist?

## Decision
What did we decide to do?

## Consequences

### Positive
- Benefits of this decision

### Negative
- Drawbacks or costs

### Neutral
- Neither good nor bad but worth noting

## References
- Links to docs, commits, discussions

Related Documentation

See Also