# rahuulsharmaa/stockmaster architecture

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

- Interactive diagram: https://gitdiagram.com/rahuulsharmaa/stockmaster
- Repository: https://github.com/rahuulsharmaa/stockmaster

## Overview

##### Main Components
a. Frontend/UI Layer:
- Jinja2 Templates (located in the “templates” directory). This is where the HTML pages are defined.
- Static assets such as CSS, JavaScript, and images (inside “static”).
b. Backend/API Layer:
- FastAPI application defined in “main.py”. This is the entry point of the application.
- Routes (inside the “routes” folder) that handle incoming HTTP requests for different functionalities (e.g., analytics, authentication, market API, prediction routes, stock API, websocket communication).
c. Service/Business Logic Layer:
- Services (in the “services” directory) include market service, prediction service, stock service, and a WebSocket manager. These encapsulate business logic and handle complex operations like accessing models and performing predictions.
- Utility functions (in the “utils” directory) that support authentication and possibly other cross-cutting concerns.
d. Data Access Layer:
- Database module (in the “database” folder) which contains the connection settings, CRUD operations, and models representing database entities. It is connected to PostgreSQL via SQLAlchemy/asyncpg as mentioned in the README.
e. Machine Learning Models:
- LSTM-based prediction models are stored in the “models” folder and are utilized by the prediction service.
f. Caching Mechanism:
- The “cache” directory contains precomputed/pickled data, which suggests caching of computation or query results for efficiency.

##### Relationships and Interactions
- The client (browser) interacts with the application via HTTP requests which hit the routes.
- The routes parse the request and delegate tasks to the services.
- Services invoke business logic such as making predictions using LSTM models from the “models” directory or accessing real-time stock data.
- For persistence, services call the database layer’s CRUD operations to interact with PostgreSQL.
- WebSockets (managed by the service in “services/websocket_manager.py” and routes in “routes/websocket.py”) provide real-time data updates.
- Utility functions support authentication, session management, and other small tasks across layers.

##### Architectural Patterns and Design Principles
- Layered Architecture: The project separates concerns across presentation (templates), API routes, business logic (services), and data access (database).
- MVC-like Pattern: While not a strict MVC, the division of routes (controller), templates (views), and business logic with models reflects an MVC style.
- Micro-modular Services: Each functionality (stock API, prediction, analytics, etc.) is modularized into its own route and service file for clarity and maintainability.
- Caching Strategy: The existence of a “cache” directory indicates the use of caching to improve performance, especially for heavy prediction computations or repeated requests.

##### Relevant Technologies
- FastAPI as the web framework managing asynchronous API calls.
- Jinja2 for template rendering.
- PostgreSQL for the relational database.
- SQLAlchemy/asyncpg as the ORM/database engine.
- LSTM models used for prediction stored as .pkl files.
- Python as the main programming language, with appropriate environment setup through “venv”.

##### Detail
- Every component—small directories like “utils” and “cache”—is represented if it plays a part in the data flow.
- Don’t shy away from separating components into finer details (e.g., differentiate between various routes like “auth”, “analytics”, “prediction”, etc.) to capture the complete picture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Client["Browser (Client)"]:::client

    %% Frontend Layer
    subgraph "Frontend Layer"
        Jinja2["Jinja2 Templates"]:::frontend
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        FAST["FastAPI App (main.py)"]:::backend
        Routes["HTTP Routes"]:::backend
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        Services["Services"]:::service
        AuthUtils["Auth Utils"]:::service
    end

    %% Data & ML Layer
    subgraph "Data & ML Layer"
        Database["Database Module (PostgreSQL)"]:::database
        LSTM["LSTM Models"]:::ml
        Cache["Cache"]:::cache
    end

    %% Connections
    Client -->|"HTTPRequest"| FAST
    FAST -->|"Dispatch"| Routes
    Routes -->|"Delegate"| Services
    Routes -->|"Render"| Jinja2
    Services -->|"CRUD"| Database
    Services -->|"Predict"| LSTM
    Services -->|"CacheOps"| Cache
    Routes <-->|"WebSocket"| Services

    %% Click Events
    click Jinja2 "https://github.com/rahuulsharmaa/stockmaster/tree/main/templates/"
    click FAST "https://github.com/rahuulsharmaa/stockmaster/blob/main/main.py"
    click Routes "https://github.com/rahuulsharmaa/stockmaster/tree/main/routes/"
    click Services "https://github.com/rahuulsharmaa/stockmaster/tree/main/services/"
    click AuthUtils "https://github.com/rahuulsharmaa/stockmaster/blob/main/utils/auth_utils.py"
    click Database "https://github.com/rahuulsharmaa/stockmaster/tree/main/database/"
    click LSTM "https://github.com/rahuulsharmaa/stockmaster/tree/main/models/"
    click Cache "https://github.com/rahuulsharmaa/stockmaster/tree/main/cache/"

    %% Styles
    classDef client fill:#F0F9FF,stroke:#3399FF,stroke-width:2px;
    classDef frontend fill:#DDEEFF,stroke:#66AAFF,stroke-width:2px;
    classDef backend fill:#FFEECC,stroke:#FFAA33,stroke-width:2px;
    classDef service fill:#E8FFD9,stroke:#66CC66,stroke-width:2px;
    classDef database fill:#FFE0E0,stroke:#FF6666,stroke-width:2px;
    classDef ml fill:#FFF0D9,stroke:#FF9933,stroke-width:2px;
    classDef cache fill:#E0E0FF,stroke:#6666FF,stroke-width:2px;
```
