How hwacho9/finance-procject works
Project Type and Purpose
• This is a full-stack, containerized Web application: a real-time macro-finance dashboard.
• Frontend (React/TypeScript, Tailwind, React Query, Recharts/D3.js) will consume data from the FastAPI backend.
• Backend (FastAPI, SQLAlchemy, Pydantic) exposes REST endpoints, schedules background updates, and persists time-series data.
• Data stores: PostgreSQL (primary), Redis (cache/session).
• External services: Yahoo Finance, FRED API, Alpha Vantage.
• Deployment: Docker Compose orchestrates backend, database, and Redis containers.
File Structure and Architectural Patterns
• backend/app/api/v1 – routers grouped by domain (market, economic, scheduler).
• backend/app/services – business logic layer, with a “providers” subpackage implementing a provider abstraction (DIP + SRP).
• backend/app/core – configuration, database initialization.
• backend/app/models & schemas – ORM models vs. Pydantic schemas (clear separation of concerns).
• docker-compose.yml – three services: backend, db, redis.
• database/init.sql – schema bootstrap.
• Tests follow TDD; they live under backend/app/tests.
Main Components
• Frontend UI (React app)
• API Gateway / FastAPI Server
• Routers (market, economic, scheduler)
• Service Layer (market_data_service, economic_data_service, data_scheduler)
• Provider Interfaces & Implementations (Yahoo, FRED, Alpha Vantage)
• Scheduler Worker (background process within FastAPI or separate container)
• PostgreSQL Database (tables: economic_indicators, update_logs, data_quality_checks, market_indices, etc.)
• Redis Cache / Session Store
• External APIs (Yahoo Finance, FRED, Alpha Vantage)
• Container Orchestration (Docker Compose)
Interactions and Data Flow
• [Frontend] → HTTP → [FastAPI Router]
• Router → calls → Service Layer
• Service Layer → (a) in-memory cache via Redis lookup/write, (b) repository → PostgreSQL, (c) calls Provider → External API
• Scheduler → triggers scheduled jobs in Data Scheduler Service → Provider → Database
• Health-check endpoints ↔ frontend or monitoring tool
• Docker Compose ensures all containers networked together (backend connects to db, redis; env vars configure URLs)
Architectural Patterns & Principles
• Layered Architecture: Controllers → Services → Providers → Data Stores
• SOLID:
• SRP – each provider handles one data source; each service handles one domain
• DIP – high-level services depend on provider interfaces, not implementations
• TDD: test files mirror service classes
• Asynchronous I/O: FastAPI + async providers
• Container-based DevOps: Dockerfiles + docker-compose.yml for local/dev/prod parity
Detail
• Caching logic: Service → Redis before hitting external API or DB.
• Init.sql step as part of the Database initialization in Docker Compose.
• Environment variable injection for service URLs and API keys.