2. FastAPI backend

The backend persists uploaded videos, analysis jobs, sessions, incidents, artifacts, and Android edge context.

Key files:

• driver_monitoring/api.py
• driver_monitoring/backend/models.py
• driver_monitoring/backend/services.py
• driver_monitoring/backend/jobs.py

3. Web dashboard

Located in apps/driveguard-web/.

This is the browser HMI for:

• desktop file upload
• browser live demo
• job monitoring
• session review
• Android edge summary review

4. Android edge app

Located in apps/driveguard-android/.

This is the on-device demo client. It currently supports:

• CameraX preview
• MediaPipe face signals
• LiteRT YOLOv8n mobile object detection
• local rule engine
• rolling pre-trigger / post-trigger clip capture
• Room persistence
• background upload retry with WorkManager
• sync of device, device_session, and edge_event to the backend

Architecture Overview

Simple view

flowchart LR
    Video["Video or camera source"] --> Python["Python analysis runtime"]
    Browser["Web dashboard"] --> Backend["FastAPI backend"]
    Android["Android edge app"] --> Backend
    Python --> Backend
    Backend --> Review["Jobs, sessions, incidents, reports"]
    Review --> Browser

Detailed view

flowchart TD
    subgraph Sources["Input surfaces"]
        DesktopVideo["Desktop video files"]
        BrowserLive["Browser live capture"]
        AndroidCamera["Android camera stream"]
        PythonWebcam["Python webcam / CLI / GUI"]
    end

    subgraph Edge["Android edge runtime"]
        AndroidCamera --> CameraX["CameraX preview and rolling capture"]
        CameraX --> Face["MediaPipe face signals"]
        CameraX --> Objects["LiteRT YOLOv8n object detection"]
        Face --> Rules["Local rule engine and suspicion score"]
        Objects --> Rules
        Rules --> Buffer["Useful clip buffer pre/post trigger"]
        Buffer --> Room["Room local storage"]
        Room --> AndroidWorker["WorkManager upload retry"]
    end

    subgraph Backend["FastAPI backend and persistence"]
        Uploads["Uploaded videos"]
        Jobs["Analysis jobs"]
        Sessions["Analysis sessions"]
        Incidents["Incidents"]
        Artifacts["Report artifacts"]
        Devices["Device / device_session / edge_event"]
    end

    subgraph PythonCore["Python CV runtime"]
        PythonWebcam --> Pipeline["Detection + tracking + face monitor + scoring"]
        DesktopVideo --> Pipeline
        Pipeline --> Reports["JSON / CSV session reports"]
    end

    BrowserLive --> Uploads
    BrowserLive --> Jobs
    AndroidWorker --> Uploads
    AndroidWorker --> Jobs
    Rules --> Devices
    Reports --> Sessions
    Reports --> Incidents
    Reports --> Artifacts
    Uploads --> Jobs
    Jobs --> Pipeline
    Jobs --> Sessions

    subgraph Web["Vue dashboard"]
        Home["Home"]
        NewAnalysis["New Analysis"]
        LiveDemo["Live Demo"]
        JobsView["Jobs"]
        SessionDetail["Session Detail"]
    end

    Backend --> Web
    Devices --> SessionDetail
    Sessions --> SessionDetail
    Incidents --> SessionDetail

Repository Layout

