docs: add Phase 2 domain verification design and clarifications
Add comprehensive Phase 2 documentation: - Complete design document for two-factor domain verification - Implementation guide with code examples - ADR for implementation decisions (ADR-0004) - ADR for rel="me" email discovery (ADR-008) - Phase 1 impact assessment - All 23 clarification questions answered - Updated architecture docs (indieauth-protocol, security) - Updated ADR-005 with rel="me" approach - Updated backlog with technical debt items Design ready for Phase 2 implementation. Generated with Claude Code https://claude.com/claude-code Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -568,9 +568,86 @@ These features are REQUIRED for the first production-ready release.
|
||||
|
||||
Technical debt items are tracked here with a DEBT: prefix. Per project standards, each release must allocate at least 10% of effort to technical debt reduction.
|
||||
|
||||
### DEBT: Add Redis for session storage (M)
|
||||
### DEBT: TD-001 - FastAPI Lifespan Migration (XS)
|
||||
**Created**: 2025-11-20 (Phase 1 review)
|
||||
**Priority**: P2
|
||||
**Component**: Core Infrastructure
|
||||
|
||||
**Issue**: Using deprecated `@app.on_event()` decorators instead of lifespan context manager.
|
||||
|
||||
**Impact**:
|
||||
- Deprecation warnings in FastAPI 0.109+
|
||||
- Will break in future FastAPI version
|
||||
- Not following current best practices
|
||||
|
||||
**Current Mitigation**: Still works in current FastAPI version.
|
||||
|
||||
**Effort to Fix**: < 1 day
|
||||
- Replace `@app.on_event("startup")` with lifespan context manager
|
||||
- Update database initialization to use lifespan
|
||||
- Update tests if needed
|
||||
|
||||
**Plan**: Address in v1.1.0 or during FastAPI upgrade.
|
||||
|
||||
**References**: FastAPI lifespan documentation
|
||||
|
||||
---
|
||||
|
||||
### DEBT: TD-002 - Database Migration Rollback Safety (S)
|
||||
**Created**: 2025-11-20 (Phase 1 review)
|
||||
**Priority**: P2
|
||||
**Component**: Database Layer
|
||||
|
||||
**Issue**: No migration rollback capability. Migrations are one-way only.
|
||||
|
||||
**Impact**:
|
||||
- Cannot easily roll back schema changes
|
||||
- Requires manual SQL to undo migrations
|
||||
- Risk during production deployments
|
||||
|
||||
**Current Mitigation**: Simple schema, manual SQL backups acceptable for v1.0.0.
|
||||
|
||||
**Effort to Fix**: 1-2 days
|
||||
- Integrate Alembic for migration management
|
||||
- Create rollback scripts for existing migrations
|
||||
- Update deployment documentation
|
||||
|
||||
**Plan**: Address before v1.1.0 when schema changes become more frequent.
|
||||
|
||||
**References**: Alembic documentation
|
||||
|
||||
---
|
||||
|
||||
### DEBT: TD-003 - Async Email Support (S)
|
||||
**Created**: 2025-11-20 (Phase 1 review)
|
||||
**Priority**: P2
|
||||
**Component**: Email Service
|
||||
|
||||
**Issue**: Synchronous SMTP blocks request thread during email sending.
|
||||
|
||||
**Impact**:
|
||||
- Email sending delays response to user (1-5 seconds)
|
||||
- Thread blocked during SMTP operation
|
||||
- Poor UX during slow email delivery
|
||||
|
||||
**Current Mitigation**: Acceptable for low-volume v1.0.0. Timeout limits (10s) prevent long blocks.
|
||||
|
||||
**Effort to Fix**: 1-2 days
|
||||
- Implement background task queue (FastAPI BackgroundTasks or Celery)
|
||||
- Make email sending non-blocking
|
||||
- Update UX to show "Sending email..." message
|
||||
- Add retry logic for failed sends
|
||||
|
||||
**Plan**: Address in v1.1.0 when user volume increases or when UX feedback indicates issue.
|
||||
|
||||
**Alternative**: Use async SMTP library (aiosmtplib)
|
||||
|
||||
---
|
||||
|
||||
### DEBT: TD-004 - Add Redis for Session Storage (M)
|
||||
**Created**: 2025-11-20 (architectural decision)
|
||||
**Priority**: P2
|
||||
**Component**: Storage Layer
|
||||
|
||||
**Issue**: In-memory storage doesn't survive restarts.
|
||||
|
||||
@@ -584,22 +661,6 @@ Technical debt items are tracked here with a DEBT: prefix. Per project standards
|
||||
|
||||
---
|
||||
|
||||
### DEBT: Implement schema migrations (S)
|
||||
**Created**: 2025-11-20 (architectural decision)
|
||||
**Priority**: P2
|
||||
|
||||
**Issue**: No formal migration system, using raw SQL files.
|
||||
|
||||
**Impact**: Schema changes require manual intervention.
|
||||
|
||||
**Mitigation (current)**: Simple schema, infrequent changes acceptable for v1.0.0.
|
||||
|
||||
**Effort to Fix**: 1-2 days (Alembic integration)
|
||||
|
||||
**Plan**: Address before v1.1.0 when schema changes become more frequent.
|
||||
|
||||
---
|
||||
|
||||
## Backlog Management
|
||||
|
||||
### Adding New Features
|
||||
|
||||
Reference in New Issue
Block a user