Trackly — No cap, the smartest way to track trains 🚆

A full-stack Indian Railways intelligence platform with live GPS tracking, AI journey assistant (RailMind), delay predictions, weather forecasting along route, elevation profiling, and POI discovery. Built for modern India, works on every device.

Output Screen :-

What is Trackly

Trackly is not just another train tracking app. While apps like NTES, RailYatri, and ixigo only show you where the train is, Trackly tells you everything:

Live position on an interactive map with smooth interpolation
Why the train is delayed — weather, congestion, or upstream trains
Whether you'll make your connecting train
What you're passing through — rivers, mountains, monuments, cities
AI answers to any question about your journey — no hallucinations, no guessing

The core differentiator is RailMind — a RAG-powered AI assistant strictly scoped to Indian Railways data, always cites its source, and honestly says "I don't know" rather than making things up.

Features

Live Train Tracking

Real-time position from RailRadar API with smooth interpolation between pings
Animated train marker on interactive MapLibre GL map
Full route visualization — orange for covered, grey for remaining
Station dots with popups showing arrival/departure times
Speed indicator (km/h), delay status, last update timestamp
Auto-refresh every 30 seconds

Smart Search

Search any train by number (e.g. 12951) or name (e.g. Rajdhani)
Instant results with live delay badge
Recent searches saved locally
Favourite trains for quick access

Journey Analytics

Journey completion percentage with distance covered and remaining
Delay trend analysis (improving / stable / worsening)
Elevation profile along the entire route
Station arrival history (actual vs scheduled)

Weather Intelligence

Current weather at every station along the route
Rain probability and fog alerts that affect delays
Temperature range across the full journey
Route-wide weather delay risk score (High / Medium / Low)

Route Intelligence

Points of interest along the route via OpenStreetMap Overpass API
Rivers, mountains, heritage sites, tourist attractions near each station
Elevation profile chart powered by OpenTopoData

RailMind AI (Strict RAG)

Powered by Groq Llama 3.3-70b — fastest free LLM available
3-layer hallucination prevention system
Confidence scoring on every response (HIGH / MEDIUM / LOW)
Hard scope boundary — refuses all non-railway questions
Suggested follow-up questions after every answer
Journey-aware — knows your current train's live status

Tech Stack

Frontend

Technology	Version	Purpose
Next.js	14.2.5	React framework with App Router
TypeScript	5.x	Type safety across the codebase
TailwindCSS	3.4	Utility-first styling
MapLibre GL JS	4.5.0	Interactive map rendering
Zustand	4.5	Lightweight global state management
Recharts	2.12	Elevation profile chart
Lucide React	0.400	Icon library (no emojis)
Framer Motion	11.3	Page transitions and animations
Axios	1.7	HTTP client with interceptors

Backend

Technology	Version	Purpose
FastAPI	0.111	High-performance Python web framework
Uvicorn	0.30	ASGI server with WebSocket support
Groq SDK	0.9	LLM API client
LangChain	0.2.6	RAG pipeline orchestration
ChromaDB	0.5.3	Local vector database
sentence-transformers	3.0.1	Free local text embeddings
httpx	0.27	Async HTTP client
Pydantic	2.7	Request/response data validation
BeautifulSoup4	4.12	HTML parsing for NTES fallback
APScheduler	3.10	Background scheduling
WebSockets	12.0	Real-time live position updates

AI / ML Models

Model	Provider	Temperature	Use Case
`llama-3.1-8b-instant`	Groq (free)	0.0	Intent classifier — binary, fast
`llama-3.1-8b-instant`	Groq (free)	0.0	Entity extraction — JSON output
`llama-3.3-70b-versatile`	Groq (free)	0.1	Main RailMind responses
`mixtral-8x7b-32768`	Groq (free)	0.1	Long-context route analysis
`all-MiniLM-L6-v2`	HuggingFace (local)	—	Text embeddings for ChromaDB

System Architecture

╔══════════════════════════════════════════════════════════════════╗
║                        USER BROWSER                              ║
║                                                                  ║
║  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐    ║
║  │  Next.js 14  │  │ MapLibre GL  │  │   RailMind Chat UI   │    ║
║  │  App Router  │  │ Interactive  │  │  (React Component)   │    ║
║  │  5 Tab Pages │  │    Map       │  │  Confidence Badges   │    ║
║  └──────┬───────┘  └──────┬───────┘  └──────────┬───────────┘    ║
║         └─────────────────┴──────────────────────┘               ║
║                           │ HTTP / WebSocket / REST              ║
╚═══════════════════════════╪══════════════════════════════════════╝
                            │
