# h1ppox99/hackathon_mit_mcp-or architecture

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

- Interactive diagram: https://gitdiagram.com/h1ppox99/hackathon_mit_mcp-or
- Repository: https://github.com/h1ppox99/hackathon_mit_mcp-or

## Overview

##### Project type and purpose
- This is a full-stack, data-driven web application (“Optimal Freight Route Planner”)
- Backend (Python + FastAPI via uvicorn)
- Solver engine (gurobipy LP model)
- Data preprocessing modules (CSV, GeoPackage, Java JAR for searoute)
- Frontend (HTML/CSS/JS, Node.js/npm)
- External services (Claude via MCP, searoute CLI)

##### File structure
- Top level
- main.py: FastAPI entrypoint
- solver.py: encapsulates Gurobi model
- normalize_routes.py, calculate_means.py, csv_editor.py, etc.: utility scripts
- data/: raw & intermediary CSV/GeoJSON/GeoPackage files
- src/data_preprocess/: ETL pipelines, add_city, maritime/road utilities, searoute JAR & scripts
- index.html, page2.html, script.js, styles.css: frontend UI
- package.json, node_modules: frontend dependencies
- send_to_claude(.py/.sh): integration with Claude via MCP server

##### Key architecture insights from README
- Backend serves REST API to frontend and handles on-the-fly city additions
- Solver module solves an LP based on user preferences (time/price/CO₂)
- Frontend visualizes routes on a map, accepts dynamic user inputs
- Claude integration for real-time data ingestion (traffic, weather)
- Data pipeline generates and normalizes multimodal graph (road/air/sea)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Client"
        direction TB
        IndexHTML["index.html"]:::frontend
        Page2HTML["page2.html"]:::frontend
        ScriptJS["script.js"]:::frontend
        StylesCSS["styles.css"]:::frontend
        PackageJSON["package.json"]:::frontend
        NodeModules["node_modules/"]:::frontend
    end

    %% Backend Layer
    subgraph "API Gateway / Backend Server"
        direction TB
        FastAPIServer["FastAPI Server"]:::backend
        PyProject["pyproject.toml"]:::backend
        UVLock["uv.lock"]:::backend
    end

    %% Solver Service
    subgraph "Solver Service"
        SolverService["Gurobi Solver"]:::solver
    end

    %% Data Ingestion & Preprocessing Pipeline
    subgraph "Data Ingestion & Preprocessing Pipeline"
        direction TB
        Pipeline["pipeline.py"]:::data
        AddCity["add_city.py"]:::data
        subgraph "Utils"
            direction TB
            CO2Price["add_CO2_price.py"]:::data
            TrainLine["add_train_line.py"]:::data
            LatLong["get_lat_long.py"]:::data
            MaritimeRoutes["get_maritime_routes.py"]:::data
            Roads["get_roads.py"]:::data
            JSON2Maritime["json_to_maritime.py"]:::data
        end
        Normalize["normalize_routes.py"]:::data
        CalcMeans["calculate_means.py"]:::data
        CsvEditor["csv_editor.py"]:::data
    end

    %% Storage Layer
    subgraph "Route Database / Storage"
        direction TB
        RawData["data/raw/"]:::storage
        InterData["data/intermediary/"]:::storage
        Routes["data/routes.csv"]:::storage
        RoutesClean["data/routes_clean.csv"]:::storage
        MarnetStore["marnet/"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Claude["Claude (MCP)"]:::external
        subgraph "Searoute CLI"
            direction TB
            SearouteJar["searoute.jar"]:::external
            SearouteSh["searoute.sh"]:::external
            SearouteBat["searoute.bat"]:::external
            SearouteMarnet["marnet/"]:::external
        end
        SendClaudePy["send_to_claude.py"]:::external
        SendClaudeSh["send_to_claude.sh"]:::external
    end

    %% Relationships
    IndexHTML -->|REST API calls| FastAPIServer
    Page2HTML -->|REST API calls| FastAPIServer
    ScriptJS -->|REST API calls| FastAPIServer

    FastAPIServer -->|reads/writes| RawData
    FastAPIServer -->|reads/writes| InterData
    FastAPIServer -->|reads/writes| Routes
    FastAPIServer -->|reads/writes| RoutesClean

    FastAPIServer -->|invoke| Pipeline
    Pipeline -->|uses| AddCity
    Pipeline -->|uses| CO2Price
    Pipeline -->|uses| TrainLine
    Pipeline -->|uses| LatLong
    Pipeline -->|uses| MaritimeRoutes
    Pipeline -->|uses| Roads
    Pipeline -->|uses| JSON2Maritime
    Pipeline -->|executes| Normalize
    Pipeline -->|executes| CalcMeans
    Pipeline -->|executes| CsvEditor
    Pipeline -->|reads| RawData
    Pipeline -->|writes| InterData
    Pipeline -->|calls| SearouteJar
    Pipeline -->|calls| SearouteSh
    Pipeline -->|calls| SearouteBat
    Pipeline -->|stores| SearouteMarnet

    FastAPIServer -->|invoke| SolverService
    SolverService -->|returns results| FastAPIServer
    FastAPIServer -->|calls| Claude
    FastAPIServer -->|calls| SendClaudePy
    FastAPIServer -->|calls| SendClaudeSh

    SolverService -->|reads| InterData
    SolverService -->|reads| RoutesClean

    %% Click Events
    click IndexHTML "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/index.html"
    click Page2HTML "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/page2.html"
    click ScriptJS "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/script.js"
    click StylesCSS "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/styles.css"
    click PackageJSON "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/package.json"
    click NodeModules "https://github.com/h1ppox99/hackathon_mit_mcp-or/tree/main/node_modules/"

    click FastAPIServer "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/main.py"
    click PyProject "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/pyproject.toml"
    click UVLock "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/uv.lock"

    click SolverService "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/solver.py"

    click Pipeline "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/src/data_preprocess/pipeline.py"
    click AddCity "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/src/data_preprocess/add_city.py"
    click CO2Price "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/src/data_preprocess/utils/add_CO2_price.py"
    click TrainLine "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/src/data_preprocess/utils/add_train_line.py"
    click LatLong "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/src/data_preprocess/utils/get_lat_long.py"
    click MaritimeRoutes "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/src/data_preprocess/utils/get_maritime_routes.py"
    click Roads "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/src/data_preprocess/utils/get_roads.py"
    click JSON2Maritime "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/src/data_preprocess/utils/json_to_maritime.py"
    click Normalize "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/normalize_routes.py"
    click CalcMeans "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/calculate_means.py"
    click CsvEditor "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/csv_editor.py"

    click RawData "https://github.com/h1ppox99/hackathon_mit_mcp-or/tree/main/data/raw/"
    click InterData "https://github.com/h1ppox99/hackathon_mit_mcp-or/tree/main/data/intermediary/"
    click Routes "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/data/routes.csv"
    click RoutesClean "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/data/routes_clean.csv"
    click MarnetStore "https://github.com/h1ppox99/hackathon_mit_mcp-or/tree/main/marnet/"

    click SearouteJar "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/src/data_preprocess/searoute/searoute.jar"
    click SearouteSh "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/src/data_preprocess/searoute/searoute.sh"
    click SearouteBat "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/src/data_preprocess/searoute/searoute.bat"
    click SearouteMarnet "https://github.com/h1ppox99/hackathon_mit_mcp-or/tree/main/src/data_preprocess/searoute/marnet/"

    click SendClaudePy "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/send_to_claude.py"
    click SendClaudeSh "https://github.com/h1ppox99/hackathon_mit_mcp-or/blob/main/send_to_claude.sh"

    %% Styles
    classDef frontend fill:#D0E7FF,stroke:#333,stroke-width:1px
    classDef backend fill:#DFFFE0,stroke:#333,stroke-width:1px
    classDef data fill:#FFF2CC,stroke:#333,stroke-width:1px
    classDef storage fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef external fill:#E3E4FA,stroke:#333,stroke-width:1px
    classDef solver fill:#FFF4E6,stroke:#333,stroke-width:1px
```
