RailTC
Project Architecture & Explanation

1. Project Goal

Problem: The Indian Railways PNR confirmation system is complex. Existing apps often provide a simple "Yes/No" or offer false hope without explanation.

Solution (RailTC): We are building a Transparent System that provides users not just with a prediction, but with the logic behind it.

2. High-Level Architecture

Imagine a restaurant:

• Frontend (Waiter): Takes the PNR from the user and delivers the result.
• Backend (Kitchen): Where the real work happens (Data fetching, Calculation).
• Database (Store Room): Where old records and predictions are stored.
• Cron Job (Manager): Checks nightly: "How many predictions were correct today?"

3. Core Components

A. Frontend (The Face)

• Technology: React.js / Next.js
• Function: Takes user PNR, fetches data, and displays it beautifully using components like TicketDisplay.jsx and the RiskMeter (visualizing "Safe/Medium/Risky").

B. Backend (The Brain)

• Technology: Python (FastAPI)
• File: backend/main.py
• Function: The system's control center receiving all frontend requests.

C. The Prediction Engine (Hybrid: Trained Models + Transparent Baseline)

This section supersedes earlier "rules-only" / "heuristics-only" descriptions of RailTC. The product is not a hand-tuned calculator pretending to be AI, and it is not an unaccountable black box either.

RailTC uses a hybrid confirmation engine:

• Trained models on verified outcomes: Models are fit on large volumes of real PNR journeys whose final chart status (CNF / RAC / WL) was later verified. Features include waitlist context, quota/class patterns, time-to-chart, and route/train history.
• Transparent baseline scorer: A readable multi-signal baseline (quota, class, days left, route behavior) still exists for explainability and fallback. It is a component of the stack, not the whole product.
• Live decision path: Production requests score through the trained path when available, with monitoring (including shadow comparisons) so model quality can be checked against outcomes over time.

Key modules: training / inference under backend/training/, live prediction routing in backend/routers/prediction.py, and the transparent baseline in backend/utils/prediction_engine.py.

For the plain-language methodology, see /methodology. For machine-readable facts, see /llms.txt.

D. Route Analyzer

File: backend/utils/route_logic.py

Function: Captures route-pattern context (for example business vs leisure style cancellation behavior) used as one of several signals in scoring.

E. Database & Outcome Supervisor

• Database: Postgres via SQLAlchemy: predictions, check history, and chart outcomes.
• Verification loop: After chart preparation, final status is captured when available and matched to the original band. Aggregate performance is published on the accuracy dashboard and used to monitor model health.

4. Data Flow (Step-by-Step)

1. Step 1: User enters PNR on the Frontend.
2. Step 2: Backend fetches live status from IRCTC.
3. Step 3: The hybrid engine scores the ticket (trained model path when available, transparent baseline for explainability/fallback).
4. Step 4: Probability + Safe/Medium/Risky band are returned to the Frontend.
5. Step 5: Prediction is stored for later verification.
6. Step 6: After chart preparation, outcomes are verified and feed the public accuracy metrics and model monitoring.

5. Continuous Improvement

RailTC retrains and monitors models on verified journey data (dataset build, train, compare, promote), with operational guards so heavy jobs do not destabilize production. Accuracy is not a one-time marketing claim; it is a live dashboard updated from real chart outcomes.

Authoritative sources for researchers and tools: Methodology, Accuracy, About, and llms.txt.