Bogieflow

Others monitor the rail. We monitor the ballast.

Climate-aware track-bed risk evaluation and agent-based telemetry fusion for railways.

▶ Live Demo  ·  Releases

---

Table of Contents

1. Why It Matters
2. What It Does
3. Screenshot Gallery
4. System Architecture
5. Quickstart & Local Installation
6. One-Click Deployment
7. Tech Stack
8. Project Structure
9. Verification & Testing
10. Judging Criteria Alignment
11. Roadmap
12. Honesty Box

---

Why It Matters

Monsoon rains saturate railway ballast, leading to loss of stiffness, subgrade erosion, and mud pumping under dynamic loads. Left unmonitored, this causes severe track geometry degradation and poses high risks of derailment. Because physical geometry inspection trains are run infrequently, track defects are often detected too late.

Bogieflow provides a continuous, automated digital-twin evaluation framework that fuses real-time climate hydrology, rolling bogie z-axis acceleration telemetry, and a machine learning classifier to predict, prioritize, and quantify avoided railway failures.

---

What It Does

Feature	Description	Status
64-Frame Corridor Scrub	Scroll or mousewheel-controlled high-fidelity view of the corridor.	Verified
Real-time Segment HUD	Color-coded segments S1-S6 displaying status dynamically.	Verified
Multi-Agent Telemetry Fusion	Fuses Hydrology (wetness) and Vibration (z-axis z-scores) telemetry.	Verified
Quantified Avoided-Failure Impact	Live calculations of prevented-failure cost ($USD), inspection-hours saved, and derailment risk reduction % (estimates based on active risk and open tickets).	Verified
Avoided-Failure Forecasting	Projects risk index 30 minutes ahead using step trends, exposing time-to-critical ETAs and ranked segment inspection priorities.	Verified
Live Weather Toggle	Fuses live Open-Meteo API data per segment coordinates with a 10-minute cache, falling back to simulation parameters cleanly.	Verified
Explainable AI (XAI)	Interrogates Gradient Boosting model feature importances and pulls plain-language rationales (Gemini API with offline local fallback templates).	Verified
Risk Model Card	GET /api/model/card exposes CV accuracy, macro F1, ROC-AUC, confusion matrix, and Real/Synthetic training provenance (docs/DATA.md).	Verified (v1.7.0)
Scenario Replay & Demo	Playbacks for Monsoon sweeps, bearing faults, or resets; client-side demo fallback when no backend WebSocket.	Verified (demo on Vercel; live REST when backend connected)
Interactive Tour Coach	Step-by-step tour guides and chatbot to explain telemetry anomalies.	Verified

---

Screenshot Gallery

Overview — status bar, corridor feed scrub, risk gauge, and impact panels	Analysis View - 3D Bogie Model, Stiffness Chart, and Authorize Action
Maintenance View - Prioritized Work Tickets and Decision Logs	Climate View - Precipitation Heatmap and Longevity Estimates
Quantified impact — avoided cost, inspection hours, derailment risk reduction	Explainable AI — feature importances and plain-language ticket rationale

Motion demo: see assets/demo.mp4 locally, or run a live inject from the Overview scenario menu.

---

System Architecture

The following diagram illustrates the flow of telemetry data through the specialized agent systems, the classification model, the WebSocket hub, and the React frontend.

