# 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/