StarPunk/docs/decisions/ADR-001-python-web-framework.md

ADR-001: Python Web Framework Selection

Status

Accepted

Context

StarPunk requires a Python web framework to implement the API-first architecture with RESTful endpoints, Micropub support, IndieAuth integration, and web interface. The framework must support both API and server-side rendered HTML with minimal complexity.

Decision

Use Flask as the primary web framework.

Rationale

Simplicity Score: 9/10

• Minimal boilerplate code required
• Explicit routing and request handling
• Easy to understand for newcomers
• Core framework is ~1000 lines of code
• Follows "micro-framework" philosophy aligned with StarPunk principles

Fitness Score: 10/10

• Perfect for single-user applications
• Built-in development server
• Excellent template engine (Jinja2) for HTML generation
• Simple decorator-based routing
• Easy integration with SQLite
• Native support for both JSON APIs and HTML rendering
• Werkzeug provides robust HTTP utilities
• Blueprint support for code organization

Maintenance Score: 9/10

• Extremely mature (13+ years)
• Large community and extensive documentation
• Stable API with minimal breaking changes
• Extensive ecosystem of well-tested extensions
• Active development and security updates

Standards Compliance: Pass

• Standard WSGI interface
• Full HTTP status code support
• Proper content-type handling
• Easy CORS implementation
• Session management built-in

Consequences

Positive

• Minimal learning curve
• Small dependency footprint
• Easy to test (built-in test client)
• Flexible enough for API-first architecture
• Can render HTML templates for public interface
• Easy deployment (WSGI compatible)

Negative

• No built-in ORM (but we're using raw SQLite, so this is actually positive)
• Requires manual selection of extensions
• Less opinionated than larger frameworks

Mitigation

• Extension selection will be minimal (see ADR-002 for extensions)
• Lack of opinion allows us to stay minimal
• Manual configuration gives us full control

Alternatives Considered

FastAPI (Rejected)

• Simplicity: 6/10 - Requires async/await understanding, Pydantic models
• Fitness: 7/10 - Overkill for single-user CMS, async not needed
• Maintenance: 8/10 - Newer framework, but growing
• Verdict: Too complex for project needs, async unnecessary

Django (Rejected)

• Simplicity: 3/10 - Large framework with heavy abstractions
• Fitness: 4/10 - Designed for multi-user applications, includes admin panel, ORM, and many features we don't need
• Maintenance: 10/10 - Excellent maintenance and security
• Verdict: Violates "minimal code" principle, too much unnecessary functionality

Bottle (Considered)

• Simplicity: 10/10 - Single file framework
• Fitness: 7/10 - Very minimal, but perhaps too minimal
• Maintenance: 6/10 - Smaller community, slower updates
• Verdict: Close second, but Flask has better ecosystem for IndieAuth/Micropub

Implementation Notes

Flask will be used with:

• Jinja2 templates for HTML rendering (included with Flask)
• Werkzeug for HTTP utilities (included with Flask)
• Minimal extensions only (see ADR-002)
• Standard WSGI deployment
• Blueprint organization for clear separation of concerns

References

• Flask Documentation: https://flask.palletsprojects.com/
• WSGI Specification: https://peps.python.org/pep-3333/
• Flask Design Decisions: https://flask.palletsprojects.com/en/3.0.x/design/