# shubhamnayak1708/mars architecture

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

- Interactive diagram: https://gitdiagram.com/shubhamnayak1708/mars
- Repository: https://github.com/shubhamnayak1708/mars

## Overview

##### Project Type and Purpose
- MarS is a domain‐specific, full‐stack financial market simulation engine.
- Core functionality lives in the “mlib” library (the simulation engine), while “market_simulation” provides domain wrappers, example scripts, demos, and model serving.
- It integrates a generative foundation model (the Large Market Model) for realistic order‐level simulation and exposes both batch scripts and interactive demos (Streamlit, Ray Serve).

##### File Structure Analysis
Top‐level directories
- .devcontainer, .github, scripts – Dev & CI/CD setup (VS Code Dev Container, Dockerfile, GitHub Actions, pre‐commit hooks).
- mlib – Core simulation engine:
– core: Env, Engine, Exchange, States, Agents abstractions, Orderbook, Events, Transactions.
– utils: time utilities, progress-bar, tests for core functionality.
- market_simulation – Domain‐specific layer:
– conf.py: configuration of data paths and model serving.
– agents: background_agent, noise_agent, trading_agent.
– models: order_model logic, HF wrapper for uploading/downloading.
– rollout: Ray Serve server (order_model_serving), client (model_client).
– states: specific State subclasses (order_state, trans_state, trade_info_state).
– examples & demo: batch scripts (stylized facts, forecast, market impact, run_simulation) and Streamlit apps.
- download.py: one‐step data & converter download.
- scripts: install, run pre‐commit, start-order-model server.
- setup.py, pyproject.toml – packaging.
- ray_serving.yaml – Ray Serve deployment config.

##### README Insights
- High‐level overview: MarS engine + generative LMM + four downstream applications (stylized facts, forecasting, market impact, interactive demo).
- Technical stack: Python 3.11+, Gym‐like interface, Ray Serve for model serving, Streamlit for UI, Docker for environment.

##### Main Components
- Development & Deployment layer: VS Code Dev Container / Docker, GitHub Actions (CI), Ray cluster.
- Core Simulation Engine (mlib):
– Env & Engine
– Exchange & Exchange Config
– States (order_state, trans_state, trade_info_state)
– Agents (Noise, Trading, Background)
– Orderbook, Events, Transactions
- Domain Layer (market_simulation):
– Configuration (conf.py)
– Model Logic (order_model.py, HF wrapper)
– Rollout Service (Ray Serve server + ModelClient)
– Example Scripts & Streamlit Demos
- External Services & Data:
– OneDrive data store for converters & stylized facts data
– Hugging Face model repository (private)
– Ray Serve (distributed inference)

##### Relationships & Data Flows
- Agent → Action → Engine.process_event() → Exchange updates → State.on_open/on_trading/on_close → Agents consume new State → loop.
- Example scripts instantiate Env, register Agents and States, push Exchange events (market open/close), then iterate simulation.
- OrderModel is exposed via Ray Serve:
- order_model_serving launches a Ray Serve endpoint.
- ModelClient in rollout and examples sends requests (Prediction) → Ray Serve → LMM model → returns tokenized orders.

##### Architectural Patterns & Design Principles
- Layered Architecture: separation between core engine (mlib), domain wrappers (market_simulation), and presentation (demos/UI).
- Publish–Subscribe: State updates trigger Agents; zero‐copy state sharing.
- Client–Server: Model serving via Ray Serve; ModelClient abstracts RPC.
- Modular & Pluggable: custom Agents, States, Exchange configurations.
- Infrastructure as Code: Docker, Dev Container, GitHub workflows.

