Architecture Decision Records (ADRs)

Overview

Architecture Decision Records (ADRs) are documents that capture important architectural decisions made during the development of Unipress. Each ADR provides context, decision rationale, and consequences to help future developers understand why certain choices were made.

ADR Structure

Each ADR follows a consistent format:

  • Title: Clear, descriptive title

  • Status: Accepted, Deprecated, Superseded, etc.

  • Context: Problem or situation requiring a decision

  • Decision: The architectural decision made

  • Consequences: Positive and negative outcomes

  • References: Related documents and resources

Decision Categories

Development Tools & Standards

ADR-001: Dependency Management with uv

  • Decision: Use uv as the primary package manager

  • Rationale: Fast, modern Rust-based tool with excellent dependency resolution

  • Impact: Faster dependency installation, better lock file management

ADR-002: Game Framework Selection (Arcade)

  • Decision: Use Arcade framework for game development

  • Rationale: Modern Python game library with good performance and ease of use

  • Impact: Simplified game development, good documentation and community

ADR-003: Development Tools (Ruff, Pytest, MyPy)

  • Decision: Ruff for linting/formatting, Pytest for testing, MyPy for type checking

  • Rationale: Fast, modern tools that work well together

  • Impact: Consistent code quality, fast feedback loops

ADR-005: Conventional Commits with git-cz

  • Decision: Use conventional commits with git-cz for standardized commit messages

  • Rationale: Clear commit history, automated changelog generation

  • Impact: Better project history, easier releases

ADR-006: Type Checking with MyPy

  • Decision: Implement comprehensive type checking

  • Rationale: Catch errors early, improve code quality and documentation

  • Impact: Better IDE support, fewer runtime errors

Game Design & Architecture

ADR-004: Game Design Standards

  • Decision: Strict one-button input constraint for all games

  • Rationale: Ensures accessibility and simplicity across all games

  • Impact: Consistent user experience, easier game development

ADR-008: Fullscreen Display Standard

  • Decision: All games run in fullscreen mode by default

  • Rationale: Immersive gaming experience, consistent across platforms

  • Impact: Better user experience, simplified display management

ADR-009: Three Lives System

  • Decision: Standard three-lives system for all games

  • Rationale: Familiar gaming pattern, provides challenge without frustration

  • Impact: Consistent game mechanics, predictable difficulty curve

ADR-014: Obstacle Spacing Algorithm

  • Decision: Implement adaptive obstacle spacing based on difficulty

  • Rationale: Ensures fair and engaging gameplay progression

  • Impact: Better game balance, scalable difficulty

Configuration & Data Management

ADR-010: Settings System with TOML

  • Decision: Use TOML for hierarchical configuration

  • Rationale: Human-readable, supports complex nested structures

  • Impact: Easy configuration management, good developer experience

ADR-011: Internationalization with JSON

  • Decision: JSON-based i18n with Polish default, English fallback

  • Rationale: Simple, flexible localization system

  • Impact: Easy to add new languages, maintainable translations

ADR-012: Logging System with Loguru

  • Decision: Use Loguru for structured JSON logging

  • Rationale: Excellent performance, structured output, easy configuration

  • Impact: Better debugging, production monitoring capabilities

Asset & Media Management

ADR-013: Asset Management System

  • Decision: Centralized asset management with JSON metadata

  • Rationale: Organized resource management, easy to extend

  • Impact: Consistent asset handling, better performance

ADR-016: Comprehensive Sound System

  • Decision: Event-driven audio system with OGG format

  • Rationale: High-quality audio, efficient event handling

  • Impact: Rich audio experience, good performance

Infrastructure & Deployment

ADR-017: Containerization with Docker and uv

  • Decision: Docker-based deployment with uv package management

  • Rationale: Consistent environments, easy deployment

  • Impact: Reproducible builds, simplified deployment

ADR-018: HTTP Server Architecture

  • Decision: Flask-based HTTP server for game management

  • Rationale: Lightweight, Python-native, easy to extend

  • Impact: API-based game management, scalable architecture

ADR-019: HTTP Server Framework Selection

  • Decision: Flask over FastAPI for simplicity and maturity

  • Rationale: Simpler learning curve, sufficient features for current needs

  • Impact: Faster development, easier maintenance

Documentation & Quality

ADR-020: UML Documentation with PlantUML

  • Decision: Use PlantUML for generating UML diagrams

  • Rationale: Text-based diagrams, version control friendly

  • Impact: Maintainable documentation, clear architecture visualization

ADR-021: Developer Documentation with Sphinx

  • Decision: Sphinx with Myst-Parser for comprehensive documentation

  • Rationale: Excellent Python documentation tool, Markdown support

  • Impact: Professional documentation, good developer experience

ADR-022: Changelog Standards and Maintenance

  • Decision: Follow “Keep a Changelog” and Semantic Versioning

  • Rationale: Standardized change tracking, clear release history

  • Impact: Better project transparency, easier releases

ADR-023: Documentation Hosting Platform

  • Decision: Read the Docs primary, GitHub Pages backup

  • Rationale: Professional hosting, good integration with GitHub

  • Impact: Reliable documentation access, good SEO

Decision Making Process

When to Create an ADR

Create an ADR when making decisions about:

  • Technology choices: Frameworks, libraries, tools

  • Architectural patterns: Design patterns, system structure

  • Standards: Coding standards, naming conventions

  • Infrastructure: Deployment, hosting, CI/CD

  • Process changes: Development workflow, release process

ADR Lifecycle

  1. Proposed: Initial draft for review

  2. Accepted: Decision approved and implemented

  3. Deprecated: Decision no longer relevant

  4. Superseded: Replaced by newer decision

Review Process

  • All ADRs are reviewed by the development team

  • Decisions are documented before implementation

  • Regular review of existing ADRs for relevance

  • Updates made when circumstances change

Benefits of ADRs

For Current Development

  • Context preservation: Why decisions were made

  • Consistency: Standardized approach across the project

  • Onboarding: New developers understand project choices

For Future Maintenance

  • Historical record: Evolution of the architecture

  • Change tracking: How and why systems evolved

  • Risk mitigation: Understanding consequences of changes

For Project Management

  • Transparency: Clear decision-making process

  • Accountability: Documented rationale for choices

  • Communication: Shared understanding across team