ADAS_YOLOv8-and-OpenCV/
|-- README.md
|-- config.toml
|-- yolo.py
|-- driver_monitoring/
|   |-- api.py
|   |-- cli.py
|   |-- gui.py
|   |-- pipeline.py
|   |-- event_engine.py
|   `-- backend/
|-- apps/
|   |-- driveguard-web/
|   `-- driveguard-android/
|-- tests/
|-- backend_uploads/
|-- backend_artifacts/
`-- outputs/

Important generated directories:

• backend_uploads/ stores uploaded videos
• backend_artifacts/ stores persisted exported reports
• outputs/ stores local Python analysis outputs

Prerequisites

Core

• Python 3.x
• Node.js + npm
• Git

For Android

• JDK 17
• Android Studio or Android SDK command-line tooling

Configuration

The main runtime configuration lives in config.toml.

It defines:

• model paths
• runtime dimensions and confidence threshold
• face thresholds
• rule thresholds
• backend storage and queue behavior

Current backend defaults include:

• SQLite database: sqlite:///driveguard_ai.db
• queue backend: inline
• uploads directory: backend_uploads
• artifacts directory: backend_artifacts
• local web CORS: http://localhost:5173 and http://127.0.0.1:5173

Quick Start

If you want the fastest meaningful demo, start with the backend + web dashboard.

1. Install Python dependencies

python -m pip install ultralytics opencv-python pillow deep-sort-realtime mediapipe fastapi uvicorn sqlalchemy redis rq python-multipart httpx

2. Start the backend

From the repo root:

python -m uvicorn driver_monitoring.api:app --host 127.0.0.1 --port 8000

Useful URLs:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

3. Start the web dashboard

cd apps/driveguard-web
npm install
npm run dev

Open the Vite URL shown in the terminal, usually:

• http://localhost:5173

4. Run a first demo

Recommended browser flow:

1. open the web dashboard
2. go to New Analysis for desktop upload or Live Demo for browser capture
3. create an analysis job
4. open Jobs
5. open the resulting Session Detail

How To Run Each Part

A. Python desktop GUI

This runs the original local desktop analysis UI.

python yolo.py

Entry point:

• yolo.py

B. Python CLI

Use the CLI when you want local analysis without the Tkinter GUI.

Single video:

python -m driver_monitoring.cli video --source path/to/video.mp4

Batch:

python -m driver_monitoring.cli batch --sources clip1.mp4 clip2.mp4

Webcam:

python -m driver_monitoring.cli webcam --device 0

C. FastAPI backend

python -m uvicorn driver_monitoring.api:app --host 127.0.0.1 --port 8000

If you want queue-based processing later, the repository also contains a worker entry point:

python -m driver_monitoring.worker --config config.toml

Note:

• the default config.toml currently uses queue_backend = "inline", so jobs run locally in-process unless you change the config

D. Web dashboard

Development:

cd apps/driveguard-web
npm install
npm run dev

Production build:

cd apps/driveguard-web
npm run build

E. Android edge app

Build a debug APK:

cd apps/driveguard-android
.\gradlew.bat app:assembleDebug

Then:

1. install the APK on an emulator or a real device
2. open Settings
3. set the backend URL
4. open Drive
5. grant camera and microphone permissions
6. start a session
7. review local events in Events
8. let useful clips sync to the backend

Android backend URL tips:

• emulator: http://10.0.2.2:8000
• physical device: use your machine LAN IP, for example http://192.168.x.x:8000

How To Execute Typical Product Flows

Flow 1: Local Python analysis only

Use this when you want to test the CV pipeline directly:

python -m driver_monitoring.cli video --source path/to/video.mp4

Result:

• local processing
• local exported outputs in outputs/

Flow 2: Browser upload -> backend -> dashboard review

1. start the backend
2. start the web dashboard
3. upload a file in New Analysis
4. watch progress in Jobs
5. inspect incidents in Session Detail

Flow 3: Browser live demo -> backend -> dashboard review

1. start backend and web
2. open Live Demo
3. record a short clip from the browser camera
4. upload automatically
5. inspect the resulting job and session

Flow 4: Android edge -> backend -> dashboard review

1. start backend
2. install the Android app
3. configure backend URL in Android settings
4. open Drive and start a session
5. let Android detect local risk signals and create useful clips
6. let Android sync the clip and edge context
7. inspect the resulting session in the web dashboard

API Surface

Main backend endpoints:

• GET /health
• POST /videos
• POST /analysis-jobs
• GET /analysis-jobs
• GET /analysis-jobs/{id}
• POST /analysis-jobs/{id}/cancel
• GET /sessions
• GET /sessions/{id}
• GET /sessions/{id}/incidents
• GET /sessions/{id}/edge-summary
• GET /reports/{id}

Android-specific backend endpoints:

• PUT /mobile/devices/{device_id}
• PUT /mobile/device-sessions/{device_session_id}
• PUT /mobile/edge-events/{edge_event_id}

Development-only immediate analysis endpoints:

• POST /dev/analyze/video
• POST /dev/analyze/batch

How To Test The Project

1. Python and backend automated tests

From the repo root:

python -m unittest discover -s tests -v

Current automated coverage includes:

• backend API behavior
• event engine logic
• reporting
• scoring

Test files:

• tests/test_backend_api.py
• tests/test_event_engine.py
• tests/test_reporting.py
• tests/test_scoring.py

2. Web validation

The web app currently does not have a dedicated automated test suite. The practical validation command today is the production build:

cd apps/driveguard-web
npm run build

This validates:

• TypeScript typing
• Vue compilation
• Vite production build

3. Android validation

The Android app currently uses build validation as the main safety c