# jeevanba273/factor-model-and-smart-beta-portfolio-builder architecture

> Architecture diagram of the GitHub repository jeevanba273/factor-model-and-smart-beta-portfolio-builder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jeevanba273/factor-model-and-smart-beta-portfolio-builder
- Repository: https://github.com/jeevanba273/factor-model-and-smart-beta-portfolio-builder

## Overview

##### Project Type & Purpose
- This is a monolithic, data-driven web application built with Streamlit.
- Purpose: Provide an interactive UI for factor analysis, portfolio construction, and backtesting using CSV-based historical data for the Indian stock market.
- Deployment: Hosted on Railway as a single container/service.

##### File Structure Analysis
- Top-level:
– app.py (entry point containing UI, business logic)
– requirements.txt (Python dependencies)
– data/ (historical CSV files, one per year)
- No separate frontend/backend repos: UI and logic are combined in app.py under Streamlit.
- No external database—local CSV files act as the data store.
- Deployment and environment managed via Railway (per README).

##### README Insights
- UI Layer: Streamlit (page layout, user controls, chart placeholders).
- Business Logic:
– Factor score calculations (value, momentum, low volatility, quality)
– Portfolio construction & rebalancing
– Backtest simulation
- Data Processing: Pandas/NumPy, optional StatsModels
- Visualization: Plotly charts
- Caching: Streamlit’s @st.cache decorator to speed repeated computations
- Hosting: Railway (container + scalable environment)

##### Main Components & Interactions
a. Browser / Client
– Renders Streamlit UI; sends user events (slider changes, date picks, run analysis).
b. Streamlit Server (app.py)
– UI Layer: Streamlit widgets (sliders, date pickers, tabs)
– Controller / Orchestrator: Coordinates UI events → invokes business logic
– Data Access Layer: Reads CSV files from data/ folder
– Business Logic Layer:
- Factor calculation modules (in-memory Pandas pipelines)
- Composite score generation
- Backtest engine (rebalancing loops, performance metrics)
– Cache Layer: Memoizes heavy operations via @st.cache
– Visualization Layer: Generates Plotly figures for the UI
c. Data Storage
– Local file system (data/*.csv). Optionally show “Data Lake” as a generic CSV-based store.
d. Deployment Infrastructure
– GitHub (source control) → Railway CI/CD → Container
– Railway runtime environment (Python 3.12, dependencies from requirements.txt)
e. External References (optional)
– NIFTY 50 index for benchmark comparison (could be an API or preloaded CSV)
– NSE (original data provider—out-of-scope)

##### Architectural Patterns & Design Principles
- Monolithic service: Single container, no microservices.
- Layered approach inside app.py: UI → Controller → Data Access → Business Logic → Visualization.
- Stateless compute functions + caching for idempotent operations.
- Vectorized data processing (Pandas) for performance.
- Separation of concerns: Keep factor formulas, backtest loops, and UI code logically distinct (use functions or modules within app.py).

- Rectangle with rounded corners for UI
- Standard rectangle for compute modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["Browser / Client"]:::ui
    subgraph "Streamlit Server"
        UI["Streamlit UI (Widgets & Layout)"]:::ui
        Controller["Controller / Orchestrator"]:::logic
        DataAccess["Data Access Layer"]:::logic
        FactorCalc["Factor Calculation Modules"]:::logic
        Composite["Composite Score Generation Logic"]:::logic
        Backtest["Backtest Engine"]:::logic
        Cache["Cache Layer (@st.cache)"]:::logic
        Viz["Visualization Layer (Plotly)"]:::logic
    end
    CSV[(CSV Data Store)]:::storage
    GitHub["GitHub (Source Control)"]:::infra
    Railway["Railway CI/CD & Hosting"]:::infra
    Requirements["requirements.txt"]:::infra
    README["README.md"]:::infra

    Browser -->|"User events"| UI
    UI -->|"Invoke workflow"| Controller
    Controller -->|"Read CSV"| DataAccess
    DataAccess -->|"Load data files"| CSV
    Controller -->|"Compute factor scores"| FactorCalc
    FactorCalc -->|"Output factor data"| Composite
    Composite -->|"Provide composite scores"| Backtest
    Backtest -->|"Fetch/cache results"| Cache
    Controller <-->|"Cache lookup"| Cache
    Backtest -->|"Results for charts"| Viz
    Viz -->|"Render Plotly charts"| UI
    UI -->|"Render to browser"| Browser

    GitHub -->|"Push code"| Railway
    Railway -->|"Deploy container"| UI

    click UI "https://github.com/jeevanba273/factor-model-and-smart-beta-portfolio-builder/blob/main/app.py"
    click Controller "https://github.com/jeevanba273/factor-model-and-smart-beta-portfolio-builder/blob/main/app.py"
    click DataAccess "https://github.com/jeevanba273/factor-model-and-smart-beta-portfolio-builder/tree/main/data/"
    click FactorCalc "https://github.com/jeevanba273/factor-model-and-smart-beta-portfolio-builder/blob/main/app.py"
    click Composite "https://github.com/jeevanba273/factor-model-and-smart-beta-portfolio-builder/blob/main/app.py"
    click Backtest "https://github.com/jeevanba273/factor-model-and-smart-beta-portfolio-builder/blob/main/app.py"
    click Cache "https://github.com/jeevanba273/factor-model-and-smart-beta-portfolio-builder/blob/main/app.py"
    click Viz "https://github.com/jeevanba273/factor-model-and-smart-beta-portfolio-builder/blob/main/app.py"
    click CSV "https://github.com/jeevanba273/factor-model-and-smart-beta-portfolio-builder/blob/main/data/data_2010.csv"
    click Requirements "https://github.com/jeevanba273/factor-model-and-smart-beta-portfolio-builder/blob/main/requirements.txt"
    click README "https://github.com/jeevanba273/factor-model-and-smart-beta-portfolio-builder/blob/main/README.md"

    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef logic fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef storage fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