╔═══════════════════════════╪══════════════════════════════════════╗
║                    FASTAPI BACKEND                               ║
║                            │                                     ║
║   ┌────────┬───────┬───────┴─┬────────┬─────────┬───────────┐    ║
║   │/search │/trains│ /live   │  /ai   │/weather │/elevation │    ║
║   │ Router │ Router│ Router  │ Router │ Router  │ /poi      │    ║
║   └───┬────┴───┬───┴────┬────┴────┬───┴────┬────┴───────────┘    ║
║       │        │        │         │        │                     ║
║   ┌───▼────────▼────────▼──┐  ┌───▼──────┐ ┌──▼──────────────┐   ║
║   │    TrainService        │  │ RailMind │ │  WeatherService  │  ║
║   │                        │  │   RAG    │ │  + GeoService    │  ║
║   │ • RailRadar API        │  │ Pipeline │ │                  │  ║
║   │ • NTES fallback        │  │          │ │ Open-Meteo       │  ║
║   │ • Position interpolate │  │ ChromaDB │ │ OpenTopoData     │  ║
║   │ • WebSocket broadcast  │  │ + Groq   │ │ Overpass API     │  ║
║   └────────────────────────┘  └──────────┘ └──────────────────┘  ║
╚══════════════════════════════════════════════════════════════════╝
                            │
╔═══════════════════════════╪══════════════════════════════════════╗
║                 EXTERNAL APIs (All Free Tier)                    ║
║                                                                  ║
║  ┌─────────────┐ ┌──────────┐ ┌────────────┐ ┌───────────────┐   ║
║  │  RailRadar  │ │ MapTiler │ │ Open-Meteo │ │ OpenTopoData  │   ║
║  │ 50 req/day  │ │ 100k/mo  │ │ unlimited  │ │ 1000 req/day  │   ║
║  └─────────────┘ └──────────┘ └────────────┘ └───────────────┘   ║
║                                                                  ║
║  ┌─────────────┐ ┌──────────┐ ┌────────────────────────────────┐ ║
║  │  Overpass   │ │Nominatim │ │         Groq API               │ ║
║  │  OSM POI    │ │Geocoding │ │  llama-3.3-70b (free tier)     │ ║
║  │  unlimited  │ │ free     │ │  500k tokens/day free          │ ║
║  └─────────────┘ └──────────┘ └────────────────────────────────┘ ║
╚══════════════════════════════════════════════════════════════════╝

Data Flow

Search Flow

User types "12951" or "Rajdhani"
            │
            ▼ debounce 300ms
GET /api/search/?q=12951
            │
            ▼
TrainService.search_trains()
            │
            ├──► RailRadar /v1/lookup/trains?q=12951
            │         │
            │    200 OK → parse {number, name, source, dest}
            │    429    → show rate limit message
            │    404    → empty results
            │
            ▼
Return SearchResult[] with delay badge
            │
            ▼
Render dropdown — click to go to /train/12951

Live Tracking Flow

User opens /train/12951
            │
            ▼ Parallel fetch
   ┌─────────────────────┐
   │ GET /api/trains/id  │  GET /api/live/id
   │ Full schedule       │  Current position
   │ All stations        │  Delay in minutes
   └─────────────────────┘  Speed (km/h)
            │
            ▼
MapLibre map.on('load'):
   ├── addSource('full')   → grey route line
   ├── addSource('done')   → orange completed line
   ├── forEach station     → dot marker + popup
   └── trainMarker         → orange circle icon
            │
            ▼
fitBounds() → zoom to show entire route
            │
            ▼
Poll every 30s:
   GET /api/live/12951
            │
   ├── trainMarker.setLngLat([lng, lat])
   ├── source('done').setData(completedCoords)
   └── Update stats grid

RailMind AI Flow

