Workflow blueprint

Kapido system flow, explained as one clear operational story.

This page shows how one analysis request moves from the input form, through prediction and persistence, into analytics, validation, and dashboard visualization.

Back to home Run live analysis

Runtime stages

Backend routes

System modules

Offline training lane

Live request path

The sequence below focuses on what happens during a real dashboard analysis run.

Enter the analysis inputs

The user chooses an hour and types a location in InputForm. The component searches the local location index, resolves coordinates, and stores the last run in localStorage.

No direct API call

findLocationMatches • resolveLocationCoordinates • getLocationCoordinates

Route the request to the dashboard

The home page builds a query string from the submitted hour, location, latitude, and longitude, then navigates to /dashboard.

No direct API call

handleSubmit • useRouter

Request a prediction

DashboardPage calls getPrediction, which sends GET /predict with the chosen hour, location, latitude, and longitude.

GET /predict

getPrediction • predict

Build features and score the models

PredictorService loads the saved model artifact, build_features creates temporal and geographic features, and the demand and supply models score the request.

No direct API call

PredictorService.predict • build_features

Produce the explanation layer

InsightService turns the numeric gap into severity, explanation strings, and recommended actions using the threshold rules and peak-hour logic.

No direct API call

InsightService.generate

Persist the result and refresh analytics

The dashboard posts the prediction snapshot to MongoDB, then loads hourly trends, location trends, and model validation metrics in parallel.

POST /store-predictionGET /analytics/hourly-trendsGET /analytics/location-trendsGET /analytics/model-validation

storePrediction • getHourlyTrends • getLocationTrends • getModelValidation

Render the operational view

PredictionCard, MapView, TrendCharts, and the validation monitor turn the API responses into an analyst-friendly dashboard.

No direct API call

PredictionCard • MapView • BarTrendChart • LineTrendChart

Interactive system map

Explore the full architecture graph. Pan, zoom, and inspect how runtime and offline parts connect.

Input to insight pipeline

FrontendBackendDatabaseAnalyticsOfflineExternal

Drag to pan, scroll to zoom, hover a node for details.

frontend

User input

live

Select an hour, type a location, and adjust the map pin if needed.

frontend/components/InputForm.tsx

Hour slider
Location search
Map pin override

hover detail

Select an hour, type a location, and adjust the map pin if needed.

frontend

Location resolver

live

Normalizes the input and resolves stable coordinates from the local location dictionary.

frontend/lib/location-coordinates.ts

findLocationMatches
resolveLocationCoordinates
getLocationCoordinates

hover detail

Normalizes the input and resolves stable coordinates from the local location dictionary.

frontend

Dashboard router

live

Pushes the request into /dashboard with query parameters.

frontend/app/page.tsx

useRouter
handleSubmit

hover detail

Pushes the request into /dashboard with query parameters.

backend

GET /predict

live

Validates the query and hands the request to PredictorService.

backend/app/routes/prediction.py

hour validation
latitude and longitude bounds
FastAPI dependency injection

hover detail

Validates the query and hands the request to PredictorService.

backend

Feature builder

live

Adds time and location features before the model scores the request.

backend/app/services/preprocess.py

hour_sin
hour_cos
is_peak_hour
location_bucket
geo_cluster

hover detail

Adds time and location features before the model scores the request.

backend

PredictorService

live

Loads model.pkl, aligns the feature columns, and scores demand and supply.

backend/app/services/predictor.py

joblib load
clamp to zero
gap = demand - supply

hover detail

Loads model.pkl, aligns the feature columns, and scores demand and supply.

analytics

InsightService

live

Turns the numeric gap into severity, explanations, and recommendations.

backend/app/services/insights_service.py

gap thresholds
peak hour rules
weekend context
low supply checks

hover detail

Turns the numeric gap into severity, explanations, and recommendations.

frontend

Prediction payload

live

Returns demand, supply, gap, severity, explanations, and recommendations to the dashboard.

frontend/app/dashboard/page.tsx

PredictionResult
PredictionCard

hover detail

Returns demand, supply, gap, severity, explanations, and recommendations to the dashboard.

backend

POST /store-prediction

live

Persists the completed analysis snapshot to MongoDB.

backend/app/routes/prediction.py

Backfills missing explanations
Backfills missing recommendations

hover detail

Persists the completed analysis snapshot to MongoDB.

backend

HistoryService

live

Inserts and reads stored prediction records.

backend/app/services/history_service.py

insert_one
find().sort().limit()

hover detail

Inserts and reads stored prediction records.

database

MongoDB predictions collection

live

Stores prediction history and supports aggregation queries.

backend/app/db/mongo.py

timestamp index
location/hour index
gap indexes

hover detail

Stores prediction history and supports aggregation queries.

analytics

