Quick Reference

5-Minute Architecture Overview

Deployment Stack

Infrastructure: - Frontend: React/Vite at http://localhost:3000 (dev) - Backend: FastAPI at http://localhost:8000 (dev) - Database: PostgreSQL (prod) via SSH tunnel from Uberspace - LLM: Ollama (local default), upgradable to OpenAI/Gemini - Proxy: oauth2-proxy at http://localhost:4180 (prod entry point) - Market Data: Finnhub (primary) → Alpha Vantage (fallback)

Docker Compose: - 4 local services: backend, frontend, ollama, oauth2-proxy - All configured in root Taskfile.yml and docker-compose.yml - Uberspace-hosted database reached via SSH tunnel

Data Domains

Domain 1: Assets (Portfolio + Market Data) - User portfolio: stocks, ETFs, cryptocurrencies - Real-time prices via Finnhub/Alpha Vantage (EUR converted) - Price history via polling (30s cadence) - Analytics: allocation, performance, sector analysis

Domain 2: Transactions (Bank Imports + Spending Analysis) - CSV import from bank (CaMT52 format, German banking standard) - Encoding detection (UTF-8, ISO-8859-1, CP1252) - AI categorization via Ollama (6 categories) - Encryption: Fernet AES-256 for descriptions - Blind indexing: HMAC for searchable encrypted fields - Deduplication: SHA-256 fingerprinting

Technology Stack

Component	Tech
Backend	FastAPI + SQLAlchemy (ORM)
Frontend	React + Vite + Tailwind CSS
Database	PostgreSQL (prod), SQLite (dev)
LLM	Ollama (local), OpenAI/Gemini (optional)
Market Data	Finnhub API + Alpha Vantage (fallback)
Security	Fernet encryption, HMAC blind indexing, OAuth2
Deployment	Docker Compose, Uberspace, GitHub Actions

---

🔴 Top 14 Improvements (Ranked by Impact)

Critical Issues (Must Fix)

1. Monolithic main.py (50+ endpoints in single file)
2. Impact: HIGH | Effort: MEDIUM
3. Solution: Split into APIRouter modules (assets, transactions, settings, ai, health)

4. Benefit: Maintainability, testing, scalability

5. Endpoint Ordering Dependency (/analyze must precede /{symbol})

6. Impact: HIGH | Effort: LOW
7. Solution: Use explicit FastAPI route decorators and parameter validation

8. Benefit: Eliminate fragile dependencies, improve robustness

9. No Encryption Key Versioning

10. Impact: HIGH | Effort: MEDIUM
11. Solution: Add key_version columns to Transaction model; implement key rotation strategy
12. Benefit: Enable future key rotation; essential for production

Important Issues (High Priority)

1. Frontend Theme Inconsistency (dark + inline styles vs. Tailwind)
2. Impact: MEDIUM | Effort: MEDIUM
3. Solution: Standardize on Tailwind; migrate asset screens to consistent theme

4. Benefit: Maintainability, consistency, faster development

5. No API Versioning (/api/v1/)

6. Impact: MEDIUM | Effort: LOW
7. Solution: Add version prefix to all endpoints

8. Benefit: Backward compatibility, easier API evolution

9. Hardcoded Transaction Categories

10. Impact: MEDIUM | Effort: MEDIUM
11. Solution: Move categories to database enum; make extensible

12. Benefit: Enable Budget feature, user customization

13. Frontend Polling Without Backoff (hard-coded 30s)

14. Impact: MEDIUM | Effort: LOW
15. Solution: Add jitter, exponential backoff, configurable cadence
16. Benefit: Resilience, reduced thundering herd risk

Quality of Life (Medium Priority)

1. No Request/Response Validation Models
2. Impact: MEDIUM | Effort: MEDIUM
3. Solution: Add Pydantic models for all endpoints

4. Benefit: Type safety, auto-generated API docs, better errors

5. No Error Handling Middleware

6. Impact: MEDIUM | Effort: LOW
7. Solution: Standardize error responses (JSON format, error codes)

8. Benefit: Consistent client error handling

9. Insufficient Test Coverage

   • Impact: MEDIUM | Effort: HIGH
   • Solution: Add tests for transaction pipeline, security, edge cases
   • Benefit: Confidence in critical paths

10. No Structured Logging

    • Impact: LOW | Effort: LOW
    • Solution: Add structured request logging (JSON format)
    • Benefit: Debugging, monitoring, audit trail

Future Enablers (Low Priority)

1. No Feature Flags System

   • Impact: LOW | Effort: MEDIUM
   • Solution: Implement feature flags (enables gradual rollout)
   • Benefit: Safer deployments, A/B testing

2. Market Data Requests Sequential (no parallel fallback)

   • Impact: LOW | Effort: LOW
   • Solution: Parallelize Finnhub + Alpha Vantage requests
   • Benefit: Faster response times

3. No API Rate Limiting

   • Impact: LOW | Effort: MEDIUM
   • Solution: Add rate limiting middleware
   • Benefit: Prevent abuse, protect external APIs

---

📊 Architecture Quality Score: 7/10

Strengths: - ✅ Security-first design (encryption, blind indexing, fingerprinting) - ✅ Clean utils layer (market data, LLM, parsers, security modules) - ✅ Flexible LLM routing (Ollama → OpenAI/Gemini) - ✅ Good provider fallback (Finnhub → Alpha Vantage) - ✅ Encrypted transaction storage with searchable indexes

Weaknesses: - ❌ Monolithic main.py (50+ endpoints) - ❌ No API versioning or clear routing structure - ❌ Endpoint ordering dependencies (fragile) - ❌ Frontend theme inconsistency - ❌ Hardcoded categories (inflexible for Budget feature) - ❌ No encryption key rotation strategy

---

🚀 Recommendations for New Features

FinTS Integration (Issue #11)

• Build as new APIRouter: routers/bank_connections.py
• Reuse transaction encryption/dedup pipeline
• Use explicit routing pattern (not monolithic)
• Add tests for HBCI parser

Google Sheets Budget (Issue #12)

• Build as new APIRouter: routers/budgets.py
• Requires: DB-driven categories (Issue #6)
• Make category mapping flexible
• Handle multi-person responsibility tracking

---

For detailed architecture, see System Diagrams.
For full recommendations, see Improvement Roadmap.