User: "Will my train reach Mumbai on time?"
            │
   ┌────────▼────────┐
   │ INTENT CHECK    │  llama-3.1-8b / temp=0.0
   │ Railway? YES/NO │  ~180ms
   └────────┬────────┘
            │ YES only
   ┌────────▼────────┐
   │ EXTRACT ENTITY  │  llama-3.1-8b / temp=0.0
   │ train=12951     │  JSON output
   │ type=delay      │
   └────────┬────────┘
            │
   ┌────────▼────────┐
   │ CHROMADB RAG    │  Local vector search
   │ Find relevant   │  Top 4 chunks returned
   │ schedule data   │
   └────────┬────────┘
            │
   ┌────────▼────────┐
   │ INJECT LIVE     │  From RailRadar API
   │ delay=23 mins   │  Real-time context
   │ station=Surat   │
   └────────┬────────┘
            │
   ┌────────▼────────────────────────────────────┐
   │ GROUNDED RESPONSE  llama-3.3-70b / temp=0.1 │
   │                                              │
   │ System prompt enforces:                      │
   │  • Only answer from provided context         │
   │  • Never invent train numbers or timings     │
   │  • Add [CONFIDENCE: HIGH/MEDIUM/LOW]         │
   │  • Add [SOURCE: Live API / Schedule DB]      │
   │  • Max 180 words, suggest 2 follow-ups       │
   └────────┬─────────────────────────────────────┘
            │
            ▼
Response with badge:
  🟢 HIGH — from live API
  🟡 MEDIUM — from schedule DB
  🔴 LOW — estimated/inferred

AI Pipeline — RailMind

How Hallucination is Prevented

Query enters
    │
    ▼
[Gate 1] Is it about railways?
    NO  ──────────────────────► "I only answer railway questions"
    │
    YES
    ▼
[Gate 2] ChromaDB retrieval
    Empty ────────────────────► "No data — check NTES or IRCTC"
    │
    Has context
    ▼
[Gate 3] LLM with constraints
    Temperature 0.1 (near-zero creativity)
    "ONLY use the context provided below"
    "NEVER invent train numbers or timings"
    │
    ▼
[Gate 4] Confidence tagging
    Live API data     → HIGH confidence
    Schedule database → MEDIUM confidence
    Inferred/estimated → LOW confidence
    │
    ▼
Response shown with confidence badge + source

Project Structure

trackly/
│
├── README.md                           ← This file
├── start.sh                            ← One-command startup script
│
├── backend/                            ← Python FastAPI server
│   ├── main.py                         ← Entry point, CORS, lifespan hooks
│   ├── requirements.txt                ← All Python dependencies
│   ├── .env.example                    ← Template (copy to .env)
│   │
│   ├── routers/                        ← HTTP route handlers
│   │   ├── search.py                   ← GET /api/search/?q=
│   │   ├── trains.py                   ← GET /api/trains/{id}
│   │   ├── live.py                     ← GET + WS /api/live/{id}
│   │   ├── ai.py                       ← POST /api/ai/chat
│   │   ├── weather.py                  ← GET /api/weather/{id}
│   │   ├── elevation.py                ← GET /api/elevation/{id}
│   │   └── poi.py                      ← GET /api/poi/{id}
│   │
│   ├── services/                       ← Core business logic
│   │   ├── train_service.py            ← RailRadar + NTES integration
│   │   ├── rag_pipeline.py             ← Groq + ChromaDB RAG engine
│   │   ├── weather_service.py          ← Open-Meteo integration
│   │   └── geo_service.py              ← Elevation + POI services
│   │
│   └── models/
│       └── train.py                    ← Pydantic request/response models
│
└── frontend/                           ← Next.js React application
    ├── next.config.js                  ← Next.js + env var config
    ├── tailwind.config.ts              ← Brand colors, design tokens
    ├── package.json                    ← Node dependencies
    ├── tsconfig.json                   ← TypeScript config
    │
    └── src/
        ├── app/                        ← Next.js App Router
        │   ├── layout.tsx              ← Root layout + Navbar
        │   ├── page.tsx                ← Homepage — hero + search
        │   ├── globals.css             ← Global styles
        │   ├── search/page.tsx         ← Full-page search
        │   ├── favourites/page.tsx     ← Saved trains list
        │   ├── settings/page.tsx       ← API keys + about
        │   └── train/[id]/page.tsx     ← Train detail (5 tabs)
        │
        ├── components/
        │   ├── layout/
        │   │   └── Navbar.tsx          ← Top nav with route awareness
        │   ├── tracking/
        │   │   ├── LiveTrackingTab.tsx ← MapLibre map + live data
        │   │   ├── StationTimeline.tsx ← All stops with status
        │   │   └── WeatherTab.tsx      ← Per-station weather cards
        │   ├── analytics/
        │   │   └── AnalyticsTab.tsx    ← Elevation chart + POI list
        │   └── ai/
        │       └── RailMindChat.tsx    ← Chat UI with confidence badges
        │
        └── lib/
            ├── api.ts                  ← Typed Axios client + interfaces
            └── store.ts                ← Zustand — recents, favourites, state

