Skip to content

Architecture Decision Records (ADRs)

ADRs document significant technical decisions made in this project. Each ADR captures: - Context - Why we needed to make this decision - Decision - What we chose and why - Consequences - Trade-offs and impacts - Alternatives - What else we considered

Format

Use the template: 000-template.md

ADRs include YAML frontmatter for enhanced visualization in MkDocs Material:

---
title: ADR NNN - Decision Title
adr:
  author: Your Name
  created: 01-Jan-2025  # Format: DD-Mon-YYYY
  status: proposed  # or: accepted, superseded
  # superseded_by: NNN-title  # Optional: only if superseded
  # extends: [NNN-first, NNN-second]  # Optional: list of related ADRs
---

This frontmatter enables: - Visual headers with metadata - Status badges (draft, proposed, accepted, rejected, superseded) - Auto-generated relationship graphs between related ADRs

Numbering

ADRs are numbered sequentially with leading zeros: - 001, 002, 003... (not 1, 2, 3) - This ensures proper sorting in file listings

Status Values

  • Proposed - Under discussion, not yet approved
  • Accepted - Approved and implemented
  • Superseded by ADR-NNN - Replaced by a newer decision

When to Write an ADR

Write an ADR when making decisions that: - Affect multiple components or the system architecture - Involve significant trade-offs or risks - Are difficult or expensive to reverse - Will impact future development - Need explanation to future developers (or your future self)

When NOT to Write an ADR

Don't write ADRs for: - Minor implementation details (goes in devlog) - Code style choices (goes in linter config) - Temporary workarounds - Decisions that can be easily reversed

Keep ADRs Brief

Important: ADRs document decisions, not implementations.

❌ Don't include: - Full code examples (link to PRs instead) - Implementation steps (goes in devlog or GitHub issues) - Detailed metrics tracking (goes in monitoring docs)

✅ Do include: - Why we made the decision - What alternatives we considered - What trade-offs we accepted - Links to relevant resources

ADR Relationships

graph TD
000-template["ADR NNN - [Decision Title]"]
click 000-template "/inkwell-cli/building-in-public/adr/000-template/" _blank
000-template:::mermaid-proposed
000-template:::mermaid-common
001-developer-knowledge-system["ADR 001 - Adopt Developer Knowledge System (DKS) for Documentation"]
click 001-developer-knowledge-system "/inkwell-cli/building-in-public/adr/001-developer-knowledge-system/" _blank
001-developer-knowledge-system:::mermaid-accepted
001-developer-knowledge-system:::mermaid-common
002-phase-1-architecture["ADR 002 - Phase 1 Architecture & Technology Decisions"]
click 002-phase-1-architecture "/inkwell-cli/building-in-public/adr/002-phase-1-architecture/" _blank
002-phase-1-architecture:::mermaid-proposed
002-phase-1-architecture:::mermaid-common
003-build-system-selection["ADR 003 - Build System Selection (Setuptools vs Hatchling)"]
click 003-build-system-selection "/inkwell-cli/building-in-public/adr/003-build-system-selection/" _blank
003-build-system-selection:::mermaid-accepted
003-build-system-selection:::mermaid-common
004-credential-encryption["ADR 004 - Credential Encryption Implementation"]
click 004-credential-encryption "/inkwell-cli/building-in-public/adr/004-credential-encryption/" _blank
004-credential-encryption:::mermaid-accepted
004-credential-encryption:::mermaid-common
005-rss-parser-library["ADR 005 - RSS Parser Library Selection"]
click 005-rss-parser-library "/inkwell-cli/building-in-public/adr/005-rss-parser-library/" _blank
005-rss-parser-library:::mermaid-accepted
005-rss-parser-library:::mermaid-common
006-terminal-output-library["ADR 006 - Terminal Output Enhancement Library"]
click 006-terminal-output-library "/inkwell-cli/building-in-public/adr/006-terminal-output-library/" _blank
006-terminal-output-library:::mermaid-accepted
006-terminal-output-library:::mermaid-common
007-enforce-pre-commit-hooks["ADR 007 - Enforce Pre-commit Hooks for Code Quality"]
click 007-enforce-pre-commit-hooks "/inkwell-cli/building-in-public/adr/007-enforce-pre-commit-hooks/" _blank
007-enforce-pre-commit-hooks:::mermaid-accepted
007-enforce-pre-commit-hooks:::mermaid-common
008-use-uv-for-python-tooling["ADR 008 - Use uv for All Python Package and Environment Management"]
click 008-use-uv-for-python-tooling "/inkwell-cli/building-in-public/adr/008-use-uv-for-python-tooling/" _blank
008-use-uv-for-python-tooling:::mermaid-accepted
008-use-uv-for-python-tooling:::mermaid-common
035-plugin-architecture["ADR 035 - Plugin Architecture"]
click 035-plugin-architecture "/inkwell-cli/building-in-public/adr/035-plugin-architecture/" _blank
035-plugin-architecture:::mermaid-accepted
035-plugin-architecture:::mermaid-common
036-youtube-url-resolution["ADR 036 - YouTube URL Resolution in Feed Ingestion"]
click 036-youtube-url-resolution "/inkwell-cli/building-in-public/adr/036-youtube-url-resolution/" _blank
036-youtube-url-resolution:::mermaid-accepted
036-youtube-url-resolution:::mermaid-common
037-web-app-stack-and-repo-boundary["ADR 037 - Web app stack and repository boundary"]
click 037-web-app-stack-and-repo-boundary "/inkwell-cli/building-in-public/adr/037-web-app-stack-and-repo-boundary/" _blank
037-web-app-stack-and-repo-boundary:::mermaid-accepted
037-web-app-stack-and-repo-boundary:::mermaid-common
038-gemini-youtube-url-fallback["ADR 038 - Gemini YouTube URL fallback"]
click 038-gemini-youtube-url-fallback "/inkwell-cli/building-in-public/adr/038-gemini-youtube-url-fallback/" _blank
038-gemini-youtube-url-fallback:::mermaid-accepted
038-gemini-youtube-url-fallback:::mermaid-common
classDef mermaid-draft fill:#a3a3a3;
classDef mermaid-common color:#595959;
classDef mermaid-proposed fill:#b6d8ff;
classDef mermaid-accepted fill:#b4eda0;
classDef mermaid-rejected fill:#ffd5d1;
classDef mermaid-superseded fill:#ffebb6;