# code-ph0enix/finedge architecture

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

- Interactive diagram: https://gitdiagram.com/code-ph0enix/finedge
- Repository: https://github.com/code-ph0enix/finedge

## Overview

##### Project type and purpose
- FinEdge is a full-stack AI-driven personal finance management and investment advisory platform.
- Frontend: React + TypeScript application built with Vite and Tailwind CSS, rendering dashboards, onboarding flows, chat, and data-visualizations.
- Backend: Python Flask REST API implementing business logic, AI services (Gemini, OpenAI), data models, and integrations with external market/stock data and authentication providers.

##### File structure
Top-level separation:
- frontend/ – React UI code (components, pages, services, hooks, context)
- backend/ – Flask application, AI modules, data layer, utility scripts, backups, legacy code
Key observations in backend/:
- app.py – Flask application factory
- database.py & models.py – data layer
- ai_financial_advisor.py, recommendations.py, financial_journey.py, learning_progress.py – core business/AI logic
- /tools – internal helper scripts
- data-input.json, fin-path.json – sample data
- .env.example, requirements.txt – configuration
Frontend structure highlights:
- src/pages – high-level routes (Chatbot, Home, Learn, etc.)
- src/components – reusable UI pieces (ChatInput, DashboardLayout, Onboarding steps, etc.)
- src/services & src/utils – wrappers around HTTP calls (chatApi, stockApi, onboardingApi)
- src/context – global state (OnboardingContext, ThemeContext, TourContext)