AnalyticsService

live

Builds hourly trends, location trends, and hotspot summaries from stored predictions.

backend/app/services/analytics_service.py

aggregate pipelines
shortage thresholds
time-series retrieval

hover detail

Builds hourly trends, location trends, and hotspot summaries from stored predictions.

analytics

ValidationService

live

Scores the model against data/ride_data.csv and emits MAE, RMSE, and anomaly notes.

backend/app/services/validation_service.py

feature frame rebuild
anomaly detection
dataset sampling

hover detail

Scores the model against data/ride_data.csv and emits MAE, RMSE, and anomaly notes.

frontend

Dashboard views

live

PredictionCard, MapView, TrendCharts, and validation panels render the returned data.

frontend/components/*

Charts
Map overlay
Validation monitor

hover detail

PredictionCard, MapView, TrendCharts, and validation panels render the returned data.

external

OpenStreetMap tiles

live

Leaflet pulls map tiles for the preview map and the result map.

frontend/components/CoordinateMapPreview.tsx

react-leaflet
tile server URL

hover detail

Leaflet pulls map tiles for the preview map and the result map.

offline

generate_ride_data.js

live

Expands ride_data.csv with additional synthetic rows across India and Andhra Pradesh.

data/generate_ride_data.js

Andhra Pradesh districts
Chittoor areas
10,000 generated rows

hover detail

Expands ride_data.csv with additional synthetic rows across India and Andhra Pradesh.

offline

train_model.py

live

Builds the feature matrix, trains the demand and supply regressors, and saves model.pkl.

models/train_model.py

RandomForestRegressor
feature_columns
joblib dump

hover detail

Builds the feature matrix, trains the demand and supply regressors, and saves model.pkl.

offline

models/model.pkl

live

Serialized artifact loaded by PredictorService at runtime.

models/model.pkl

demand_model
supply_model
feature_columns

hover detail

Serialized artifact loaded by PredictorService at runtime.

Main runtime

InputForm -> /dashboard -> /predict -> prediction output

Persistence and analytics

storePrediction -> MongoDB -> trends and validation

Offline model lifecycle

generate_ride_data.js -> train_model.py -> model.pkl

External services

MongoDB Atlas and OpenStreetMap tiles

API contracts

Endpoints currently available in the FastAPI backend and their usage in the live dashboard.

GET /predict

used in dashboard

Validates hour, location, and optional coordinates, then returns demand, supply, gap, severity, explanations, and recommendations.

POST /store-prediction

used in dashboard

Writes the prediction snapshot to MongoDB and backfills explanations and recommendations if they are missing.

GET /history

used in dashboard

Returns stored prediction records sorted by newest first.

GET /analytics/hourly-trends

used in dashboard

Aggregates stored predictions into hourly averages, shortage rates, and peak shortage hours.

GET /analytics/location-trends

used in dashboard

Groups stored predictions by location and returns hotspots plus severity labels.

GET /analytics/day-of-week

used in dashboard

Aggregates mismatch metrics by day index (0-6) and identifies peak shortage days.

GET /analytics/gap-distribution

used in dashboard

Returns percentile and bucket distribution of demand-supply gaps.

GET /analytics/time-series

used in dashboard

Returns time-ordered prediction history for charting.

GET /analytics/model-validation

used in dashboard

Evaluates the current model artifact against data/ride_data.csv and returns MAE, RMSE, and anomaly notes.

GET /health

support

Returns the API health status.

Module ownership

Where each responsibility lives in the codebase, with a clear runtime vs offline split.

Frontend runtime

Used by the live UI

Home, dashboard, form, charts, map preview, prediction card, and the typed API wrapper that orchestrates the user flow.

frontend/app/page.tsx

frontend/app/dashboard/page.tsx

frontend/components/InputForm.tsx

frontend/components/CoordinateMapPreview.tsx

frontend/components/PredictionCard.tsx

frontend/components/TrendCharts.tsx

Backend runtime

Active API layer

FastAPI routes, predictor service, feature builder, insight rules, history storage, analytics aggregation, and validation logic.

backend/app/main.py

backend/app/routes/prediction.py

backend/app/services/predictor.py

backend/app/services/preprocess.py

backend/app/services/insights_service.py

backend/app/services/history_service.py

Offline model lifecycle

Manual maintenance flow

The data generator expands ride_data.csv and the training script produces the model.pkl artifact consumed by PredictorService.

data/generate_ride_data.js

models/train_model.py

data/ride_data.csv

models/model.pkl

External services

Runtime dependencies

MongoDB Atlas stores prediction history, and Leaflet renders OpenStreetMap tiles for the preview map and result map.

backend/app/db/mongo.py

frontend/components/CoordinateMapPreview.tsx

frontend/components/MapView.tsx