98 lines
3.4 KiB
Markdown
98 lines
3.4 KiB
Markdown
# 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/
|