# jasminpradhan/owlex_smart_financial_advisor architecture

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

- Interactive diagram: https://gitdiagram.com/jasminpradhan/owlex_smart_financial_advisor
- Repository: https://github.com/jasminpradhan/owlex_smart_financial_advisor

## Overview

##### What this project is (type + purpose)
**Owlex** is a **full-stack web application**:
- **Frontend:** React SPA that renders dashboards, calculators, charts, profile, and a **chatbot UI**
- **Backend:** Flask REST API with modular structure (auth/routes/models/utils) and an **AI “agent”** layer using **LangGraph** orchestrating **Gemini Flash 2.0**
- **Database:** SQLite for persistence (likely users/auth + profile data + maybe chat history/preferences)
- **Static/seed data:** `backend/data/market_data.json` for market comparisons or recommendation inputs

##### Frontend boundary (`frontend/`)
Key cues:
- `src/pages/*` → page-level routes: `login`, `registration`, `dashboard`
- `src/dashboard/*` → dashboard subviews: `overview`, `returns`
- `src/components/*` → feature components:
- `chatbot.js` (chat UI)
- calculators (`fd.js`, `mfunds.js`, `lscagr.js`)
- `marketcomp.js`, `riskprofilesug.js`, `profile.js`, etc.
- `src/utils/private_route.js` and `src/utils/userContext.js` → **auth gating** + user session context
- Charts: Chart.js/Recharts (not visible as files, but in README)

**Architecture implication:** a React SPA with protected routes that calls Flask endpoints; visual analytics are client-rendered.

##### Backend boundary (`backend/`)
Key cues:
- `backend/main.py` → likely entrypoint to run Flask
- `backend/backend/app.py` → Flask app factory / app setup
- `backend/backend/auth.py` → authentication blueprint/routes
- `backend/backend/bot_routes.py` → chatbot endpoints (API surface for AI)
- `backend/backend/models.py` → ORM/data models (likely SQLite-backed)
- `backend/backend/utils.py` → helpers (token handling, validation, etc.)
- `backend/agent/agent.py` → AI agent workflow; LangGraph orchestration; Gemini calls
- `backend/backend/database.db` → SQLite database file
- `backend/data/market_data.json` → local market dataset for comparisons/recommendations

**Architecture implication:** Flask API with at least two main route groups: **Auth** and **Bot/AI**; models persist to SQLite; agent is a separate module invoked by bot routes.

Shows: React app, Flask API, SQLite DB, Market JSON data, Gemini (external), LangGraph agent module.

Shows: Flask app → Blueprints (`auth.py`, `bot_routes.py`) → services (`agent.py`) → persistence (`models.py`/SQLite) + static data (`market_data.json`) + external Gemini.

At minimum:
- Login/registration flow
- Chatbot conversation / recommendation flow

This repo is small enough that “separating into as many components as possible” is feasible and will improve precision.

##### Frontend ↔ Backend (REST)
- React pages/components → Flask endpoints
- Login/Registration pages → `/auth/*` routes
- Dashboard components → endpoints for profile/returns/market comparisons (if implemented)
- Chatbot component → `/bot/*` routes

##### Backend → Database
- `auth.py` and/or profile endpoints → `models.py` → SQLite
(store users, hashed passwords, risk profile, preferences, maybe chat history)

##### Backend → AI Agent → External LLM
- `bot_routes.py` → `agent/agent.py` (LangGraph workflow) → **Gemini API**
- Then response flows back: Gemini → agent → bot_routes → frontend chatbot UI

##### Backend → Market Data
- `bot_routes.py` or dashboard endpoints → read `market_data.json`
(used for market comparison / context for recommendations)

##### Architectural patterns to explicitly annotate
- **SPA + REST API**: React client consumes Flask JSON endpoints.
- **Flask modularization via Blueprints**: auth routes and bot routes are separated.
- **Agentic workflow boundary**: LangGraph-based orchestration is a distinct “service module” within the backend.
- **External AI provider integration**: Gemini is not part of your deployable system; it’s an external dependency.
- **SQLite for development persistence**: show as a single DB (and optionally note “dev-only” in label).

- “React SPA (MUI, Chart.js/Recharts)”
- “Auth (private routes via JWT/session)”
- “Flask Blueprints: auth.py, bot_routes.py”
- “Agent: LangGraph workflow (agent.py)”
- “SQLite (dev)”
- “Market dataset (JSON)”
- “External LLM API: Gemini Flash 2.0”

