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:
2025-11-20 13:05:09 -07:00
parent bebd47955f
commit 6f06aebf40
10 changed files with 5605 additions and 410 deletions

View File

@@ -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