[FEATURE] Implement Architecture Decision Records (ADRs)

[nanotaboada]

Problem

This project makes several opinionated architectural and technology choices (FastAPI over Flask, async SQLAlchemy, SQLite, aiocache, layered architecture, coach-themed versioning) without documenting the why behind these decisions.

Pain points:

• New contributors/learners must reverse-engineer the rationale behind technology choices
• Architectural context is lost - no record of alternatives considered or trade-offs made
• Risk of uninformed changes - future modifications may violate original design principles without understanding the constraints that shaped them
• Missed learning opportunity - as a PoC demonstrating modern Python patterns, the reasoning behind choices is as valuable as the implementation itself
• Difficult to justify forks/adaptations - others reusing this as a template can't make informed decisions about what to keep vs change

This is especially problematic for a learning-focused PoC where understanding the "why" is critical for educational value.

Proposed Solution

Implement Architecture Decision Records (ADRs) using the Michael Nygard template to systematically document all architecturally significant decisions.

Benefits:

• 📚 Better onboarding - New contributors understand context immediately
• 🎓 Enhanced learning value - Learners see not just what was built, but why
• 🔍 Informed evolution - Future changes can reference past decisions and their constraints
• 📖 Knowledge preservation - Rationale survives team/contributor changes
• 🏗️ Best practice demonstration - Shows proper architecture documentation for production systems
• ♻️ Easier forking - Others can adapt this PoC with full context of original decisions

Suggested Approach

1. Directory Structure

Create ADR storage location:

docs/
  adr/
    README.md              # Index and overview
    0001-adopt-fastapi.md
    0002-async-sqlalchemy.md
    0003-sqlite-database.md
    0004-aiocache-memory-cache.md
    0005-layered-architecture.md
    0006-coach-themed-versioning.md
    0007-docker-single-container.md
    0008-black-flake8-formatting.md
    template.md            # ADR template for future decisions

2. ADR Template

Use the Michael Nygard format:

# ADR-NNNN: {Title}

Date: YYYY-MM-DD

## Status

{Proposed | Accepted | Deprecated | Superseded by ADR-XXXX}

## Context

{Describe the forces at play: technical, business, team constraints.
What problem needs solving? What alternatives exist?}

## Decision

{State the decision in full sentences with active voice: "We will..."}

## Consequences

{Describe the resulting context after applying this decision:
- Positive outcomes
- Negative trade-offs
- Neutral implications
All affect the project going forward.}

3. Initial ADRs to Create (Retroactive)

Priority ADRs (document existing decisions):

1. ADR-0001: Adopt FastAPI as REST API Framework

   • Context: Need modern Python web framework for async REST API
   • Alternatives: Flask, Django REST Framework, Starlette
   • Decision: FastAPI
   • Why: Auto-generated OpenAPI docs, native async support, Pydantic validation, modern Python 3.13+ patterns

2. ADR-0002: Use Async SQLAlchemy with SQLite

   • Context: Need ORM with async support
   • Alternatives: Sync SQLAlchemy, Tortoise ORM, PostgreSQL
   • Decision: SQLAlchemy 2.0+ async with SQLite
   • Why: Demonstrate modern async patterns, SQLite sufficient for demo, avoid external dependencies

3. ADR-0003: Implement In-Memory Caching with aiocache

   • Context: Need caching for GET endpoints
   • Alternatives: Redis, memcached, no caching
   • Decision: aiocache SimpleMemoryCache
   • Why: Zero external dependencies, sufficient for PoC, demonstrates pattern

4. ADR-0004: Adopt Layered Architecture (Routes → Services → Database)

   • Context: Need clear separation of concerns
   • Alternatives: MVC, hexagonal, flat structure
   • Decision: 3-layer (routes, services, database)
   • Why: Clear separation, testable, familiar pattern, appropriate complexity for PoC

5. ADR-0005: Use Coach-Themed Semantic Versioning

   • Context: Need memorable release naming convention
   • Alternatives: Standard semver, animal names, city names
   • Decision: Famous football coaches A-Z
   • Why: Fun, memorable, culturally universal, alphabetical progression

6. ADR-0006: Single-Container Docker Deployment

   • Context: Need containerization strategy
   • Alternatives: Docker Compose multi-service, Kubernetes, no containers
   • Decision: Single container + volume for SQLite
   • Why: Simplicity, appropriate for PoC, demonstrates Docker patterns

7. ADR-0007: Enforce Black Formatting and Flake8 Linting

   • Context: Need consistent code style
   • Alternatives: pylint, autopep8, no enforcement
   • Decision: Black (formatting) + Flake8 (linting)
   • Why: Black is opinionated (zero config), Flake8 catches errors, industry standard

