This **README** is designed to give your **SIH 2025** judges and collaborators a professional overview of the **IntelliRail** project. It highlights the technical complexity of your "Digital Twin" approach while providing clear setup instructions.

---

# 🚆 IntelliRail: AI-Powered Precise Train Traffic Control

**IntelliRail** is a high-performance "Digital Twin" system designed to maximize railway section throughput. Built for the **Smart India Hackathon (SIH) 2025 (Problem Statement #25022)**, it replaces static, rigid scheduling with a dynamic, AI-driven controller that safely compresses headway gaps to increase track capacity.

---

## 🚀 Key Features

* **AI-Optimized Scheduling:** Uses **Google OR-Tools** to calculate mathematically optimal entry gaps (headway) between trains.
* **Predictive Risk Analysis:** A **PyTorch GRU model** analyzes real-time telemetry to predict congestion risks before they cause delays.
* **Real-Time Visualization:** A live **React dashboard** powered by **WebSockets** showing a side-by-side comparison of AI-Optimized vs. Standard tracks.
* **Historical Benchmarking:** Integrated **PostgreSQL** database to track and graph long-term efficiency trends using **Chart.js**.
* **Physics-Based Simulation:** Built on **SimPy** to ensure all movements obey realistic acceleration, braking, and safety interlocking rules.

---

## 🛠️ Tech Stack

### **Backend (Python)**
| Component | Technology | Role |
| :--- | :--- | :--- |
| **API Framework** | **FastAPI** | Orchestration & High-speed WebSocket streaming. |
| **Optimization** | **Google OR-Tools** | Constraint Programming for gap optimization. |
| **Simulation** | **SimPy** | Discrete Event Simulation for train physics. |
| **AI/ML Engine** | **PyTorch (GRU)** | Time-series prediction for congestion risk. |
| **Database** | **PostgreSQL** | Storage for telemetry and run history. |

### **Frontend (React)**
| Component | Technology | Role |
| :--- | :--- | :--- |
| **UI Framework** | **React.js** | Modular, state-driven dashboard. |
| **Visuals** | **Chart.js / CSS3** | Real-time graphs and track animations. |
| **Communication** | **WebSockets** | Low-latency bi-directional data flow. |

---

## 📁 Project Structure

```bash
IntelliRail/
├── backend/
│   ├── main.py            # FastAPI entry point & WebSocket logic
│   ├── simulation.py      # SimPy train & track physics logic
│   ├── optimizer.py       # Google OR-Tools scheduling logic
│   ├── ai_model.py        # PyTorch GRU architecture & prediction
│   ├── database.py        # PostgreSQL connection & queries
│   └── seed_data.py       # Script to populate historical data
└── frontend/
    ├── src/
    │   ├── App.jsx        # Main dashboard logic & state management
    │   ├── App.css        # Industrial SCADA-themed styling
    │   └── components/    # (Optional) Modular UI components
    └── package.json       # Frontend dependencies
```

---

## ⚙️ Installation & Setup

### **1. Prerequisites**
* Python 3.10+
* Node.js & npm
* PostgreSQL (Running on port 5432)

### **2. Backend Setup**
```bash
cd backend
pip install fastapi uvicorn simpy ortools torch psycopg2-binary
# Ensure your PostgreSQL database 'intellirail' is created
python seed_data.py  # Seed the database with initial trends
uvicorn main:app --reload
```

### **3. Frontend Setup**
```bash
cd frontend
npm install
npm run dev
```

---

## 🧠 How It Works: The Logic Flow

1.  **Input:** The user initiates a simulation from the dashboard.
2.  **Optimize:** `optimizer.py` calculates the tightest safe schedule for the requested trains.
3.  **Simulate:** `simulation.py` launches the trains. If a train slows down, the physics engine updates the telemetry.
4.  **Predict:** `ai_model.py` receives live telemetry via the backend. If it detects a "congestion signature," the **Risk Score** spikes.
5.  **Visualize:** Data is pushed through a **WebSocket** to the React UI, updating the train positions and graphs in real-time.

---

## 🔮 Future Roadmap

* **Multi-Priority Routing:** Dynamic prioritization for Express vs. Freight trains.
* **Environmental Awareness:** Adjusting safety buffers based on real-time weather data (rain/fog).
* **Decentralized Control:** Transitioning to an autonomous multi-agent system for individual train-to-train communication.

---