API Reference

Base URL: http://localhost:8000/api

Interactive docs at http://localhost:8000/docs

Method	Endpoint	Description
`GET`	`/search/?q={query}`	Search trains by number or name
`GET`	`/trains/{id}`	Full schedule + all stations
`GET`	`/trains/{id}/status`	Current running status
`GET`	`/live/{id}`	Live position + delay (HTTP)
`WS`	`/live/ws/{id}`	WebSocket stream (30s interval)
`POST`	`/ai/chat`	RailMind AI conversation
`GET`	`/ai/suggestions/{id}`	Proactive AI journey alerts
`GET`	`/weather/{id}`	Weather for all route stations
`GET`	`/elevation/{id}`	Elevation profile data
`GET`	`/poi/{id}`	Points of interest along route

Free APIs Used

API	Provides	Free Limit	Key?
RailRadar	Live tracking, schedules, search	50 req/day	Yes — railradar.in/developers
Groq	LLM inference (Llama 3.3)	500k tokens/day	Yes — console.groq.com
MapTiler	Vector map tiles	100k tiles/month	Yes — maptiler.com
Open-Meteo	Weather forecast	Unlimited	No
OpenTopoData	Elevation (SRTM)	1000 req/day	No
Overpass API	OSM points of interest	Unlimited	No
Nominatim	Reverse geocoding	Fair use	No

Total cost for full MVP: ₹0 / month

Quick Start

Prerequisites

Node.js 18+
Python 3.11+
Git

1. Clone

git clone https://github.com/yourusername/trackly.git
cd trackly

2. Get Free API Keys

RailRadar  → https://railradar.in/developers  (2 min)
Groq       → https://console.groq.com         (2 min)
MapTiler   → https://maptiler.com             (2 min)

3. Backend

cd backend
cp .env.example .env
# Edit .env → add RAILRADAR_API_KEY and GROQ_API_KEY

python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt
python main.py
# ✅ http://localhost:8000
# 📖 http://localhost:8000/docs

4. Frontend

cd frontend
cp .env.local.example .env.local
# Edit .env.local → add NEXT_PUBLIC_MAPTILER_KEY

npm install
npm run dev
# ✅ http://localhost:3000

Environment Variables

`backend/.env`

RAILRADAR_API_KEY=rr_live_xxxxxxxxxxxxxxxx    # required
GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxx      # required
REDIS_URL=redis://localhost:6379               # optional
APP_ENV=development
CORS_ORIGINS=http://localhost:3000

`frontend/.env.local`

NEXT_PUBLIC_MAPTILER_KEY=your_key_here         # required
NEXT_PUBLIC_API_URL=http://localhost:8000       # change in production

Deployment

Backend on Render.com

1. Push repo to GitHub
2. render.com → New Web Service → Connect repo
3. Build command:   pip install -r requirements.txt
4. Start command:   uvicorn main:app --host 0.0.0.0 --port $PORT
5. Add env vars in Render dashboard

Frontend on Vercel

1. vercel.com → Import project → Connect GitHub repo
2. Framework: Next.js (auto-detected)
3. Environment variables:
   NEXT_PUBLIC_API_URL        = https://your-app.onrender.com
   NEXT_PUBLIC_MAPTILER_KEY   = your_maptiler_key
4. Deploy

Built by

Ankit ♡

"No cap, Indian Railways just got an upgrade."

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
backend		backend
frontend		frontend
.gitignore		.gitignore
README.md		README.md
start.sh		start.sh

Folders and files

Latest commit

History

Repository files navigation