8. ADR-0008: Maintain AGENTS.md for AI-Assisted Development

   • Context: Need comprehensive yet token-efficient documentation for AI tooling
   • Alternatives: Single README, wiki, inline comments only
   • Decision: Layered docs (copilot-instructions.md auto-loaded, AGENTS.md on-demand)
   • Why: Token efficiency (500 vs 2500), detailed when needed, modern AI-first workflow

4. Integration with Existing Docs

• Update README.md - Add "Architecture Decisions" section linking to docs/adr/
• Update AGENTS.md - Reference ADRs in "Additional Resources" section
• Update CONTRIBUTING.md - Add guideline: "New architecturally significant decisions must include an ADR"

5. Automation & Tooling (Optional Future Enhancement)

• Use adr-tools for creating/managing ADRs
• Add docs/adr/ to grep searches in VS Code settings
• Include ADR review in PR checklist for architectural changes

6. File Modifications Required

Create docs/adr/README.md

# Architecture Decision Records (ADR)

This directory contains records of architecturally significant decisions made in this project.

## Index

- [ADR-0001](0001-adopt-fastapi.md) - Adopt FastAPI as REST API Framework
- [ADR-0002](0002-async-sqlalchemy.md) - Use Async SQLAlchemy with SQLite
- [ADR-0003](0003-aiocache-memory-cache.md) - Implement In-Memory Caching
- [ADR-0004](0004-layered-architecture.md) - Adopt Layered Architecture
- [ADR-0005](0005-coach-themed-versioning.md) - Use Coach-Themed Versioning
- [ADR-0006](0006-docker-single-container.md) - Single-Container Deployment
- [ADR-0007](0007-black-flake8-formatting.md) - Enforce Black + Flake8
- [ADR-0008](0008-agents-md-documentation.md) - Maintain AGENTS.md Documentation

## Resources

- [Michael Nygard's ADR article](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
- [ADR GitHub organization](https://adr.github.io/)
- [Microsoft Azure Well-Architected: ADRs](https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record)

Update README.md

Add after "Structure" section:

## Architecture Decisions

This project documents architecturally significant decisions using Architecture Decision Records (ADRs).

📖 [View all ADRs](docs/adr/)

Key decisions:
- [Why FastAPI?](docs/adr/0001-adopt-fastapi.md)
- [Why async SQLAlchemy?](docs/adr/0002-async-sqlalchemy.md)
- [Why coach-themed versioning?](docs/adr/0005-coach-themed-versioning.md)

Update AGENTS.md "Additional Resources" section

## Additional Resources

- **Architecture Decisions**: `docs/adr/` - Rationale behind technology choices
- **Postman Collection**: `postman_collections/python-samples-fastapi-restful.postman_collection.json`
...

Update CONTRIBUTING.md "Code & Commit Conventions" section

- **Architecture Decisions**
  - For architecturally significant changes (new frameworks, major pattern changes, etc.),
    create an ADR in `docs/adr/` using the template.
  - Reference the ADR in your PR description.

Acceptance Criteria

• Directory structure created: docs/adr/ with README.md, template.md
• Initial 8 ADRs written using Michael Nygard template format (Title, Status, Context, Decision, Consequences)
• README.md updated with "Architecture Decisions" section linking to ADRs
• AGENTS.md updated with reference to ADRs in "Additional Resources"
• CONTRIBUTING.md updated with guideline for creating ADRs for significant decisions
• ADRs are discoverable: Can find via README, AGENTS.md, or file explorer
• ADRs are educational: Each ADR clearly explains alternatives considered and trade-offs made
• Template provided: docs/adr/template.md exists for future ADRs
• CHANGELOG.md updated: Entry in [Unreleased] section under "Added"

References

ADR Resources

• Documenting Architecture Decisions - Michael Nygard (2011) - Original blog post that popularized ADRs
• ADR GitHub Organization - Templates, tools, and best practices
• Microsoft Azure Well-Architected: ADRs - Enterprise perspective on maintaining ADRs
• Michael Nygard ADR Template - Canonical template format

Tooling (Optional)

• adr-tools - Command-line tools for managing ADRs
• adr-manager - Web UI for browsing ADRs
• log4brains - Modern ADR toolchain with architecture knowledge base

Similar Projects Using ADRs

• Architectural Decision Records in Action - YouTube - IBM Watson Group's experience with ADRs
• AWS Prescriptive Guidance on ADRs - Amazon's recommendation for ADR usage

Related Issues/PRs

• N/A (initial proposal)

---

Note: This feature aligns with the project's philosophy of being a "learning-focused PoC" by making the architectural reasoning explicit and accessible to learners and contributors.

[coderabbitai]

🔗 Related PRs

#471 - docs: optimize AI agent instructions for token efficiency [merged]
#481 - docs: standardize release workflow and improve documentation quality [closed]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!