that initial commit

docs/decisions/ADR-002-flask-extensions.md

@@ -0,0 +1,134 @@
+# ADR-002: Flask Extensions and Dependencies
+
+## Status
+Accepted
+
+## Context
+Flask is intentionally minimal. We need to select only essential extensions that align with the "minimal code" philosophy while supporting required functionality.
+
+## Decision
+Use the following minimal set of dependencies:
+- **Flask** - Core framework
+- **markdown** - Markdown to HTML conversion
+- **feedgen** - RSS feed generation
+- **httpx** - HTTP client for IndieAuth verification
+- **python-dotenv** - Environment configuration
+- **pytest** - Testing framework
+
+**NO additional Flask extensions** will be used in V1.
+
+## Rationale
+
+### Core Dependencies
+
+#### markdown
+- **Purpose**: Convert markdown notes to HTML
+- **Simplicity**: Pure Python, simple API
+- **Justification**: Core requirement for note rendering
+- **Alternative**: mistune (faster but less standard)
+- **Verdict**: markdown is more standard and sufficient for single-user
+
+#### feedgen
+- **Purpose**: Generate valid RSS 2.0 feeds
+- **Simplicity**: High-level API, handles all RSS requirements
+- **Justification**: Ensures RSS 2.0 compliance without manual XML generation
+- **Alternative**: Manual XML generation (error-prone)
+- **Verdict**: feedgen guarantees valid RSS output
+
+#### httpx
+- **Purpose**: HTTP client for IndieAuth endpoint verification
+- **Simplicity**: Modern, clean API
+- **Justification**: Need to verify IndieAuth endpoints and fetch client metadata
+- **Alternative**: requests (synchronous only), urllib (too low-level)
+- **Verdict**: httpx provides clean API and can be sync or async if needed later
+
+#### python-dotenv
+- **Purpose**: Load environment variables from .env file
+- **Simplicity**: Single-purpose, simple API
+- **Justification**: Standard pattern for configuration management
+- **Alternative**: Manual environment variable handling
+- **Verdict**: Industry standard, minimal overhead
+
+#### pytest
+- **Purpose**: Testing framework
+- **Simplicity**: Minimal boilerplate, clear assertions
+- **Justification**: Required for test coverage
+- **Alternative**: unittest (more verbose), nose2 (unmaintained)
+- **Verdict**: pytest is current Python testing standard
+
+### Extensions REJECTED for V1
+
+#### Flask-SQLAlchemy (Rejected)
+- **Reason**: Adds ORM abstraction we don't need
+- **Decision**: Use sqlite3 standard library directly
+- **Benefit**: Simpler code, explicit queries, no magic
+
+#### Flask-Login (Rejected)
+- **Reason**: Session-based authentication, we need token-based
+- **Decision**: Implement simple token validation ourselves
+- **Benefit**: Full control over IndieAuth flow
+
+#### Flask-CORS (Rejected)
+- **Reason**: Single function decorator, don't need extension
+- **Decision**: Use @after_request decorator for CORS headers
+- **Benefit**: 5 lines of code vs. another dependency
+
+#### Flask-Limiter (Rejected for V1)
+- **Reason**: Rate limiting is nice-to-have, not critical for single-user
+- **Decision**: Defer to V2 or rely on reverse proxy
+- **Benefit**: Reduced complexity
+
+#### Flask-WTF (Rejected)
+- **Reason**: Form handling for single form (note creation) is overkill
+- **Decision**: Simple HTML forms with manual validation
+- **Benefit**: No CSRF complexity in V1, manual validation is clear
+
+## Consequences
+
+### Positive
+- Minimal dependency tree
+- Full control over implementation
+- Easy to understand codebase
+- Fast installation and startup
+- Reduced attack surface
+
+### Negative
+- Must implement some features manually (token validation, CORS)
+- No form CSRF protection in V1 (acceptable for single-user)
+- Manual SQL queries required
+
+### Mitigation
+- Document manual implementations clearly
+- Ensure manual code is well-tested
+- Keep manual implementations simple and obvious
+- Plan to add CSRF in V2 if needed
+
+## Complete Dependency List
+
+```
+Flask==3.0.*
+markdown==3.5.*
+feedgen==1.0.*
+httpx==0.27.*
+python-dotenv==1.0.*
+pytest==8.0.*
+```
+
+## Development Dependencies
+```
+pytest-cov       # Test coverage reporting
+black            # Code formatting
+flake8           # Linting
+```
+
+## Standards Compliance
+- All dependencies are pure Python or have minimal C extensions
+- All are actively maintained with security updates
+- All support Python 3.11+
+- Total dependency count: 6 direct dependencies (excluding dev tools)
+
+## References
+- Flask Extensions: https://flask.palletsprojects.com/en/3.0.x/extensions/
+- Markdown Spec: https://daringfireball.net/projects/markdown/
+- RSS 2.0: https://www.rssboard.org/rss-specification
+- Python Packaging: https://packaging.python.org/