# mwasifanwar/smartcity-vision architecture

> Architecture diagram of the GitHub repository mwasifanwar/smartcity-vision, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mwasifanwar/smartcity-vision
- Repository: https://github.com/mwasifanwar/smartcity-vision

## Overview

##### Project type and purpose
- This is a full-stack computer-vision system (“smartcity-vision”) for real-time smart-city management.
- It ingests CCTV feeds and satellite imagery, runs ML‐powered detectors and analyzers (traffic, crowd, parking, pedestrians), exposes results via a FastAPI service, and drives an interactive dashboard.

##### File structure
- Top-level directories:
- api: FastAPI server and endpoint definitions
- core: processing modules (object_detector, traffic_analyzer, crowd_density, etc.)
- dashboard: front-end app (likely Streamlit or Flask)
- data: sample data for testing or demo
- models: ML model wrappers (YOLO, custom)
- utils: shared helpers (config loader, video processing, geo utilities, visualization)
- tests: unit tests for detectors and analyzers
- Key scripts:
- main.py: orchestrates end-to-end pipeline (ingestion → processing → serving)
- run_dashboard.py: launches the dashboard GUI
- config.yaml + utils/config_loader.py: centralized configuration

##### README for additional insights
- Purpose: real-time detection of traffic patterns, crowd density, parking availability, and pedestrian flow.

a. Main components
1. Data Sources
– CCTV camera streams
– Satellite imagery service
2. Video Ingestion & Preprocessing
– utils/video_processor.py
– utils/config_loader.py (config.yaml)
3. Core Analysis Pipeline
– core/object_detector.py (uses models/yolo_model.py & custom_models.py)
– core/traffic_analyzer.py
– core/crowd_density.py
– core/parking_analyzer.py
– core/pedestrian_tracker.py
4. Data Storage (optional)
– In-memory queues or time-series DB (not in code but you may annotate)
5. API Layer
– api/fastapi_server.py & api/endpoints.py
6. Dashboard Frontend
– dashboard/app.py (run via run_dashboard.py)
7. Utilities
– utils/geo_utils.py, utils/visualization.py

b. Relationships & Data Flow
– Ingestion → Core Analysis modules (object detection first → specialized analyzers)
– Analysis outputs → API Layer (exposed as REST/WebSocket endpoints)
– Dashboard polls/subscribes to API to render live metrics & maps
– Configuration flows into Ingestion & API at startup via config_loader

c. Architectural Patterns & Design Principles
– Modular Pipeline: each analyzer is a separate module that can be chained or replaced
– Service-Oriented: clear separation between processing logic (core) and serving logic (api + dashboard)
– Dependency Injection: config_loader centralizes parameters for all modules
– Testable Units: core and models directories have accompanying tests

