that initial commit

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

@@ -0,0 +1,97 @@
+# 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/