Improvement Roadmap¶

3-Phase Implementation Plan¶

Phase 1: Foundation Refactoring (2-3 Days)¶

Goal: Establish clean patterns before adding new features
Effort: 14 story points
Owner: Backend team

Tasks¶

Split main.py into APIRouter modules
Create routers/assets.py (asset endpoints)
Create routers/transactions.py (transaction endpoints)
Create routers/settings.py (configuration)
Create routers/ai.py (AI analysis)
Create routers/health.py (health checks)
Update main.py to import routers
Effort: 4 hours
Fix endpoint ordering dependency
Add explicit parameter validation using Pydantic
Use APIRouter with clear route patterns
Add tests to catch ordering regressions
Effort: 1 hour
Add API versioning (/api/v1/)
Create APIRouter with /api/v1 prefix
Import all routers under v1_router
Document deprecation path
Effort: 1 hour
Add Pydantic request/response models
Define models for all endpoint inputs/outputs
Add OpenAPI documentation
Effort: 3 hours
Implement error handling middleware
Standardize error response format
Add error codes
Effort: 1 hour
Add comprehensive tests
Transaction encryption roundtrips
Blind index functionality
Endpoint error cases
Effort: 3 hours

Deliverables: - ✅ Clean APIRouter structure - ✅ No endpoint ordering issues - ✅ API versioning ready - ✅ Type-safe endpoints - ✅ 80%+ test coverage on critical paths

Phase 2: Operations & Security (3-4 Days, Parallel with Phase 3)¶

Goal: Production-readiness improvements
Effort: 12 story points
Owner: DevOps/Backend team

Tasks¶

Encryption key versioning
Add key_version column to Transaction table
Implement key rotation script
Add rotation documentation
Effort: 3 hours
Feature flags system
Add feature_flags table
Implement flag evaluation middleware
Effort: 2 hours
Structured request logging
Add JSON-formatted logging
Include request ID, timing, user
Effort: 1 hour
Security documentation
Create SECURITY.md threat model
Document key rotation procedure
Effort: 2 hours
Database optimization
Add indexes on common queries
Document query plans
Effort: 1 hour

Deliverables: - ✅ Key rotation capability - ✅ Feature flags infrastructure - ✅ Structured logging - ✅ Security documentation - ✅ Optimized database queries

Phase 3: New Features (2-3 Weeks, Parallel with Phase 2)¶

Goal: Implement FinTS and Budget features
Uses: Clean patterns from Phase 1

Task 3A: FinTS Integration (Issue #11, ~18 todos)¶

Timeline: Week 1-1.5

Database & Backend Setup (3 todos)
Create BankConnection model
Add fints library dependency
Create hbci_parser.py module
Backend Endpoints (4 todos)
routers/bank_connections.py (CRUD)
POST /api/v1/transactions/import/fints/{bank_connection_id}
Frontend UI (5 todos)
Settings section for bank accounts
Connection form modal
Import workflow UI
Testing (4 todos)
Parser unit tests
Endpoint integration tests
Deduplication verification
Documentation (2 todos)
README section
.env.example updates

Deliverables: - ✅ FinTS bank import working - ✅ Multiple account support - ✅ 90-day default fetch - ✅ PIN never stored - ✅ Full test coverage

Task 3B: Google Sheets Budget (Issue #12, ~24 todos)¶

Timeline: Week 1.5-3

Dependency: DB-driven transaction categories (Phase 2, Task 2)

Database & Backend Setup (4 todos)
Create BudgetPlan model
Create transaction_category table
Create sheets_parser.py
Category mapping logic
Backend Endpoints (4 todos)
routers/budgets.py
Budget CRUD endpoints
Comparison endpoint with filters
Data Logic (4 todos)
Expense aggregation
Variance calculation
Multi-person filtering
Monthly vs. YTD logic
Frontend UI (7 todos)
Settings section (URL input)
Comparison page
Comparison table component
Filters and toggles
Optional charts
Testing (5 todos)
Parser tests
Mapping logic tests
Variance calculation tests
Endpoint tests
Filter logic tests
Documentation (2 todos)
README section
Google Sheets setup guide

Deliverables: - ✅ Budget comparison working - ✅ Multi-person responsibility tracking - ✅ Monthly and YTD views - ✅ Variance calculations - ✅ Full test coverage

Priority Matrix¶

Impact
  ▲
  │ [HIGH]              [CRITICAL]
  │
  │ Structured logging  Monolithic main.py
  │ Feature flags       Endpoint ordering
  │ Rate limiting       Encryption versioning
  │                     Theme consistency
  │ [MEDIUM]            [HIGH]
  │ Test coverage       API versioning
  │ Error handling      Hardcoded categories
  │                     Polling backoff
  └─────────────────────────────────────► Effort
    Low        Medium         High

Implementation Estimates¶

Phase	Component	Story Points	Days	Effort
1	Refactor main.py	4	1	High
1	Fix endpoint ordering	1	0.5	Low
1	API versioning	1	0.5	Low
1	Validation models	3	1.5	Medium
1	Error handling	1	0.5	Low
1	Testing	4	2	High
Phase 1 Total		14	6 (2-3 days)
2	Key versioning	3	1.5	Medium
2	Feature flags	2	1	Low
2	Structured logging	1	0.5	Low
2	Security docs	2	1	Low
2	DB optimization	1	0.5	Low
Phase 2 Total		9	4.5 (3-4 days)
3A	FinTS integration	18	8	High
3B	Budget comparison	24	12	High
Phase 3 Total		42	20 (2-3 weeks)
Grand Total		65	30.5 (4-5 weeks)

Quick Wins (Can Do First)¶

Low effort, high impact — do ASAP:

Fix endpoint ordering (1 hour)
Add parameter validation
Prevents production bugs
Add API versioning (1 hour)
Just change endpoint prefix
Enables future API changes safely
Implement error handling middleware (1-2 hours)
Standardize responses
Better debugging
Add structured logging (1 hour)
JSON format
Better monitoring

Total: 4-5 hours, enables safer development.

Future Enhancements¶

Beyond Phase 3¶

WebSocket real-time updates (replace polling)
Mobile app (reuse /api/v1 endpoints)
Data export (CSV, JSON)
Multi-user households
Recurring transactions
Tax reporting
Investment analytics
Alerts and notifications

Start with Phase 1. Enables cleaner Phase 3 implementation.