# harshads7/relulu architecture

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

- Interactive diagram: https://gitdiagram.com/harshads7/relulu
- Repository: https://github.com/harshads7/relulu

## Overview

##### Project Type and Purpose
- This is a full-stack forecasting application:
– Frontend: Next.js/React UI for visualizing alerts, backtests, risk metrics, and analyst dashboards.
– Backend: Python service exposing REST endpoints, running the forecast engine, backtesting, alerting, and training GNN models.

##### Top-Level Components
- Frontend (Next.js)
– Pages: alerts, backtest, analyst, risk
– Shared UI components: charts, timelines, metric cards, ticker bars
– Theme context, global CSS, fonts
- Backend API
– app.py: main web server (e.g., FastAPI/Flask)
– routes.py & schemas.py: HTTP endpoints & data contracts
– ticker.py: real-time data feeder
- Core Services
– forecast_engine.py: runs prediction workflows
– backtest.py / optimize.py / alerts.py: business logic modules
– analyst.py: domain-specific analyses
- Data Layer
– loader.py & constants.py: read raw data from files or external sources
- Machine-Learning Models
– super_node_gnn.py & temporal_gnn.py: GNN architectures
– training scripts: train_temporal.py, train_legacy.py
– artifacts: super_node_v1.pth
- Utility Scripts
– dashboard, netting_report, simulation, stress_test, run_forecast_test

##### Interactions and Data Flow
1. User → Frontend UI
– Clicks buttons in Next.js pages
2. Frontend → Backend API
– HTTP calls to /alerts, /backtest, /forecast, etc.
3. API → Core Services
– Parses request schemas → invokes forecast_engine, backtest, or alerts
4. Core → Data Layer & Models
– loader.py fetches input data
– forecast_engine loads ML model (.pth) and runs inference
5. Core → Response
– Structures results via schemas → returns JSON to frontend
6. Optional: Scripts & Training
– Offline: training scripts read data, train GNNs, write model files
– Reporting scripts generate CSV/XLS dashboards

##### Architectural Patterns
- Layered (Controller → Service → Data / Model)
- Separation of concerns:
– Frontend (presentation)
– API (transport)
– Core (business logic)
– Models (ML inference/training)
- Extensibility points:
– Add new routes in backend/api
– Plug in new GNN architectures under backend/models
– Extend UI by adding pages/components in frontend/src/app

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User Browser"]:::user

    %% Frontend Layer
    subgraph "Frontend (Next.js)"
        Alerts["alerts page"]:::frontend
        Backtest["backtest page"]:::frontend
        Analyst["analyst page"]:::frontend
        Risk["risk page"]:::frontend
        ForecastChart["ForecastChart"]:::frontend
        TickerBar["TickerBar"]:::frontend
    end

    %% API Layer
    subgraph "Backend API"
        Server["app.py"]:::api
        Routes["routes.py"]:::api
        Schemas["schemas.py"]:::api
    end

    %% Core Services
    subgraph "Core Services"
        Forecast["ForecastEngine"]:::core
        BacktestS["Backtest"]:::core
        AlertsS["Alerts"]:::core
    end

    %% Data & Models Layer
    subgraph "Data & Models"
        Loader["loader.py"]:::data
        Constants["constants.py"]:::data
        GNN1["super_node_gnn.py"]:::models
        GNN2["temporal_gnn.py"]:::models
        Artifact["super_node_v1.pth"]:::models
    end

    %% Utility & Reporting Scripts
    subgraph "Utility Scripts"
        Dashboard["dashboard.py"]:::scripts
        Netting["netting_report.py"]:::scripts
        ForecastTest["run_forecast_test.py"]:::scripts
    end

    %% Flows
    User -->|"clicks page"| Alerts
    User -->|"clicks page"| Backtest
    User -->|"clicks page"| Analyst
    User -->|"clicks page"| Risk

    Alerts -->|"/alerts"| Server
    Backtest -->|"/backtest"| Server
    Analyst -->|"/analyst"| Server
    Risk -->|"/risk"| Server

    Server -->|invokes| Forecast
    Server -->|invokes| BacktestS
    Server -->|invokes| AlertsS

    Forecast -->|loads data| Loader
    Forecast -->|loads model| Artifact
    Forecast -->|runs GNNs| GNN1
    Forecast -->|runs GNNs| GNN2

    Forecast -->|returns results| Server
    Server -->|JSON response| Alerts
    Server -->|JSON response| Backtest
    Server -->|JSON response| Analyst
    Server -->|JSON response| Risk

    %% Click Events - Frontend Pages
    click Alerts "https://github.com/harshads7/relulu/blob/main/frontend/src/app/alerts/page.tsx"
    click Backtest "https://github.com/harshads7/relulu/blob/main/frontend/src/app/backtest/page.tsx"
    click Analyst "https://github.com/harshads7/relulu/blob/main/frontend/src/app/analyst/page.tsx"
    click Risk "https://github.com/harshads7/relulu/blob/main/frontend/src/app/risk/page.tsx"

    %% Click Events - Shared Components
    click ForecastChart "https://github.com/harshads7/relulu/blob/main/frontend/src/app/components/ForecastChart.tsx"
    click TickerBar "https://github.com/harshads7/relulu/blob/main/frontend/src/app/components/TickerBar.tsx"

    %% Click Events - API Layer
    click Server "https://github.com/harshads7/relulu/blob/main/backend/app.py"
    click Routes "https://github.com/harshads7/relulu/blob/main/backend/api/routes.py"
    click Schemas "https://github.com/harshads7/relulu/blob/main/backend/api/schemas.py"

    %% Click Events - Core Services
    click Forecast "https://github.com/harshads7/relulu/blob/main/backend/core/forecast_engine.py"
    click BacktestS "https://github.com/harshads7/relulu/blob/main/backend/core/backtest.py"
    click AlertsS "https://github.com/harshads7/relulu/blob/main/backend/core/alerts.py"

    %% Click Events - Data & Models
    click Loader "https://github.com/harshads7/relulu/blob/main/backend/data/loader.py"
    click Constants "https://github.com/harshads7/relulu/blob/main/backend/data/constants.py"
    click GNN1 "https://github.com/harshads7/relulu/blob/main/backend/models/super_node_gnn.py"
    click GNN2 "https://github.com/harshads7/relulu/blob/main/backend/models/temporal_gnn.py"
    click Artifact "https://github.com/harshads7/relulu/blob/main/backend/super_node_v1.pth"

    %% Click Events - Utility Scripts
    click Dashboard "https://github.com/harshads7/relulu/blob/main/backend/scripts/dashboard.py"
    click Netting "https://github.com/harshads7/relulu/blob/main/backend/scripts/netting_report.py"
    click ForecastTest "https://github.com/harshads7/relulu/blob/main/backend/scripts/run_forecast_test.py"

    %% Styles
    classDef user fill:#ffffff,stroke:#000000
    classDef frontend fill:#ADD8E6,stroke:#0000FF,color:#000000
    classDef api fill:#90EE90,stroke:#008000,color:#000000
    classDef core fill:#20B2AA,stroke:#008B8B,color:#000000
    classDef models fill:#FFA500,stroke:#FF8C00,color:#000000
    classDef data fill:#D3D3D3,stroke:#A9A9A9,color:#000000
    classDef scripts fill:#D3D3D3,stroke:#696969,color:#000000
```