##### Agent (LangGraph) optionally pulls
- user profile from SQLite (models)
- market context from `market_data.json`

##### Practical “don’t overthink” checklist (repo-grounded)

- Frontend exists: `frontend/src/*` (pages, components, utils)
- Backend routes exist: `backend/backend/auth.py`, `backend/backend/bot_routes.py`
- Agent exists: `backend/agent/agent.py` (LangGraph/Gemini per README)
- Persistence exists: `backend/backend/database.db`, `backend/backend/models.py`
- Market dataset exists: `backend/data/market_data.json`

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% External Actor
  %% =========================
  User(["User (Browser)"]):::external

  %% =========================
  %% Frontend Boundary
  %% =========================
  subgraph "Frontend (React SPA)"
    direction TB

    FE_Public["Static HTML Shell"]:::frontend
    FE_App["React App Shell & Routing"]:::frontend

    subgraph "Pages"
      direction TB
      FE_Login["Login Page"]:::frontend
      FE_Reg["Registration Page"]:::frontend
      FE_Dash["Dashboard Page"]:::frontend
    end

    subgraph "Dashboard Views"
      direction TB
      FE_Overview["Overview View"]:::frontend
      FE_Returns["Returns View"]:::frontend
    end

    subgraph "Feature Components"
      direction TB
      FE_ChatUI["Chatbot UI"]:::frontend
      FE_Profile["Profile"]:::frontend
      FE_RiskSug["Risk Profile Suggestion"]:::frontend
      FE_MarketComp["Market Comparison"]:::frontend

      subgraph "Calculators"
        direction TB
        FE_FD["FD Calculator"]:::frontend
        FE_MFunds["Mutual Funds Calculator"]:::frontend
        FE_LSCAGR["Lumpsum CAGR Calculator"]:::frontend
      end
    end

    subgraph "Auth & Session Utilities"
      direction TB
      FE_PrivateRoute["PrivateRoute (Auth Gating)"]:::security
      FE_UserCtx["UserContext (Session Store)"]:::security
    end

    FE_Charts["Chart Rendering (Chart.js / Recharts)"]:::frontend
    FE_MUI["UI Kit (MUI)"]:::frontend
  end

  %% =========================
  %% Backend Boundary
  %% =========================
  subgraph "Backend (Flask REST API)"
    direction TB

    BE_Entrypoint["Flask Entrypoint"]:::backend
    BE_App["Flask App Initialization (App Factory / Setup)"]:::backend

    subgraph "Flask Blueprints / Routes"
      direction TB
      BE_Auth["Auth Blueprint (register/login/JWT)"]:::api
      BE_Bot["Bot Routes (chat/recommendations)"]:::api
    end

    subgraph "Backend Modules"
      direction TB
      BE_Utils["Utilities (tokens/hash/validation)"]:::backend
      BE_Models["Models (SQLite-backed)"]:::backend
      BE_Agent["AI Agent (LangGraph workflow)"]:::agent
    end

    DB[(SQLite Database - dev)]:::db
    MarketData[/"Market Dataset (JSON)"/]:::data
  end

  %% =========================
  %% External Dependency
  %% =========================
  Gemini{{"Gemini Flash 2.0 API (External LLM)"}}:::externalAI

  %% =========================
  %% Connections (Vertical-first)
  %% =========================
  User -->|"uses"| FE_App
  FE_Public -->|"bootstraps"| FE_App

  FE_App -->|"routes"| FE_Login
  FE_App -->|"routes"| FE_Reg
  FE_App -->|"routes"| FE_Dash

  FE_Dash -->|"contains"| FE_Overview
  FE_Dash -->|"contains"| FE_Returns

  FE_Dash -->|"renders"| FE_Profile
  FE_Dash -->|"renders"| FE_RiskSug
  FE_Dash -->|"renders"| FE_MarketComp
  FE_Dash -->|"renders"| FE_ChatUI
  FE_Dash -->|"renders"| FE_FD
  FE_Dash -->|"renders"| FE_MFunds
  FE_Dash -->|"renders"| FE_LSCAGR
  FE_Dash -->|"renders"| FE_Charts
  FE_Dash -->|"styles"| FE_MUI

  FE_PrivateRoute -->|"gates"| FE_Dash
  FE_Login -->|"sets_session"| FE_UserCtx
  FE_Reg -->|"sets_session"| FE_UserCtx
  FE_UserCtx -->|"provides_token"| FE_PrivateRoute

  FE_Login -->|"POST_/auth/login"| BE_Auth
  FE_Reg -->|"POST_/auth/register"| BE_Auth
  FE_Dash -->|"GET/POST_API"| BE_App
  FE_ChatUI -->|"POST_/bot/chat"| BE_Bot
  FE_MarketComp -->|"GET_market_context"| BE_App
  FE_Profile -->|"GET/PUT_profile"| BE_App
  FE_RiskSug -->|"GET/POST_risk"| BE_App

  BE_Entrypoint -->|"starts"| BE_App
  BE_App -->|"registers"| BE_Auth
  BE_App -->|"registers"| BE_Bot

  BE_Auth -->|"uses"| BE_Utils
  BE_Auth -->|"CRUD"| BE_Models

  BE_Bot -->|"invokes"| BE_Agent
  BE_Bot -.->|"reads"| MarketData
  BE_Bot -->|"optional_persist"| BE_Models

  BE_Models -->|"reads/writes"| DB

  BE_Agent -->|"LLM_calls"| Gemini
  BE_Agent -.->|"optional_context"| MarketData
  BE_Agent -->|"optional_profile"| BE_Models

  %% =========================
  %% Click Events (paths only)
  %% =========================
  click FE_App "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/frontend/src/App.js"
  click FE_App "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/frontend/src/index.js"
  click FE_Public "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/frontend/public/index.html"

  click FE_Login "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/frontend/src/pages/login.js"
  click FE_Reg "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/frontend/src/pages/registration.js"
  click FE_Dash "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/frontend/src/pages/dashboard.js"

  click FE_Overview "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/frontend/src/dashboard/overview.js"
  click FE_Returns "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/frontend/src/dashboard/returns.js"

  click FE_ChatUI "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/frontend/src/components/chatbot.js"
  click FE_Profile "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/frontend/src/components/profile.js"
  click FE_RiskSug "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/frontend/src/components/riskprofilesug.js"
  click FE_MarketComp "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/frontend/src/components/marketcomp.js"

  click FE_FD "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/frontend/src/components/calculators/fd.js"
  click FE_MFunds "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/frontend/src/components/calculators/mfunds.js"
  click FE_LSCAGR "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/frontend/src/components/calculators/lscagr.js"

  click FE_PrivateRoute "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/frontend/src/utils/private_route.js"
  click FE_UserCtx "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/frontend/src/utils/userContext.js"

  click BE_Entrypoint "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/backend/main.py"
  click BE_App "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/backend/backend/app.py"
  click BE_Auth "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/backend/backend/auth.py"
  click BE_Bot "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/backend/backend/bot_routes.py"
  click BE_Agent "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/backend/agent/agent.py"
  click BE_Models "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/backend/backend/models.py"
  click BE_Utils "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/backend/backend/utils.py"
  click DB "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/backend/backend/database.db"
  click MarketData "https://github.com/jasminpradhan/owlex_smart_financial_advisor/blob/main/backend/data/market_data.json"

  %% =========================
  %% Styles
  %% =========================
  classDef frontend fill:#1e88e5,stroke:#0d47a1,color:#ffffff,stroke-width:1.5px
  classDef backend fill:#1565c0,stroke:#0b2e6b,color:#ffffff,stroke-width:1.5px
  classDef api fill:#0d47a1,stroke:#08244f,color:#ffffff,stroke-width:1.5px
  classDef security fill:#5e35b1,stroke:#311b92,color:#ffffff,stroke-width:1.5px
  classDef agent fill:#fb8c00,stroke:#e65100,color:#1b1b1b,stroke-width:1.5px
  classDef db fill:#2e7d32,stroke:#1b5e20,color:#ffffff,stroke-width:1.5px
  classDef data fill:#90a4ae,stroke:#455a64,color:#111111,stroke-width:1.5px
  classDef external fill:#cfd8dc,stroke:#546e7a,color:#111111,stroke-width:1.5px
  classDef externalAI fill:#ffebee,stroke:#c62828,color:#b71c1c,stroke-width:2px,stroke-dasharray: 5 3
```
