# aayushgokhale2005/finfreedom architecture

> Architecture diagram of the GitHub repository aayushgokhale2005/finfreedom, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aayushgokhale2005/finfreedom
- Repository: https://github.com/aayushgokhale2005/finfreedom

## Overview

FinFreedom is a stock-analysis product: users browse or search symbols, inspect market data and indicators, and receive AI recommendations; authenticated users also have protected dashboard access. The frontend calls the FastAPI service, which routes stock and insight requests through market-data, caching, persistence, and prediction services. The repository also contains a distinct algorithm research/training and backtesting toolkit. Relationships below are limited to README statements and supplied source/index evidence; unsampled routes and frontend request wiring are not inferred.

Main entry points: [`backend/app/routes/stocks_v2.py`](https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/routes/stocks_v2.py) (Stock API routes), [`backend/main.py`](https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/main.py) (FastAPI app), [`finfreedom_algo/main.py`](https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/main.py) (Analysis orchestrator), [`backend/app/services/ai_model_service.py`](https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/services/ai_model_service.py) (Prediction service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web experience"]
  node_frontend["Pages and dashboard"]
  node_stockpage["Symbol details<br/>[page.tsx]"]
  node_aiwidget["AI insights UI<br/>[AIInsights.tsx]"]
  node_authui["Authentication UI<br/>[AuthContext.tsx]"]
  node_firebase["Firebase client<br/>[firebase.ts]"]
end

subgraph group_api["API and market data"]
  node_api_main["FastAPI app<br/>[main.py]"]
  node_stocks_route["Stock API routes<br/>[stocks_v2.py]"]
  node_auth_route["Auth routes<br/>[auth.py]"]
  node_insight_route["Insight routes<br/>[ai_insights.py]"]
  node_stock_service["Market data service<br/>[stock_service.py]"]
  node_cache["TTL cache and limiter<br/>[cache_service.py]"]
  node_search["Symbol search index<br/>[search_index.py]"]
  node_universe["S&amp;P 500 universe<br/>[sp500_universe.py]"]
  node_firestore["User and stock data"]
  node_firestore_db[("Firestore")]
end

subgraph group_insights["AI analysis"]
  node_ai_service["Prediction service"]
  node_recommendation["Recommendation service"]
  node_live_data["Live market analysis"]
end

subgraph group_algo["Algorithm toolkit"]
  node_algorithm["Analysis orchestrator<br/>[main.py]"]
  node_features["Technical features"]
  node_recommend_system["Technical recommendations"]
  node_ml_model["Model training<br/>[model.py]"]
  node_ml_prediction["Model predictions<br/>[prediction.py]"]
  node_historical_data["Historical data fetch<br/>[get_stock_data.py]"]
  node_cleaning["Data cleaning<br/>[data_cleaning.py]"]
  node_decision["Model selection<br/>[decision_maker.py]"]
  node_probabilistic["Probabilistic trading"]
  node_evaluation["Evaluation workflow<br/>[eval_results.py]"]
  node_backtesting["Backtesting<br/>[backtesting.py]"]
end

node_visitor(("Stock user"))

node_visitor -->|"browses"| node_frontend
node_frontend -->|"opens symbols"| node_stockpage
node_frontend -->|"authenticates"| node_authui
node_stockpage -.->|"requests stock data"| node_stocks_route
node_aiwidget -.->|"requests insights"| node_insight_route
node_authui -.->|"uses auth client"| node_firebase
node_api_main -->|"registers router"| node_stocks_route
node_api_main -->|"registers router"| node_auth_route
node_api_main -->|"registers router"| node_insight_route
node_api_main -->|"initializes"| node_search
node_api_main -->|"loads tickers"| node_universe
node_stocks_route -->|"calls"| node_stock_service
node_stocks_route -->|"uses"| node_cache
node_stocks_route -->|"calls"| node_firestore
node_stocks_route -->|"requests predictions"| node_ai_service
node_stocks_route -->|"uses ticker list"| node_universe
node_stock_service -->|"reads and writes"| node_cache
node_firestore -.->|"reads and writes"| node_firestore_db
node_ai_service -->|"uses analysis"| node_evaluation
node_ai_service -->|"uses models"| node_probabilistic
node_ai_service -->|"uses selection"| node_decision
node_recommendation -->|"requests live data"| node_live_data
node_algorithm -->|"computes features"| node_features
node_algorithm -->|"generates recommendation"| node_recommend_system
node_algorithm -->|"runs predictions"| node_ml_prediction
node_algorithm -->|"integrates models"| node_ml_model
node_recommend_system -->|"uses"| node_features
node_recommend_system -->|"uses"| node_live_data
node_ml_model -->|"preprocesses with"| node_cleaning
node_ml_model -->|"loads data via"| node_historical_data
node_ml_prediction -->|"loads data via"| node_historical_data
node_evaluation -->|"loads data via"| node_historical_data
node_evaluation -->|"uses predictions"| node_probabilistic
node_evaluation -->|"selects model"| node_decision
node_backtesting -->|"uses"| node_cleaning
node_backtesting -->|"uses"| node_probabilistic
node_backtesting -->|"uses"| node_decision

click node_frontend "https://github.com/aayushgokhale2005/finfreedom/tree/main/frontend/src/app"
click node_stockpage "https://github.com/aayushgokhale2005/finfreedom/blob/main/frontend/src/app/stock/%5Bsymbol%5D/page.tsx"
click node_aiwidget "https://github.com/aayushgokhale2005/finfreedom/blob/main/frontend/src/components/AIInsights.tsx"
click node_authui "https://github.com/aayushgokhale2005/finfreedom/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_firebase "https://github.com/aayushgokhale2005/finfreedom/blob/main/frontend/src/lib/firebase.ts"
click node_api_main "https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/main.py"
click node_stocks_route "https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/routes/stocks_v2.py"
click node_auth_route "https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/routes/auth.py"
click node_insight_route "https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/routes/ai_insights.py"
click node_stock_service "https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/services/stock_service.py"
click node_cache "https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/services/cache_service.py"
click node_search "https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/services/search_index.py"
click node_universe "https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/data/sp500_universe.py"
click node_firestore "https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/services/firestore_service.py"
click node_ai_service "https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/services/ai_model_service.py"
click node_recommendation "https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/services/recommendation_service.py"
click node_live_data "https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/live_data_service.py"
click node_algorithm "https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/main.py"
click node_features "https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/stock_feature_calculation.py"
click node_recommend_system "https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/recommendation_system.py"
click node_ml_model "https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/ML/model.py"
click node_ml_prediction "https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/ML/prediction.py"
click node_historical_data "https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/get_stock_data.py"
click node_cleaning "https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/data_cleaning.py"
click node_decision "https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/decision_maker.py"
click node_probabilistic "https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/probabilistic_trading.py"
click node_evaluation "https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/eval_results.py"
click node_backtesting "https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/backtesting.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_stockpage,node_aiwidget,node_authui,node_firebase,node_visitor toneBlue
class node_api_main,node_stocks_route,node_auth_route,node_insight_route,node_stock_service,node_cache,node_search,node_universe,node_firestore,node_firestore_db toneAmber
class node_ai_service,node_recommendation,node_live_data toneMint
class node_algorithm,node_features,node_recommend_system,node_ml_model,node_ml_prediction,node_historical_data,node_cleaning,node_decision,node_probabilistic,node_evaluation,node_backtesting toneRose
```

## Components

### Web experience

- [Pages and dashboard](https://github.com/aayushgokhale2005/finfreedom/tree/main/frontend/src/app): `frontend/src/app`
- [Symbol details](https://github.com/aayushgokhale2005/finfreedom/blob/main/frontend/src/app/stock/%5Bsymbol%5D/page.tsx): `frontend/src/app/stock/[symbol]/page.tsx`
- [AI insights UI](https://github.com/aayushgokhale2005/finfreedom/blob/main/frontend/src/components/AIInsights.tsx): `frontend/src/components/AIInsights.tsx`
- [Authentication UI](https://github.com/aayushgokhale2005/finfreedom/blob/main/frontend/src/contexts/AuthContext.tsx): `frontend/src/contexts/AuthContext.tsx`
- [Firebase client](https://github.com/aayushgokhale2005/finfreedom/blob/main/frontend/src/lib/firebase.ts): `frontend/src/lib/firebase.ts`

### API and market data

- [FastAPI app](https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/main.py): `backend/main.py`
- [Stock API routes](https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/routes/stocks_v2.py): `backend/app/routes/stocks_v2.py`
- [Auth routes](https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/routes/auth.py): `backend/app/routes/auth.py`
- [Insight routes](https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/routes/ai_insights.py): `backend/app/routes/ai_insights.py`
- [Market data service](https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/services/stock_service.py): `backend/app/services/stock_service.py`
- [TTL cache and limiter](https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/services/cache_service.py): `backend/app/services/cache_service.py`
- [Symbol search index](https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/services/search_index.py): `backend/app/services/search_index.py`
- [S&P 500 universe](https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/data/sp500_universe.py): `backend/app/data/sp500_universe.py`
- [User and stock data](https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/services/firestore_service.py): `backend/app/services/firestore_service.py`
- **Firestore**

### AI analysis

- [Prediction service](https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/services/ai_model_service.py): `backend/app/services/ai_model_service.py`
- [Recommendation service](https://github.com/aayushgokhale2005/finfreedom/blob/main/backend/app/services/recommendation_service.py): `backend/app/services/recommendation_service.py`
- [Live market analysis](https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/live_data_service.py): `finfreedom_algo/live_data_service.py`

### Algorithm toolkit

- [Analysis orchestrator](https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/main.py): `finfreedom_algo/main.py`
- [Technical features](https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/stock_feature_calculation.py): `finfreedom_algo/stock_feature_calculation.py`
- [Technical recommendations](https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/recommendation_system.py): `finfreedom_algo/recommendation_system.py`
- [Model training](https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/ML/model.py): `finfreedom_algo/ML/model.py`
- [Model predictions](https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/ML/prediction.py): `finfreedom_algo/ML/prediction.py`
- [Historical data fetch](https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/get_stock_data.py): `finfreedom_algo/get_stock_data.py`
- [Data cleaning](https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/data_cleaning.py): `finfreedom_algo/data_cleaning.py`
- [Model selection](https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/decision_maker.py): `finfreedom_algo/decision_maker.py`
- [Probabilistic trading](https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/probabilistic_trading.py): `finfreedom_algo/probabilistic_trading.py`
- [Evaluation workflow](https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/eval_results.py): `finfreedom_algo/eval_results.py`
- [Backtesting](https://github.com/aayushgokhale2005/finfreedom/blob/main/finfreedom_algo/backtesting.py): `finfreedom_algo/backtesting.py`

### Other components

- **Stock user**

## Connections

- Stock user → Pages and dashboard: browses (evidence: `README.md`)
- Pages and dashboard → Symbol details: opens symbols (evidence: `README.md`)
- Pages and dashboard → Authentication UI: authenticates (evidence: `README.md`)
- Symbol details → Stock API routes: requests stock data
- AI insights UI → Insight routes: requests insights
- Authentication UI → Firebase client: uses auth client
- FastAPI app → Stock API routes: registers router (evidence: `backend/main.py`)
- FastAPI app → Auth routes: registers router (evidence: `backend/main.py`)
- FastAPI app → Insight routes: registers router (evidence: `backend/main.py`)
- FastAPI app → Symbol search index: initializes (evidence: `backend/main.py`)
- FastAPI app → S&P 500 universe: loads tickers (evidence: `backend/main.py`)
- Stock API routes → Market data service: calls (evidence: `backend/app/routes/stocks_v2.py`)
- Stock API routes → TTL cache and limiter: uses (evidence: `backend/app/routes/stocks_v2.py`)
- Stock API routes → User and stock data: calls (evidence: `backend/app/routes/stocks_v2.py`)
- Stock API routes → Prediction service: requests predictions (evidence: `backend/app/routes/stocks_v2.py`)
- Stock API routes → S&P 500 universe: uses ticker list (evidence: `backend/app/routes/stocks_v2.py`)
- Market data service → TTL cache and limiter: reads and writes (evidence: `backend/app/services/stock_service.py`)
- User and stock data → Firestore: reads and writes
- Prediction service → Evaluation workflow: uses analysis (evidence: `backend/app/services/ai_model_service.py`)
- Prediction service → Probabilistic trading: uses models (evidence: `backend/app/services/ai_model_service.py`)
- Prediction service → Model selection: uses selection (evidence: `backend/app/services/ai_model_service.py`)
- Recommendation service → Live market analysis: requests live data (evidence: `backend/app/services/recommendation_service.py`)
- Analysis orchestrator → Technical features: computes features (evidence: `finfreedom_algo/main.py`)
- Analysis orchestrator → Technical recommendations: generates recommendation (evidence: `finfreedom_algo/main.py`)
- Analysis orchestrator → Model predictions: runs predictions (evidence: `finfreedom_algo/main.py`)
- Analysis orchestrator → Model training: integrates models (evidence: `finfreedom_algo/main.py`)
- Technical recommendations → Technical features: uses (evidence: `finfreedom_algo/recommendation_system.py`)
- Technical recommendations → Live market analysis: uses (evidence: `finfreedom_algo/recommendation_system.py`)
- Model training → Data cleaning: preprocesses with (evidence: `finfreedom_algo/ML/model.py`)
- Model training → Historical data fetch: loads data via (evidence: `finfreedom_algo/ML/model.py`)
- Model predictions → Historical data fetch: loads data via (evidence: `finfreedom_algo/ML/prediction.py`)
- Evaluation workflow → Historical data fetch: loads data via (evidence: `finfreedom_algo/eval_results.py`)
- Evaluation workflow → Probabilistic trading: uses predictions (evidence: `finfreedom_algo/eval_results.py`)
- Evaluation workflow → Model selection: selects model (evidence: `finfreedom_algo/eval_results.py`)
- Backtesting → Data cleaning: uses (evidence: `finfreedom_algo/backtesting.py`)
- Backtesting → Probabilistic trading: uses (evidence: `finfreedom_algo/backtesting.py`)
- Backtesting → Model selection: uses (evidence: `finfreedom_algo/backtesting.py`)