flowchart TD
    %% Subgraph 1: Control & Ingestion
    subgraph INGEST [Control & Ingest]
        Scan[Sidebar scan / Ops strip] -->|POST /inject| REST[REST Inject API]
    end

    %% Subgraph 2: Processing Pipeline
    subgraph PIPELINE [Telemetry & Analysis Pipeline]
        Train[Train Position] -->|z-acceleration| Vib[Vibration Agent]
        Segments[S1 to S6] -->|moisture/rainfall| Hydro[Hydrology Agent]
        
        Hydro -->|stiffness index| ML[ML Risk Classifier]
        Vib -->|rolling z-score| ML
        
        Hydro -->|wetness report| Plan[Planner Agent]
        ML -->|predicted tier| Plan
    end

    %% Subgraph 3: Real-Time Display
    subgraph DISPLAY [Real-Time Display]
        WS[WebSocket Hub]
        WS -->|live track state| Scrub[Corridor feed scrub]
        WS -->|system risk index| Gauge[Risk gauge + metrics]
        WS -->|work tickets| Maint[Maintenance view]
    end

    %% Cross-subgraph connections
    REST -->|Force Anomaly| Segments
    Train -->|position stream| WS
    Segments -->|stiffness stream| WS
    Plan -->|dispatch tickets| WS

    %% Styling
    style INGEST fill:#0e1014,stroke:#243041,stroke-width:2px,color:#ffffff
    style PIPELINE fill:#111820,stroke:#ff5545,stroke-width:2px,color:#ffffff
    style DISPLAY fill:#0e1014,stroke:#243041,stroke-width:2px,color:#ffffff

    style Scan fill:#161f2a,stroke:#8b99aa,color:#ffffff
    style REST fill:#161f2a,stroke:#8b99aa,color:#ffffff
    style Train fill:#161f2a,stroke:#8b99aa,color:#ffffff
    style Segments fill:#161f2a,stroke:#8b99aa,color:#ffffff
    style Hydro fill:#161f2a,stroke:#8b99aa,color:#ffffff
    style Vib fill:#161f2a,stroke:#8b99aa,color:#ffffff
    style ML fill:#161f2a,stroke:#8b99aa,color:#ffffff
    style Plan fill:#161f2a,stroke:#8b99aa,color:#ffffff
    style WS fill:#ff5545,stroke:#ffffff,color:#ffffff
    style Scrub fill:#161f2a,stroke:#8b99aa,color:#ffffff
    style Gauge fill:#161f2a,stroke:#8b99aa,color:#ffffff
    style Maint fill:#161f2a,stroke:#8b99aa,color:#ffffff

Loading

Data Flow Detail: Every 500 ms, the asynchronous simulation loop ticks, moving the train position. Telemetry parameters are evaluated by rule-based Hydrology and Vibration agents. They feed a Gradient Boosting Classifier (scikit-learn), which determines the track risk tier (OK, P2, P1). The Planner Agent evaluates these tiers to issue or upgrade work tickets, broadcasting updates over a WebSocket Hub to React clients.

---

Quickstart & Local Installation

Prerequisites

• Python 3.11 or higher
• Node.js 20 or higher

1. Fresh Clone & Run (< 10 minutes)

Clone the repository and spin up both the FastAPI backend and Vite React development server using a single command:

git clone https://github.com/Stormynubee/Bogieflow.git
cd Bogieflow
python -m pip install -r requirements.txt
npm install
npm run dev:all

Open http://localhost:5173 in your browser. The Vite development proxy maps /api and /ws requests directly to FastAPI running on port 8000.

Alternative command: make dev (requires GNU Make).

2. Manual Dual-Terminal Fallback

If concurrently is not preferred, run the backend and frontend in separate terminals:

Terminal 1 (Backend):

python -m uvicorn server.main:app --reload --port 8000

Terminal 2 (Frontend):

npm run dev

3. Environment Variables

Copy .env.example to .env. Key variables:

• ALLOWED_ORIGINS: Comma-separated CORS origins (empty defaults to localhost dev origins).
• GUIDE_AI_API_KEY: Optional Google Gemini API key to enable plain-language guide chat and ticket explainers.
• VITE_API_BASE / VITE_WS_BASE: Optional URLs for split Vercel + Render deploys (leave empty for Vite proxy / single-origin Docker).
• BOGIE_TRAIN_USE_REAL: When true (default), train on Open-Meteo + CWRU CSVs in server/data/ if present; otherwise synthetic fallback. See docs/DATA.md.
• BOGIE_TRAINING_DATA_DIR: Optional override for training CSV directory.

Fetch real training data locally:

python -m server.data.fetch_datasets
python -m server.agents.train_risk_model

---

One-Click Deployment