d. Key Technologies & Frameworks
– Python 3.x, FastAPI for the REST layer
– YOLO (and custom) models for object detection (likely using PyTorch or TensorFlow)
– Video processing via OpenCV or similar (inside utils/video_processor.py)
– Dashboard framework (Flask/Streamlit) in dashboard/app.py

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestration Entry Point
    Main["main.py\n(Orchestration)"]:::main

    %% Data Sources & Storage
    subgraph "Data Sources & Storage"
        direction TB
        CCTV["Live CCTV Streams"]:::data
        Satellite["Satellite Imagery Service"]:::data
        SampleData["data/sample_data.py"]:::data
        Queue["In-Memory Queue / Time-Series DB"]:::data
    end

    %% Ingestion & Preprocessing
    subgraph "Data Ingestion & Preprocessing"
        direction TB
        VideoProcessor["utils/video_processor.py"]:::processing
        ConfigLoader["utils/config_loader.py"]:::processing
        ConfigYAML["config.yaml"]:::processing
    end

    %% Core Analysis Pipeline
    subgraph "Core Analysis Pipeline"
        direction TB
        ObjectDetector["core/object_detector.py"]:::processing
        subgraph "Models"
            direction TB
            YOLO["models/yolo_model.py"]:::processing
            CustomModels["models/custom_models.py"]:::processing
        end
        TrafficAnalyzer["core/traffic_analyzer.py"]:::processing
        CrowdDensity["core/crowd_density.py"]:::processing
        ParkingAnalyzer["core/parking_analyzer.py"]:::processing
        PedestrianTracker["core/pedestrian_tracker.py"]:::processing
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        FastAPIServer["api/fastapi_server.py"]:::api
        Endpoints["api/endpoints.py"]:::api
    end

    %% Dashboard Frontend
    subgraph "Dashboard Frontend"
        direction TB
        DashboardApp["dashboard/app.py"]:::ui
        RunDashboard["run_dashboard.py"]:::ui
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        GeoUtils["utils/geo_utils.py"]:::utils
        Visualization["utils/visualization.py"]:::utils
    end

    %% Testing
    subgraph "Tests"
        direction TB
        TestAnalyzer["tests/test_analyzer.py"]:::tests
        TestDetector["tests/test_detector.py"]:::tests
    end

    %% Data Flow Arrows
    Main -->|launches| VideoProcessor
    Main -->|launches| FastAPIServer
    Main -->|launches| DashboardApp

    CCTV -->|video frames| VideoProcessor
    Satellite -->|imagery| VideoProcessor
    SampleData -->|demo input| VideoProcessor

    ConfigYAML -->|load config| ConfigLoader
    ConfigLoader -->|provide params| VideoProcessor
    ConfigLoader -->|provide params| FastAPIServer
    ConfigLoader -->|provide params| ObjectDetector

    VideoProcessor -->|preprocessed frames| ObjectDetector

    ObjectDetector -->|detections| TrafficAnalyzer
    ObjectDetector -->|detections| CrowdDensity
    ObjectDetector -->|detections| ParkingAnalyzer
    ObjectDetector -->|detections| PedestrianTracker

    YOLO -->|model infer| ObjectDetector
    CustomModels -->|model infer| ObjectDetector

    TrafficAnalyzer -->|metrics| FastAPIServer
    CrowdDensity -->|metrics| FastAPIServer
    ParkingAnalyzer -->|metrics| FastAPIServer
    PedestrianTracker -->|metrics| FastAPIServer

    FastAPIServer -->|serves API| Endpoints
    Endpoints -->|JSON metrics| DashboardApp
    DashboardApp -->|UI update| RunDashboard

    GeoUtils -->|geo processing| TrafficAnalyzer
    Visualization -->|charts/maps| DashboardApp

    %% Click Events
    click VideoProcessor "https://github.com/mwasifanwar/smartcity-vision/blob/main/utils/video_processor.py"
    click ConfigLoader "https://github.com/mwasifanwar/smartcity-vision/blob/main/utils/config_loader.py"
    click ConfigYAML "https://github.com/mwasifanwar/smartcity-vision/blob/main/config.yaml"
    click ObjectDetector "https://github.com/mwasifanwar/smartcity-vision/blob/main/core/object_detector.py"
    click YOLO "https://github.com/mwasifanwar/smartcity-vision/blob/main/models/yolo_model.py"
    click CustomModels "https://github.com/mwasifanwar/smartcity-vision/blob/main/models/custom_models.py"
    click TrafficAnalyzer "https://github.com/mwasifanwar/smartcity-vision/blob/main/core/traffic_analyzer.py"
    click CrowdDensity "https://github.com/mwasifanwar/smartcity-vision/blob/main/core/crowd_density.py"
    click ParkingAnalyzer "https://github.com/mwasifanwar/smartcity-vision/blob/main/core/parking_analyzer.py"
    click PedestrianTracker "https://github.com/mwasifanwar/smartcity-vision/blob/main/core/pedestrian_tracker.py"
    click FastAPIServer "https://github.com/mwasifanwar/smartcity-vision/blob/main/api/fastapi_server.py"
    click Endpoints "https://github.com/mwasifanwar/smartcity-vision/blob/main/api/endpoints.py"
    click DashboardApp "https://github.com/mwasifanwar/smartcity-vision/blob/main/dashboard/app.py"
    click RunDashboard "https://github.com/mwasifanwar/smartcity-vision/blob/main/run_dashboard.py"
    click Main "https://github.com/mwasifanwar/smartcity-vision/blob/main/main.py"
    click GeoUtils "https://github.com/mwasifanwar/smartcity-vision/blob/main/utils/geo_utils.py"
    click Visualization "https://github.com/mwasifanwar/smartcity-vision/blob/main/utils/visualization.py"
    click SampleData "https://github.com/mwasifanwar/smartcity-vision/blob/main/data/sample_data.py"
    click TestAnalyzer "https://github.com/mwasifanwar/smartcity-vision/blob/main/tests/test_analyzer.py"
    click TestDetector "https://github.com/mwasifanwar/smartcity-vision/blob/main/tests/test_detector.py"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef processing fill:#90EE90,stroke:#333,stroke-width:1px
    classDef api fill:#FFA500,stroke:#333,stroke-width:1px
    classDef ui fill:#DA70D6,stroke:#333,stroke-width:1px
    classDef utils fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef tests fill:#FFB6C1,stroke:#333,stroke-width:1px
    classDef main fill:#FFE4B5,stroke:#333,stroke-width:1px
```
