Motion

Motion is a real‑time traffic‑intelligence system that processes video streams, detects and tracks objects, estimates their velocity, and provides live analytics through a web dashboard.

Architecture Overview

flowchart LR
    subgraph Frontend
        FE[Next.js UI]
        FE -->|WebSocket| WS[Redis Pub/Sub]
        FE -->|REST| API[FastAPI]
    end
    subgraph Backend
        API -->|Task Queue| CEL[Celery Worker]
        CEL -->|Video Processing| CV[OpenCV & YOLOv8]
        CEL -->|DB Writes| PG[PostgreSQL]
        WS -->|Frames| FE
    end
    subgraph Infra
        Redis[Redis]
        PG
        Docker[Docker Compose]
    end
    API --> Redis
    CEL --> Redis
    Redis -->|Pub/Sub| WS
    Docker --> Redis & PG

Loading

The diagram above shows the high‑level data flow:

1. The user uploads a video via the frontend.
2. The FastAPI service receives the request and enqueues a Celery job.
3. The worker runs OpenCV + YOLOv8 inference, writes an annotated MP4, and publishes each frame to Redis.
4. The frontend receives frames over a WebSocket connection and renders them in real‑time.
5. Detection events are batched and stored in PostgreSQL for analytics.

Screenshots

Page	Screenshot
Upload page
Upload progress
Live traffic view
Bus motor detection
Cars in motion

Tech Stack

• Python – backend and ML pipeline.
• FastAPI – async API & WebSocket server.
• Celery + Redis – background processing and frame pub/sub.
• PostgreSQL + TimescaleDB – persistent event storage.
• OpenCV / PyTorch (YOLOv8) – video decoding and object detection.
• Next.js (React) + Tailwind CSS – modern frontend UI.
• Docker Compose – local development environment.
• GitHub Actions – CI pipeline (pytest, linting, build checks).

Directory Structure

Motion/
├─ backend/                     # FastAPI backend
│   ├─ app/
│   │   ├─ api/                # HTTP & WebSocket routers
│   │   ├─ core/               # ML logic (detector, tracker, heatmap, etc.)
│   │   ├─ db/                 # SQLModel/SQLAlchemy models and CRUD
│   │   └─ tasks/              # Celery workers (video_worker.py)
│   └─ tests/                  # Test suite
├─ frontend/                    # Next.js application
│   └─ src/
│       ├─ app/               # Pages (upload, dashboard)
│       ├─ components/        # UI components
│       └─ hooks/             # Data‑fetching hooks
├─ docker-compose.yml           # Local PostgreSQL & Redis services
├─ README.md                    # Project documentation
└─ screenshots/                 # Images used in documentation

Running Locally

# Start infrastructure
docker-compose up -d postgres redis

# Backend (FastAPI + Celery)
cd backend
python -m venv .venv
source .venv/bin/activate   # .venv\\Scripts\\activate on Windows
pip install -r requirements.txt
# Run API
uvicorn app.main:app --reload
# In a new terminal, run Celery worker
celery -A app.tasks.celery_app worker --loglevel=info --queues=video

# Frontend (Next.js)
cd ../frontend
npm install
npm run dev

Navigate to http://localhost:3000 to explore the dashboard.