##### README insights
- Clean architecture, Flask app factory, RESTful API design
- Unified AI service pattern (“FinancialAIService”)
- External integrations: Gemini AI, stock/market/ news APIs, OAuth providers
- Emphasis on separation of concerns and centralized error handling

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Browser["User Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend (React UI)"
        direction TB
        OnboardingUI["Onboarding Components"]:::frontend
        subgraph "Chatbot UI"
            direction TB
            ChatbotPage["Chatbot.tsx"]:::frontend
            ChatInput["ChatInput.tsx"]:::frontend
            ChatMessage["ChatMessage.tsx"]:::frontend
            ChatHeader["ChatHeader.tsx"]:::frontend
        end
        subgraph "Dashboard & Visualization"
            direction TB
            DashboardLayout["DashboardLayout.tsx"]:::frontend
            MarketMarquee["MarketMarquee.tsx"]:::frontend
            MoneyPulse["MoneyPulse.tsx"]:::frontend
        end
        RoutingPages["Pages (Home, Learn, MarketAnalysis)"]:::frontend
        subgraph "HTTP Service Wrappers"
            direction TB
            ChatApi["chatApi.ts"]:::service
            OnboardingApi["onboardingApi.ts"]:::service
            StockApi["stockApi.ts"]:::service
        end
        subgraph "Global State Context"
            direction TB
            OnboardingCtx["OnboardingContext.tsx"]:::frontend
            ThemeCtx["ThemeContext.tsx"]:::frontend
            TourCtx["TourContext.tsx"]:::frontend
        end
    end

    %% API Gateway
    APIGateway["API Gateway / HTTP Layer"]:::api

    %% Backend Layer
    subgraph "Backend Application (Flask)"
        direction TB
        AppFactory["app.py"]:::api
        subgraph "API Layer"
            direction TB
            LearningRoutes["learning_routes.py"]:::api
            OnboardRoutes["onboard.py"]:::api
        end
        subgraph "Service Layer"
            direction TB
            AIService["ai_financial_advisor.py"]:::service
            RecService["recommendations.py"]:::service
            JourneyService["financial_journey.py"]:::service
            LearningService["learning_progress.py"]:::service
        end
        subgraph "Data Layer"
            direction TB
            DBModule["database.py"]:::data
            Models["models.py"]:::data
        end
        subgraph "Utilities & Helpers"
            direction TB
            Tools["tools/mytools.py"]:::util
            SampleData["data-input.json\nfin-path.json"]:::util
            Backups["backups/"]:::util
        end
    end

    %% Database and External
    Database["Database (PostgreSQL)"]:::data
    ExternalAI["Gemini/OpenAI"]:::external
    MarketData["Market Data APIs"]:::external
    ExternalAuth["OAuth Providers"]:::external

    %% Connections
    Browser -->|interacts with| OnboardingUI
    Browser -->|opens| ChatbotPage
    Browser -->|views| DashboardLayout
    Browser -->|navigates| RoutingPages

    OnboardingUI -->|uses| OnboardingApi
    ChatbotPage -->|calls| ChatApi
    DashboardLayout -->|fetches| StockApi

    OnboardingApi -->|HTTP| APIGateway
    ChatApi -->|HTTP| APIGateway
    StockApi -->|HTTP| APIGateway

    OnboardingCtx --> OnboardingUI
    ThemeCtx --> OnboardingUI
    TourCtx --> OnboardingUI

    APIGateway -->|routes to| AppFactory
    AppFactory -->|registers| LearningRoutes
    AppFactory -->|registers| OnboardRoutes

    LearningRoutes -->|invoke| AIService
    OnboardRoutes -->|invoke| JourneyService
    AIService -->|use| RecService
    AIService -->|use| LearningService

    JourneyService --> DBModule
    LearningService --> DBModule
    RecService --> MarketData
    AIService --> ExternalAI
    AppFactory --> ExternalAuth

    DBModule --> Models
    DBModule --> Database

    Tools -.-> AppFactory
    Tools --> SampleData
    Tools --> Backups

    %% Click Events
    click OnboardingUI "https://github.com/code-ph0enix/finedge/tree/main/frontend/src/components/onboarding"
    click ChatbotPage "https://github.com/code-ph0enix/finedge/blob/main/frontend/src/pages/Chatbot.tsx"
    click ChatInput "https://github.com/code-ph0enix/finedge/blob/main/frontend/src/components/ChatInput.tsx"
    click ChatMessage "https://github.com/code-ph0enix/finedge/blob/main/frontend/src/components/ChatMessage.tsx"
    click ChatHeader "https://github.com/code-ph0enix/finedge/blob/main/frontend/src/components/ChatHeader.tsx"
    click DashboardLayout "https://github.com/code-ph0enix/finedge/blob/main/frontend/src/components/DashboardLayout.tsx"
    click MarketMarquee "https://github.com/code-ph0enix/finedge/blob/main/frontend/src/components/MarketMarquee.tsx"
    click MoneyPulse "https://github.com/code-ph0enix/finedge/blob/main/frontend/src/components/MoneyPulse.tsx"
    click RoutingPages "https://github.com/code-ph0enix/finedge/tree/main/frontend/src/pages"
    click ChatApi "https://github.com/code-ph0enix/finedge/blob/main/frontend/src/utils/chatApi.ts"
    click OnboardingApi "https://github.com/code-ph0enix/finedge/blob/main/frontend/src/utils/onboardingApi.ts"
    click StockApi "https://github.com/code-ph0enix/finedge/blob/main/frontend/src/services/stockApi.ts"
    click OnboardingCtx "https://github.com/code-ph0enix/finedge/blob/main/frontend/src/context/OnboardingContext.tsx"
    click ThemeCtx "https://github.com/code-ph0enix/finedge/blob/main/frontend/src/context/ThemeContext.tsx"
    click TourCtx "https://github.com/code-ph0enix/finedge/blob/main/frontend/src/context/TourContext.tsx"
    click AppFactory "https://github.com/code-ph0enix/finedge/blob/main/backend/app.py"
    click LearningRoutes "https://github.com/code-ph0enix/finedge/blob/main/backend/learning_routes.py"
    click OnboardRoutes "https://github.com/code-ph0enix/finedge/blob/main/backend/onboard.py"
    click AIService "https://github.com/code-ph0enix/finedge/blob/main/backend/ai_financial_advisor.py"
    click RecService "https://github.com/code-ph0enix/finedge/blob/main/backend/recommendations.py"
    click JourneyService "https://github.com/code-ph0enix/finedge/blob/main/backend/financial_journey.py"
    click LearningService "https://github.com/code-ph0enix/finedge/blob/main/backend/learning_progress.py"
    click DBModule "https://github.com/code-ph0enix/finedge/blob/main/backend/database.py"
    click Models "https://github.com/code-ph0enix/finedge/blob/main/backend/models.py"
    click SampleData "https://github.com/code-ph0enix/finedge/blob/main/backend/data-input.json"
    click Tools "https://github.com/code-ph0enix/finedge/blob/main/backend/tools/mytools.py"
    click Backups "https://github.com/code-ph0enix/finedge/tree/main/backend/backups/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef api fill:#D6F5D6,stroke:#28A745,color:#28A745
    classDef service fill:#FFE4B5,stroke:#FFA500,color:#8B4000
    classDef data fill:#FFFACD,stroke:#FFD700,color:#B8860B
    classDef util fill:#F0F0F0,stroke:#CCCCCC,color:#666666
    classDef external fill:#E8E8E8,stroke:#A9A9A9,color:#555555
```