Bogieflow is configured for single-origin serving, compiling the React dashboard into static assets served directly by FastAPI. This allows you to host the entire application (REST API, WebSocket, and UI) on a single port.

Docker Deploy

Build and run the multi-stage Docker container:

docker build -t bogie-flow .
docker run --rm -p 8000:8000 -e PORT=8000 -e ALLOWED_ORIGINS=https://your-service.onrender.com bogie-flow

Deployment configurations are included in:

• render.yaml (Render deployment settings)
• railway.toml (Railway deployment settings)
• vercel.json (Vercel SPA routing settings)

Vercel Deployment (Frontend UI)

The Vite React frontend is deployed on Vercel as a static SPA with client-side demo simulation when no backend is reachable.

• Production URL: https://bogieflow.vercel.app (alias: faraway-2026-japan.vercel.app)
• Live backend: https://bogie-flow.onrender.com (FastAPI + WebSocket) — see docs/DEPLOY-LIVE.md. After pushing to main, Manual Deploy on Render if /api/model/card returns 404.
• Demo mode: Without a hosted FastAPI backend, the dashboard runs a local telemetry simulation (header shows Demo, field sensors show Simulated ingest).
• Full stack: Set VITE_API_BASE=https://bogie-flow.onrender.com in Vercel project settings, then redeploy.

---

Tech Stack

• Backend Framework: FastAPI (Python 3.11)
• Frontend Library: React 19 / Vite
• Machine Learning: Scikit-Learn 1.8.0 / NumPy / Joblib
• Real-time Pipeline: Python WebSockets
• Styling & UI: Vanilla CSS / Framer Motion / Material Icons
• Browser Testing & Shots: Playwright

---

Project Structure

