Advanced Traffic Counting & Classification Platform

Project Overview

This is an enterprise-grade, multi-tenant Software-as-a-Service platform that automates the counting and classification of road traffic from recorded video footage. Traditional traffic surveys rely on manual counting — people stationed at roadside points with tally counters, or analysts painstakingly scrubbing through hours of video frame by frame. Both approaches are slow, expensive, prone to human fatigue, and struggle to deliver the level of detail modern transportation planning demands.

The platform replaces that workflow with an end-to-end digital pipeline: clients upload recorded video, computer-vision models do the heavy lifting, and structured, auditable traffic data is produced in hours rather than weeks. From a business standpoint, it compresses the turnaround time on traffic studies from days to minutes of operator time per video, removes the inconsistency of human counters, and delivers classification granularity that would be economically impossible to capture manually. It is purpose-built for the operational realities of transportation consultancies, civil engineering firms, toll authorities, and infrastructure planning agencies — organisations that routinely need defensible vehicle-class and direction-wise counts at scale.

Key Features & Functionality

At the heart of the platform is a guided project workflow. A user creates a project, uploads one or more videos against it, configures the analysis, and receives a set of deliverable reports. Around that core flow, the product provides a full suite of capabilities.

Project and video management ensures every uploaded video lives within a defined study with associated recording metadata — dates, times, site notes, and computed video properties such as duration, frame rate, resolution, and codec.

Directional counting using configurable counting lines lets operators define the counting geometry visually against a reference frame; the system then counts vehicles crossing in each direction with precise, auditable attribution.

Fourteen-class vehicle classification is calibrated for the Indian and broader South Asian traffic mix, spanning two-wheelers, three-wheelers and auto rickshaws, cars and light commercial vehicles, mini and standard buses, multiple truck categories (rigid, tipper, multi-axle), tractors and tractor-trolleys, construction equipment, cycles, cycle rickshaws, and an "others" bucket for edge cases.

Interval-wise aggregation produces minute-by-minute, directional, and class-wise counts that can be rolled up into peak-hour summaries. A quality-control workflow surfaces suspicious events — counts that may warrant human review — and lets reviewers verify or correct outputs before a report is considered final. Verified jobs are flagged and attributed to the reviewer for traceability.

Live monitoring of in-progress analyses gives operators a real-time view of the detection pipeline so they can sanity-check early frames without waiting for the full job to complete. Multi-format export covers CSV (summary, directional, and minute-wise variants), richly formatted Excel workbooks, and printable PDF reports with embedded charts suitable for direct delivery to clients.

Multi-tenant administration rounds out the platform, including organisation management, per-organisation user provisioning, role-based access control, and subscription-tier attributes such as project and storage caps.

Technology Stack

The platform is built as a modern, containerised two-tier application with an asynchronous processing layer.

• Backend: Python 3.10+ on FastAPI, with SQLAlchemy 2.0 as the ORM and Alembic for schema migrations. Pydantic v2 drives request/response validation, and authentication is handled with JWT issued from a bcrypt-hashed credential store.
• Frontend: React 18 with Vite, React Router for client-side routing, Bootstrap 5 and react-bootstrap for the component system, Recharts for data visualisation, and react-hot-toast for feedback. Axios handles API communication.
• Computer Vision: Ultralytics YOLOv8 for object detection, paired with a ByteTrack-based tracker provided through the Supervision library, and OpenCV for video I/O and frame operations. Geometric logic is backed by Shapely.
• Asynchronous processing: Celery with a Redis broker, partitioned across purpose-specific queues for video ingestion, detection/analysis, and export generation.
• Data layer: PostgreSQL in production, with a SQLite fallback for local development — both served through the same ORM abstraction.
• Reporting & exports: pandas, openpyxl, WeasyPrint, Jinja2, and matplotlib together produce the CSV, Excel, and PDF deliverables.
• Deployment: Docker and Docker Compose, orchestrating a database service, Redis, the FastAPI API server, a Celery worker fleet, and the compiled frontend behind an HTTP server — all wired with health checks and persistent named volumes for uploads, processed artefacts, and generated exports.

Technical Complexity & Challenges

Behind the clean user experience sits a substantial engineering effort. The detection layer is the most technically demanding part of the system. Traffic video analysis is unforgiving: vehicles occlude one another, enter and leave the frame in quick succession, change apparent size as they approach the camera, and in many real-world recordings share the frame with shadows, glare, lens distortion, and motion blur. Getting a stable, high-quality count requires coordination between three layered subsystems — a detector, a tracker, and a counting policy — each of which has its own failure modes.

The architecture separates these concerns into dedicated modules. Two distinct pipelines exist: a buffered pipeline optimised for throughput on completed video jobs, and a live pipeline optimised for incremental feedback during processing. Together these pipelines are among the largest modules in the codebase, reflecting the amount of edge-case handling required to keep counts stable across a broad range of inputs. A separate suspicious-event detector layers heuristics on top of the raw count stream to flag outputs that deviate from expected patterns, which then drives the QC workflow.