##### Capturing Essential Elements
- Configuration files (conf.py, ray_serving.yaml) as annotation in the infrastructure layer.
- Download.py and OneDrive/HF repository as external data sources feeding into conf.py and model server.
- Test coverage in mlib/test and CI workflow to show quality gates.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        direction TB
        DevDocker["Dev Container / Docker"]:::infra
        CI["GitHub Actions (Lint, Test)"]:::infra
        RayCluster["Ray Cluster & Serve"]:::infra
        RayConfig["ray_serving.yaml"]:::infra
        StartOrder["Start Order Model Script"]:::infra
    end

    %% External Data & Download
    subgraph "External Data & Utilities"
        direction TB
        Download["download.py"]:::external
        BinConverter["Bin Converter"]:::external
        PKLUtils["Pickle Utils"]:::external
        OneDrive["OneDrive Data Store"]:::external
        HFRepo["Hugging Face Repo"]:::external
    end

    %% Core Simulation Engine
    subgraph "mlib Core Engine"
        direction TB
        Env["Env"]:::core
        Engine["Engine"]:::core
        Exchange["Exchange"]:::core
        ExchangeConfig["Exchange Config"]:::core
        StateCore["State"]:::core
        AgentsCore["Agents"]:::core
        Orderbook["Orderbook"]:::core
        Events["Events"]:::core
        Transactions["Transactions"]:::core
    end

    %% Domain Layer
    subgraph "market_simulation Domain Layer"
        direction TB
        Conf["conf.py"]:::domain
        subgraph "Agents"
            direction TB
            BackgroundAgent["Background Agent"]:::domain
            NoiseAgent["Noise Agent"]:::domain
            TradingAgent["Trading Agent"]:::domain
        end
        subgraph "States"
            direction TB
            OrderState["Order State"]:::domain
            TransState["Trans State"]:::domain
            TradeInfoState["Trade Info State"]:::domain
        end
        subgraph "Model Logic"
            direction TB
            OrderModel["OrderModel Logic"]:::domain
            HFWr["HF Wrapper"]:::domain
        end
        subgraph "Rollout Service"
            direction TB
            Serve["OrderModel Serving"]:::domain
            ModelClient["ModelClient"]:::domain
        end
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        subgraph "Batch Example Scripts"
            direction TB
            ForecastScript["forecast.py"]:::presentation
            MarketImpactScript["market_impact.py"]:::presentation
            StylizedFacts["report_stylized_facts.py"]:::presentation
            RunSim["run_simulation.py"]:::presentation
        end
        subgraph "Streamlit Demos"
            direction TB
            HomeApp["home_app.py"]:::presentation
            ForecastApp["forecast_app.py"]:::presentation
            ImpactApp["market_impact_app.py"]:::presentation
        end
    end

    %% External flows
    Download -->|feeds config| Conf
    BinConverter -->|used by| Conf
    PKLUtils -->|used by| Conf
    OneDrive -->|data source| Conf
    HFRepo -->|model source| OrderModel

    %% Infrastructure to components
    DevDocker -->|provisions| Env
    CI -->|tests| Engine
    RayCluster -->|hosts| Serve
    RayConfig -->|deploys| Serve
    StartOrder -->|launches| Serve

    %% Core simulation loop
    AgentsCore -->|action| Engine
    Engine -->|process_event| Exchange
    Exchange -->|update| StateCore
    StateCore -->|notify| AgentsCore
    ExchangeConfig -->|configures| Exchange
    Orderbook -->|records| Exchange
    Events -->|drive| Engine
    Transactions -->|record| Engine

    %% Domain integration
    Conf -->|configures| Env
    BackgroundAgent -->|implements| AgentsCore
    NoiseAgent -->|implements| AgentsCore
    TradingAgent -->|implements| AgentsCore
    OrderState -->|extends| StateCore
    TransState -->|extends| StateCore
    TradeInfoState -->|extends| StateCore
    OrderModel -->|wrapped by| HFWr
    Serve -->|serves| OrderModel
    ModelClient -->|requests| Serve
    ModelClient -->|used by| ForecastScript
    ModelClient -->|used by| MarketImpactScript
    ModelClient -->|used by| StylizedFacts
    ModelClient -->|used by| RunSim
    HomeApp -->|calls| ModelClient
    ForecastApp -->|calls| ModelClient
    ImpactApp -->|calls| ModelClient

    %% Click Events
    click DevDocker "https://github.com/shubhamnayak1708/mars/tree/main/.devcontainer/Dockerfile"
    click CI "https://github.com/shubhamnayak1708/mars/blob/main/.github/workflows/codeql.yml"
    click RayConfig "https://github.com/shubhamnayak1708/mars/blob/main/ray_serving.yaml"
    click StartOrder "https://github.com/shubhamnayak1708/mars/blob/main/scripts/start-order-model.sh"
    click Download "https://github.com/shubhamnayak1708/mars/blob/main/download.py"
    click BinConverter "https://github.com/shubhamnayak1708/mars/blob/main/market_simulation/utils/bin_converter.py"
    click PKLUtils "https://github.com/shubhamnayak1708/mars/blob/main/market_simulation/utils/pkl_utils.py"
    click Engine "https://github.com/shubhamnayak1708/mars/blob/main/mlib/core/engine.py"
    click Env "https://github.com/shubhamnayak1708/mars/blob/main/mlib/core/env.py"
    click Exchange "https://github.com/shubhamnayak1708/mars/blob/main/mlib/core/exchange.py"
    click ExchangeConfig "https://github.com/shubhamnayak1708/mars/blob/main/mlib/core/exchange_config.py"
    click StateCore "https://github.com/shubhamnayak1708/mars/blob/main/mlib/core/state.py"
    click Events "https://github.com/shubhamnayak1708/mars/blob/main/mlib/core/event.py"
    click Transactions "https://github.com/shubhamnayak1708/mars/blob/main/mlib/core/transaction.py"
    click Orderbook "https://github.com/shubhamnayak1708/mars/blob/main/mlib/core/orderbook.py"
    click OrderModel "https://github.com/shubhamnayak1708/mars/blob/main/market_simulation/models/order_model.py"
    click HFWr "https://github.com/shubhamnayak1708/mars/blob/main/market_simulation/models/hf_wrapper/upload.py"
    click Serve "https://github.com/shubhamnayak1708/mars/blob/main/market_simulation/rollout/order_model_serving.py"
    click ModelClient "https://github.com/shubhamnayak1708/mars/blob/main/market_simulation/rollout/model_client.py"
    click ForecastScript "https://github.com/shubhamnayak1708/mars/blob/main/market_simulation/examples/forecast.py"
    click MarketImpactScript "https://github.com/shubhamnayak1708/mars/blob/main/market_simulation/examples/market_impact.py"
    click StylizedFacts "https://github.com/shubhamnayak1708/mars/blob/main/market_simulation/examples/report_stylized_facts.py"
    click RunSim "https://github.com/shubhamnayak1708/mars/blob/main/market_simulation/examples/run_simulation.py"
    click HomeApp "https://github.com/shubhamnayak1708/mars/blob/main/market_simulation/examples/demo/home_app.py"
    click ForecastApp "https://github.com/shubhamnayak1708/mars/blob/main/market_simulation/examples/demo/forecast_app.py"
    click ImpactApp "https://github.com/shubhamnayak1708/mars/blob/main/market_simulation/examples/demo/market_impact_app.py"

    %% Styles
    classDef infra fill:#cccccc,stroke:#333,stroke-width:1px
    classDef core fill:#a0c4ff,stroke:#333,stroke-width:1px
    classDef domain fill:#b5e48c,stroke:#333,stroke-width:1px
    classDef presentation fill:#ffb703,stroke:#333,stroke-width:1px
    classDef external fill:#cdb4db,stroke:#333,stroke-width:1px
```