Faraway2026Japan/          # repo also published as github.com/Stormynubee/Bogieflow
├── .github/
│   ├── dependabot.yml
│   ├── issue_template/
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   ├── workflows/
│   │   ├── ai-review.yml
│   │   ├── ci.yml
│   │   ├── issue-triage.yml
│   │   ├── publish-package.yml
│   │   └── stale.yml
│   ├── CODEOWNERS
│   └── pull_request_template.md
├── assets/
│   ├── screenshots/
│   │   ├── overview.png
│   │   ├── analysis.png
│   │   ├── maintenance.png
│   │   ├── climate.png
│   │   ├── impact.png
│   │   └── explain.png
│   ├── bogie_flow_banner.png
│   ├── social-preview.png
│   ├── demo.mp4
│   └── demo_fallback.mp4
├── docs/
│   ├── README.md
│   ├── PROJECT.md
│   ├── SENSORS.md
│   ├── physics.md
│   ├── ws-schema.md
│   ├── SUBMISSION.md
│   ├── DESIGN.md
│   ├── DEMO_SCRIPT.md
│   ├── DATA.md
│   ├── DEPLOY-LIVE.md
│   └── plans/
│       ├── 2026-06-14-bogie-flow-rebrand.md
│       ├── 2026-06-14-corridor-scrub-dashboard.md
│       └── 2026-06-14-overview-calm-instrument.md
├── hardware/
│   └── README.md
├── scripts/
│   ├── capture-screenshots.mjs
│   ├── generate_banner.mjs
│   └── generate_social_preview.mjs
├── server/
│   ├── agents/
│   │   ├── dataset.py
│   │   ├── forecast.py
│   │   ├── hydrology.py
│   │   ├── planner.py
│   │   ├── risk_model.joblib
│   │   ├── risk_model.meta.json
│   │   ├── risk_model.py
│   │   ├── train_risk_model.py
│   │   └── vibration.py
│   ├── data/
│   │   └── fetch_datasets.py
│   ├── env.py
│   ├── explain.py
│   ├── guide.py
│   ├── impact.py
│   ├── main.py
│   ├── models.py
│   ├── simulation.py
│   ├── static_routes.py
│   └── weather.py
├── src/
│   ├── components/
│   │   ├── charts/
│   │   │   ├── MoistureSparkline.jsx
│   │   │   └── RainfallBars.jsx
│   │   ├── guide/
│   │   │   ├── GuideChatPanel.jsx
│   │   │   ├── GuideCoach.jsx
│   │   │   ├── GuideLauncher.jsx
│   │   │   └── GuideSpotlight.jsx
│   │   ├── ink/
│   │   │   ├── CornerBrackets.jsx
│   │   │   ├── Eyebrow.jsx
│   │   │   ├── GrainOverlay.jsx
│   │   │   ├── Hairline.jsx
│   │   │   ├── KineticNumber.jsx
│   │   │   ├── PageHeader.jsx
│   │   │   └── StatusTicker.jsx
│   │   ├── views/
│   │   │   ├── AnalysisView.jsx
│   │   │   ├── ClimateView.jsx
│   │   │   ├── MaintenanceView.jsx
│   │   │   └── OverviewView.jsx
│   │   ├── AnomalyStream.jsx
│   │   ├── BogieAnalysisPanel.jsx
│   │   ├── BootContinueButton.jsx
│   │   ├── BootFlowMark.jsx
│   │   ├── BootLoader.jsx
│   │   ├── BootTerminal.jsx
│   │   ├── ClimatePanel.jsx
│   │   ├── CorridorBriefing.jsx
│   │   ├── CorridorCommandDock.jsx
│   │   ├── CorridorScrubRail.jsx
│   │   ├── CorridorScrubViewer.jsx
│   │   ├── DashboardSkeleton.jsx
│   │   ├── ForecastPanel.jsx
│   │   ├── HeroStatusLine.jsx
│   │   ├── ImpactPanel.jsx
│   │   ├── ModelCardPanel.jsx
│   │   ├── LogEntry.jsx
│   │   ├── MetricBar.jsx
│   │   ├── OverviewOpsStrip.jsx
│   │   ├── PanelHeader.jsx
│   │   ├── ReconnectBanner.jsx
│   │   ├── RiskGaugeDial.jsx
│   │   ├── ScenarioMenu.jsx
│   │   ├── SegmentHudGrid.jsx
│   │   ├── SensorStackPanel.jsx
│   │   ├── Sidebar.jsx
│   │   ├── StationMapModal.jsx
│   │   ├── TicketExplain.jsx
│   │   ├── ToastStack.jsx
│   │   ├── TopBar.jsx
│   │   ├── TrackMap.jsx
│   │   └── WeatherToggle.jsx
│   ├── content/
│   │   ├── guideKnowledge.js
│   │   ├── guideSteps.js
│   │   └── uiCopy.js
│   ├── data/
│   │   └── corridorFrames.js
│   ├── hooks/
│   │   ├── useGuideCoach.js
│   │   └── useWebSocket.js
│   ├── lib/
│   │   ├── api.js
│   │   ├── chartData.js
│   │   ├── config.js
│   │   ├── corridorScrub.js
│   │   ├── corridorStatus.js
│   │   ├── demoScenarios.js
│   │   ├── guideChat.js
│   │   ├── guideLauncher.js
│   │   ├── impactDisplay.js
│   │   ├── modelCardDisplay.js
│   │   ├── overviewSplitLayout.js
│   │   ├── riskGaugeGeometry.js
│   │   ├── scrubRail.js
│   │   ├── segmentUtils.js
│   │   ├── sensorStack.js
│   │   ├── wsReconnect.js
│   │   └── wsReducer.js
│   ├── styles/
│   │   ├── ink-motifs.css
│   │   ├── ink-overrides.css
│   │   ├── ink-reskin.css
│   │   ├── ink-tokens.css
│   │   └── overview-split.css
│   ├── App.jsx
│   └── index.css
├── tests/
│   ├── conftest.py
│   ├── test_api_inject.py
│   ├── test_cors_health.py
│   ├── test_explain.py
│   ├── test_forecast.py
│   ├── test_guide.py
│   ├── test_impact.py
│   ├── test_inject_anomaly.py
│   ├── test_model_cached.py
│   ├── test_planner.py
│   ├── test_readme_badges.py
│   ├── test_recovery.py
│   ├── test_model_card.py
│   ├── test_live_stack_smoke.py
│   ├── test_risk_model.py
│   ├── test_sim_guard.py
│   ├── test_static_serving.py
│   ├── test_ticket_dedup.py
│   └── test_vibration.py
├── package.json
├── pyproject.toml
└── requirements.txt