The multi-tenant architecture introduces a second axis of complexity. Every request carries tenant context that must be propagated through authorisation checks, database queries, file storage paths, and background jobs. The platform enforces this with a dedicated tenant-context mechanism that is cleared after every request lifecycle, reducing the risk of cross-tenant leakage when workers are reused. Role-based access is enforced both in the API layer and in the frontend's route wrappers, so super admins, organisation admins, and end users each see only the surface area appropriate to their role.

The asynchronous processing tier adds further depth. Video analysis is a long-running, CPU- and memory-intensive workload; doing it inside a request-response cycle is infeasible. The platform pushes this work onto Celery workers across three logical queues so that operators can queue multiple jobs, cancel in-progress work, and receive live progress updates without blocking the API. Generated artefacts such as annotated preview videos are given explicit time-to-live semantics, balancing review convenience against storage cost.

Design & User Experience

The user interface is deliberately pragmatic. The target users are traffic analysts, project managers, and reviewers — professionals who need to move through a predictable workflow many times a day, not consumer users who need decorative polish. The design philosophy favours clarity, information density appropriate to the task, and consistent navigation over visual novelty.

The application shell uses a persistent layout with role-aware navigation, so administrative surfaces only appear to users who can act on them. Core workflows — project creation, video upload, analysis setup, results review, live monitoring — each have their own dedicated page, linked to one another through contextual actions. Recharts-based visualisations render counts, distributions, and time-series summaries on results pages, and Bootstrap's component library provides familiar affordances for forms, modals, tables, and status indicators.

Feedback is handled through non-blocking toast notifications, so operators are informed of upload progress, job state transitions, and errors without having their workflow interrupted. The analysis-setup workflow guides operators through defining counting lines visually and adjusting detection parameters, with sensible defaults so non-expert users can produce good results without tuning, while power users retain the option to override.

Scale & Scope

The codebase is substantial. The backend spans roughly 13,600 lines of Python across 64 source files, organised into clear functional layers: API endpoints, data models, validation schemas, core security and permissions, detection modules, exporters, workers, and database migrations. The frontend contributes another 5,500 lines across components, contexts, services, and roughly a dozen primary pages. Taken together, the platform comprises nearly 19,000 lines of hand-written application code before dependencies.

Structurally, the backend exposes seven distinct REST endpoint families (authentication, organisations, users, projects, videos, analyses, QC), backed by eight core domain models. The detection subsystem alone contains ten specialised modules, including two full processing pipelines. Three dedicated Celery task modules handle video preparation, detection, and export generation. On the frontend, thirteen primary pages deliver the operator workflows. From a deployment perspective, a single docker-compose up provisions five coordinated services with health checks, restart policies, and persistent volumes.

Business Impact & Use Case

The direct beneficiaries are organisations whose core deliverable is traffic data: transportation consultancies, traffic and transportation planning teams, civil engineering firms executing road and highway projects, toll-road operators, and urban mobility agencies. These organisations are typically commissioned to produce rigorous traffic counts as inputs into feasibility studies, road design, capacity analysis, junction improvement proposals, environmental assessments, and regulatory submissions.

Traditionally, the bottleneck in these studies is the human counting and review effort. The platform compresses that bottleneck. A single operator can supervise many parallel analyses rather than personally counting one video at a time. Classification granularity — fourteen vehicle classes including types specific to South Asian roads, where the vehicle mix is heterogeneous and agriculturally oriented vehicles are routine — is delivered by default rather than being cost-prohibitive. Outputs are reproducible and auditable, with every count linked to an analysis job, model version, parameters, and reviewer identity, which materially reduces the risk of disputes on deliverables. The multi-tenant model lets a single deployment serve many client organisations in parallel, each isolated from the others, with per-tenant limits that align naturally to subscription-based commercial offerings.

Development Approach

The backend follows a layered architecture that cleanly separates request handling, business logic, data access, and infrastructure integrations, which keeps modules individually testable and makes future evolution — such as new vehicle classes, new export formats, or new counting policies — a matter of extending specific layers rather than rewriting the system.

Schema changes are managed through Alembic migrations, giving the project a controlled, reversible history of its data model. Pydantic schemas provide strong input and output validation at the API boundary, catching malformed requests before they enter business logic. A centralised configuration system, backed by environment variables and documented through an example file, keeps secrets and environment-specific values out of source code. Pytest, pytest-asyncio, and pytest-cov support unit and integration testing, and the frontend is linted with ESLint rules tuned for React and React Hooks, with builds enforced to zero warnings.

Logging is configured globally and distinguishes between normal operation, validation warnings, and unexpected exceptions; unhandled errors in production are returned as generic messages to clients while retaining full detail in server logs. Containerisation through Docker Compose ensures developer environments match production closely. A dedicated training workspace provides the scaffolding for improving the underlying detection model over time without polluting the runtime application. The result is a production-ready, multi-tenant computer-vision SaaS platform that pairs modern web application engineering with applied deep-learning-based video analytics, delivering meaningful commercial value in a domain where manual labour has historically defined the cost structure.