How jacobobernalgonzalez/financeai works
FinanceAI is a Docker-deployed full-stack web app:
• Frontend: React SPA (frontend/src/*, package.json, frontend/Dockerfile)
• Backend: FastAPI service (backend/app/main.py, backend/app/__init__.py)
• Persistence: PostgreSQL (declared in README; typically wired via docker-compose.yml)
• Caching: Redis (README; typically used to cache predictions/categorizations)
• ML layer inside backend: scikit-learn models for:
• Transaction categorization (Random Forest + TF-IDF + amount features)
• Anomaly detection (Isolation Forest)
• Spending prediction (Linear Regression)
(backend/app/services/ml.py, backend/test_ml.py)
• Optional external integration: OpenAI API (chatbot feature; needs key)
• DB initialization script: backend/init_db.py run after compose up
So the “system” is not microservices; it’s a single backend service that contains both the API and the ML inference logic, plus separate infra containers (Postgres/Redis) and an external API.
Backend (FastAPI)
• backend/app/main.py → API entrypoint (routers/endpoints live here or are imported here)
• backend/app/core/config.py → Configuration / env management (show as “Config/Secrets: .env” feeding backend)
• backend/app/models/db.py → DB access layer (ORM/queries; show as a component that talks to Postgres)
• backend/app/services/ml.py → ML service (feature extraction + model inference; show explicitly as a subcomponent)
Frontend (React)
• frontend/src/App.js, index.js, public/index.html → SPA in browser
• Frontend calls backend via HTTP (REST) to manage transactions, fetch dashboard data, request predictions/categorizations, etc.
System Context (who uses it, what it depends on)
• User
• FinanceAI Web App
• OpenAI API (optional external dependency)
• User ↔ FinanceAI (browser usage)
• FinanceAI → OpenAI API (only for chatbot flows)
This view communicates scope and external dependency without implementation noise.
Redis container
• Browser → Frontend: “GET / (static assets)”
• Browser/Frontend → Backend: “HTTPS/HTTP REST API (JSON)”
• Backend → PostgreSQL: “SQL (transactions, categories, users, …)”
• Backend → Redis: “Cache (predictions, categorization results, sessions/ratelimits if any)”
• Backend → OpenAI API: “Chatbot prompts/completions (optional)”
• Admin/Dev (or init job) → Backend or directly → PostgreSQL: “init_db.py creates tables + seeds data”
Make Redis and Postgres first-class (they’re explicitly part of the stack in README; don’t hide them in a note).
Use the backend folder structure to justify these internal components:
Backend (FastAPI) components:
• API Layer (FastAPI app)
Source anchor: backend/app/main.py
• Config / Settings
Source anchor: backend/app/core/config.py (reads env vars; DB URL, Redis URL, OpenAI key)
• DB Access / Models
Source anchor: backend/app/models/db.py
• ML Service
Source anchor: backend/app/services/ml.py
• (Optional) OpenAI Client
Even if it’s inside ml.py or another module, show as a distinct component that calls the external API when enabled.
• “Create transaction”:
• API → DB (persist raw transaction)
• API → ML Service (categorize + anomaly score)
• ML Service → Redis (cache results)
• API → DB (store category/anomaly metadata) *or* return to client
• “Dashboard / analytics”:
• API → DB (aggregate spend)
• API → ML Service (predictions)
• ML Service → Redis (cache)
• “Chatbot” (optional):
• API → OpenAI Client → OpenAI API → API → Frontend
What to include because Docker is the deployment story here
Since the repo has docker-compose.yml + Dockerfiles, add a Deployment View (even if it’s simple):
• One “Docker Host” boundary
• Inside: frontend container, backend container, postgres container, redis container
• Exposed ports (label if known/standard):
• Frontend: typically 3000
• Backend: typically 8000
• Postgres: 5432 (internal)
• Redis: 6379 (internal)
• .env feeding compose/config (secrets/keys)
Labels
• Source anchors in small text (e.g., services/ml.py) for credibility and navigability.
• “HTTP/JSON”
• “SQL”
• “Redis GET/SET”
• “HTTPS (OpenAI)”