# minhaj-mhd/stock-prediction architecture

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

- Interactive diagram: https://gitdiagram.com/minhaj-mhd/stock-prediction
- Repository: https://github.com/minhaj-mhd/stock-prediction

## Overview

##### Project type and purpose
- This is a full-stack, real-time stock market price prediction system built with Python’s FastAPI.
- It fetches live data from Yahoo Finance, passes it through an LSTM model, and serves both a REST API and an interactive HTML frontend.

##### File structure
- Top-level files:
- README.md (project description)
- requirements.txt (dependencies)
- train_model.py (offline model training script)
- test/test.py (unit/integration tests)
- app/ directory:
- main.py (FastAPI entry point, defines routes)
- models/models.py (ML model loader, possibly defines how to load LSTM weights)
- schemas.py (Pydantic models for request/response validation)
- services/data_service.py (handles data fetching from Yahoo Finance)
- services/prediction_service.py (wraps the loaded LSTM model to generate forecasts)
- services/templates/index.html (Jinja2 template for the web UI)

##### README for additional insights
- Features emphasize:
- Real-time data fetching
- LSTM-based prediction
- RESTful endpoints
- Interactive visualization

##### Components and interactions
a. Main components:
1) Frontend (index.html + JS/CSS for visualization)
2) FastAPI Web Server (app/main.py)
3) Data Service (app/services/data_service.py)
4) Prediction Service (app/services/prediction_service.py + app/models/models.py)
5) Model Training Pipeline (train_model.py)
6) External Service: Yahoo Finance API
7) Consumer / Client (browser and programmatic API clients)
b. Relationships & data flow:
- The browser/client sends HTTP requests to FastAPI endpoints (e.g., GET /predict).
- FastAPI controllers validate input via Pydantic schemas (schemas.py).
- Controllers invoke Data Service to fetch live stock quotes from Yahoo Finance.
- Raw data flows into the Prediction Service, which uses the loaded LSTM model to generate forecasts.
- The result is returned as JSON or rendered via the Jinja2 HTML template.
- Separately, train_model.py loads historical data, trains or retrains the LSTM, and saves model artifacts for app/models/models.py to load at startup.
c. Architectural patterns and principles:
- Layered architecture:
- Controllers / Routes (main.py)
- Business logic / Services (data and prediction services)
- Models / Persistence (model loader, saved artifacts)
- Presentation (HTML templates)
- Separation of concerns: data fetching, prediction logic, API interface are decoupled.
- Use of Pydantic for input/output validation.
d. Key technologies and frameworks:
- FastAPI (web framework)
- Pydantic (data validation)
- Jinja2 (templating)
- LSTM model (TensorFlow or PyTorch)
- YahooFinance (external data source)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Browser["Web UI / API Client"]:::client
    end

    %% Backend Services
    subgraph "Backend Services"
        subgraph "FastAPI Server"
            Routes["Routes (main.py)"]:::backend
            Schemas["Pydantic Schemas (schemas.py)"]:::backend
            DataSvc["Data Service (data_service.py)"]:::service
            PredSvc["Prediction Service (prediction_service.py)"]:::service
            ModelsLoader["ML Model Loader (models/models.py)"]:::model
            Templates["Templates (index.html)"]:::frontend
        end
        ModelArtifact[(Model Artifacts)]:::artifact
    end

    %% External Service
    YahooCloud(("Yahoo Finance API")):::external

    %% Offline Training Pipeline
    subgraph "Offline Training Pipeline"
        Trainer["train_model.py"]:::offline
        HistData["Historical Data"]:::offline
        SavModel[(Saved Model Artifacts)]:::artifact
    end

    %% Project Files
    subgraph "Project Files"
        README["README.md"]:::docs
        Req["requirements.txt"]:::docs
        Tests["test/test.py"]:::docs
    end

    %% Data intermediate
    DataOut["Live Stock Data"]:::data

    %% Connections - Online Flow
    Browser -->|HTTP GET /predict| Routes
    Routes -->|validate| Schemas
    Routes -->|fetch data| DataSvc
    DataSvc -->|GET quotes| YahooCloud
    YahooCloud -->|return JSON| DataSvc
    DataSvc -->|return data| DataOut
    DataOut -->|input for prediction| PredSvc
    PredSvc -->|load model at startup| ModelArtifact
    PredSvc -->|predict| Routes
    Routes -->|JSON response / HTML| Browser

    %% Connections - Offline Flow
    Trainer -->|train on| HistData
    HistData -->|save artifacts| SavModel
    SavModel -->|deploy to| ModelArtifact

    %% Click Events
    click Templates "https://github.com/minhaj-mhd/stock-prediction/blob/main/app/services/templates/index.html"
    click Routes "https://github.com/minhaj-mhd/stock-prediction/blob/main/app/main.py"
    click Schemas "https://github.com/minhaj-mhd/stock-prediction/blob/main/app/schemas.py"
    click DataSvc "https://github.com/minhaj-mhd/stock-prediction/blob/main/app/services/data_service.py"
    click PredSvc "https://github.com/minhaj-mhd/stock-prediction/blob/main/app/services/prediction_service.py"
    click ModelsLoader "https://github.com/minhaj-mhd/stock-prediction/blob/main/app/models/models.py"
    click Trainer "https://github.com/minhaj-mhd/stock-prediction/blob/main/train_model.py"
    click README "https://github.com/minhaj-mhd/stock-prediction/blob/main/README.md"
    click Req "https://github.com/minhaj-mhd/stock-prediction/blob/main/requirements.txt"
    click Tests "https://github.com/minhaj-mhd/stock-prediction/blob/main/test/test.py"

    %% Styles
    classDef client fill:#FDEBD0,stroke:#E67E22,stroke-width:2px
    classDef backend fill:#D6EAF8,stroke:#3498DB,stroke-width:2px
    classDef service fill:#D5F5E3,stroke:#27AE60,stroke-width:2px
    classDef frontend fill:#F9EBEA,stroke:#C0392B,stroke-width:2px
    classDef model fill:#EBDEF0,stroke:#8E44AD,stroke-width:2px
    classDef artifact fill:#F2F3F4,stroke:#95A5A6,stroke-width:2px,stroke-dasharray: 5 5
    classDef external fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px
    classDef offline fill:#F4F6F7,stroke:#7F8C8D,stroke-width:2px,stroke-dasharray: 5 5
    classDef docs fill:#FEF9E7,stroke:#F39C12,stroke-width:2px
    classDef data fill:#EBF5FB,stroke:#5DADE2,stroke-width:2px
```
