# vruxak21/tradeflow architecture

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

- Interactive diagram: https://gitdiagram.com/vruxak21/tradeflow
- Repository: https://github.com/vruxak21/tradeflow

## Overview

##### Project type and purpose
- TradeFlow is a full‑stack, cross‑platform mobile (and desktop/web) financial application.
- Frontend: Flutter app (Android/iOS/Linux/Mac/Windows/Web).
- Backend: Two Flask‑based Python microservices for API handling and recommendation logic.
- Purpose: Authenticate users, fetch real‑time market data, serve AI chatbot, generate personalized stock recommendations, display analytics and educational content.

##### File structure
- Top‑level “my_app” directory: contains a standard Flutter project (“android/”, “ios/”, “linux/”, “macos/”, “windows/”, “web/”), Dart source under lib/, tests, plus a python_server folder.
- “python_server/”: two entry points (app.py and stock_api.py) plus modules for data ingestion, recommendation, symbol lookups, user input handling.
- Configuration and build files show this is a multi‑platform Flutter project using CMake for desktop targets.
- .yaml files (pubspec.yaml, analysis_options.yaml) declare Flutter/Dart dependencies.

##### README for architectural insights
- Frontend communicates with:
- Firebase (Authentication, Database)
- Flask servers (REST API endpoints)
- Backend communicates with external services:
- yfinance, Alpha Vantage, GNews for market data
- Gemini API for AI chatbot
- Two separate Flask servers are started (app.py, stock_api.py), indicating a microservice approach.

##### Main components
a. Frontend (Flutter app)
– UI Layer: pages, components, widgets.
– Service Layer: Dart services (api_service.dart, stock_service.dart).
b. Authentication & Data Store (Firebase)
– Firebase Auth
– Firestore / Realtime Database
c. Backend Microservices
– Main Flask Server (app.py): handles user requests, AI chatbot, orchestrates recommendation workflow.
– Stock API Server (stock_api.py): dedicated to fetching/processing real‑time stock data.
d. External APIs & Data Sources
– yfinance, Alpha Vantage, GNews for market data and news.
– Gemini API for FinAI Chatbot.
e. User Devices
– Android, iOS, Linux, Mac, Windows, Web browsers.

##### Relationships and interactions
- The Flutter app UI calls Dart service classes which:
- Perform Firebase Auth operations directly.
- Send HTTP(S) requests to the Flask microservices.
- Main Flask Service:
- Validates tokens (Firebase Auth), fetches user profile data from Firebase DB.
- Routes AI chatbot queries to Gemini API.
- Calls Stock API Server or directly uses modules for recommendation logic.
- Persists recommendation history or user inputs back to Firebase DB.
- Stock API Service:
- Receives HTTP requests from Main Flask Service or directly from app.
- Fetches market data from yfinance/Alpha Vantage/GNews.
- Returns cleaned JSON to callers.
- All external services (APIs & Firebase) are over secure HTTPS.

##### Architectural patterns & design principles
- Microservices: Two Flask servers each with a single responsibility.
- Layered Frontend: UI layer separated from networking/services.
- RESTful APIs: JSON over HTTP between Flutter and Flask.
- Cloud‑native: offloading auth and persistence to Firebase.
- Dependency Injection in Dart (service classes) for testability.
- Modular Python code for data, recommendation, and API wrappers.

##### Essential elements
- Clear component labels and groupings.
- Notes on key technologies (Flutter, Dart, Flask, Firebase, yfinance, Alpha Vantage, GNews, Gemini API).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Flutter)" 
        direction TB
        UI["Flutter UI<br/>(pages)"]:::frontend
        Shared["Shared Components<br/>(components)"]:::frontend
        MainEntry["Main Entry Point<br/>(main.dart)"]:::frontend
        APIService["API Service<br/>(api_service.dart)"]:::frontend
        StockService["Stock Service<br/>(stock_service.dart)"]:::frontend
        FirebaseConfig["Firebase Config<br/>(firebase_options.dart)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Python Microservices)"
        direction TB
        MainFlask["Main Flask Service<br/>(app.py)"]:::backend
        StockAPIService["Stock API Service<br/>(stock_api.py)"]:::backend
        subgraph "Modules"
            direction TB
            DataIngestion["Data Ingestion<br/>(stock_data.py)"]:::backend
            Recommender["Recommendation Logic<br/>(stock_recommender.py)"]:::backend
            SymbolLookup["Symbol Lookup<br/>(stock_symbols.py)"]:::backend
            UserInput["User Input Handling<br/>(user_input.py)"]:::backend
        end
        FirebaseAuth["Firebase Auth"]:::datastore
        FirebaseDB["Firebase DB"]:::datastore
    end

    %% External APIs
    subgraph "External Services"
        direction TB
        MarketData["yfinance / Alpha Vantage / GNews"]:::external
        GeminiAPI["Gemini API"]:::external
    end

    %% Client interactions
    UI -->|uses| APIService
    UI -->|uses| StockService
    UI -->|init auth| FirebaseConfig
    APIService -->|HTTPS/JSON| MainFlask
    StockService -->|HTTPS/JSON| StockAPIService
    APIService -->|Auth / Data| FirebaseAuth
    APIService -->|Read/Write| FirebaseDB

    %% Backend orchestrations
    MainFlask -->|Validate Token| FirebaseAuth
    MainFlask -->|Profile Data| FirebaseDB
    MainFlask -->|GET /recommendations| Recommender
    MainFlask -->|User Input| UserInput
    MainFlask -->|Symbol Lookup| SymbolLookup
    MainFlask -->|AI Chat Query| GeminiAPI
    MainFlask -->|Stock Data Request| StockAPIService

    StockAPIService -->|Process Req| DataIngestion
    DataIngestion -->|Fetch / Clean| MarketData

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#000;
    classDef backend fill:#FFE4B5,stroke:#d2691e,color:#000;
    classDef datastore fill:#D0FFD6,stroke:#228B22,color:#000;
    classDef external fill:#F0F0F0,stroke:#888,color:#000;

    %% Click events
    click UI "https://github.com/vruxak21/tradeflow/tree/main/my_app/lib/pages/"
    click Shared "https://github.com/vruxak21/tradeflow/tree/main/my_app/lib/components/"
    click MainEntry "https://github.com/vruxak21/tradeflow/blob/main/my_app/lib/main.dart"
    click APIService "https://github.com/vruxak21/tradeflow/blob/main/my_app/lib/services/api_service.dart"
    click StockService "https://github.com/vruxak21/tradeflow/blob/main/my_app/lib/services/stock_service.dart"
    click FirebaseConfig "https://github.com/vruxak21/tradeflow/blob/main/my_app/lib/firebase_options.dart"
    click MainFlask "https://github.com/vruxak21/tradeflow/blob/main/my_app/python_server/app.py"
    click StockAPIService "https://github.com/vruxak21/tradeflow/blob/main/my_app/python_server/stock_api.py"
    click DataIngestion "https://github.com/vruxak21/tradeflow/blob/main/my_app/python_server/stock_data.py"
    click Recommender "https://github.com/vruxak21/tradeflow/blob/main/my_app/python_server/stock_recommender.py"
    click SymbolLookup "https://github.com/vruxak21/tradeflow/blob/main/my_app/python_server/stock_symbols.py"
    click UserInput "https://github.com/vruxak21/tradeflow/blob/main/my_app/python_server/user_input.py"
```