---

Verification & Testing

Verify both test suites locally by running the following commands:

Python Pytest Suite

python -m pytest tests/ -v

(Verifies CORS middleware, static single-origin routing, ML model card API, model caching, ticket de-duplication, Open-Meteo cache fallbacks, and forecast projections. 79 tests collected.)

Frontend Vitest Suite

npm run test

(Verifies WebSocket reducer state, model card display helpers, config path derivations, corridor scrub, guide launcher, sensor stack state, Overview split layout calculation, risk gauge geometries, and custom kinetic counters. 133 tests passing.)

Live stack smoke (production)

node scripts/verify-live-stack.mjs
node scripts/e2e-live-smoke.mjs https://bogieflow.vercel.app
LIVE_BACKEND_URL=https://bogie-flow.onrender.com python -m pytest tests/test_live_stack_smoke.py -v

---

Judging Criteria Alignment

Criteria	Evidence / Implementation in Bogieflow
Innovation	Fuses climate meteorology predictions with high-frequency rolling bogie acceleration data. Employs a Gradient Boosting classification model to determine risk levels dynamically rather than relying on static thresholds.
Technical Depth	Implements multi-agent pipelines (Hydrology, Vibration, Planner) on an async FastAPI event loop. Features non-blocking Gemini AI integration, real-time Open-Meteo API caching, and automated ticket explanations.
Real-World Impact	Explains maintenance tickets via Shapley-style model feature importances, translating ML inputs into actionable engineering indicators. Calculates avoided derailment risks and USD savings to justify maintenance operations.
Execution	Built with a high-fidelity "ink & paper" monochrome theme using Fraunces and Hanken Grotesk typography, fine hairline blueprint grids, and tactile feedback. Single-origin production setup allows serving REST, WebSockets, and Vite UI from one Docker container.
Scalability	Designed with standard hardware interface targets (ESP32-S3 and MPU6050 accelerometer). Back-end agents are decoupled from presentation, making them ready to port directly to edge gatekeepers. See docs/SENSORS.md for sensor details.

---

Roadmap

• Decouple Hydrology & Vibration simulation rules.
• Implement Gradient Boosting Classifier for risk prioritization.
• Ground ML training in Open-Meteo + CWRU data with model card API (v1.7.0).
• Integrate Open-Meteo API for live regional weather.
• Develop Avoided-Failure Quantified Impact estimation.
• Create 30-minute Risk Forecasting (Time-to-Critical) agent.
• Port Vibration evaluation code to ESP32-S3 edge node.
• Connect physical MPU6050 accelerometers for active field trials.
• Add multi-train corridor tracking support.

---

Honesty Box

• Telemetry & Simulation: Sensor values (acceleration, rain) are simulated in real-time unless a live ingest path is connected. Acceleration values are generated via normal distribution models (random.gauss) incorporating randomized spikes on wet segments.
• ML Model: Training prefers real Open-Meteo monsoon hydrology + CWRU-class bearing vibration CSVs when server/data/ is populated (python -m server.data.fetch_datasets). The Docker/Render build attempts this fetch automatically. Without CSVs, a Simulated 503-sample physics-derived frame is used — see the Overview Risk model card badge and docs/DATA.md.
• Model metrics: CV accuracy / F1 on the training frame are not field-validated derailment prediction — they document classifier fit only.
• Weather Data: The live weather toggle fetches real precipitation data from the Open-Meteo API. If offline or rate-limited, the system falls back to simulated parameters with a visible notification.
• Hardware Integration: The current codebase does not interface directly with physical sensors. The ESP32-S3 edge node architecture and schematic design are included for documentation purposes only.

---

Built with 💻 for the FAR AWAY 2026 Hackathon under the Railways theme.
Licensed under the MIT License.