# ecocity-the-try-people/ecocity-traffic-prediction architecture

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

- Interactive diagram: https://gitdiagram.com/ecocity-the-try-people/ecocity-traffic-prediction
- Repository: https://github.com/ecocity-the-try-people/ecocity-traffic-prediction

## Overview

##### Project Type & Purpose
- This is a single-service, Python-based image-processing component of a larger “Ecocity Traffic Prediction” system.
- It fetches traffic images from Firebase, runs YOLOv8 inference to detect vehicles, computes a congestion level, and writes results back to Firebase.

##### Key Components & Boundaries
a. External Image Source
- Could be IoT cameras or an upstream service that pushes image URLs into Firebase Realtime Database or Cloud Storage.
b. Firebase (Google Cloud)
- Authentication & Credentials (via `firebase_admin` + JSON key)
- Realtime Database (stores image URLs and congestion results)
- (Optionally) Cloud Storage for actual image blobs
c. Processing Service (main.py)
- Environment loader (`dotenv`)
- Firebase client (`firebase_admin`)
- Image fetcher (`requests`, `io`, `PIL`)
- YOLOv8 inference engine (`ultralytics`, model file `yolov8n.pt`)
- Congestion calculator (simple vehicle count → level)
- Database updater (writes back to Firebase)
d. Developer Machine / Scheduler
- Cron job or manual trigger that runs `python main.py`

##### Architectural Patterns & Principles
- Single responsibility: The service only handles image analysis & DB updates.
- Stateless processing: Each run fetches data, computes, writes results without local persistence.
- Dependency injection via environment variables: Credentials and DB URLs configured in `.env`
- Model as a resource: `yolov8n.pt` loaded at startup or per invocation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Machine
    subgraph "Developer Machine"
        Cron["Scheduler / Cron Job"]:::external
    end

    %% Processing Service
    subgraph "Processing Service"
        PS["main.py"]:::compute
        subgraph "Modules"
            Env["Environment Loader\n(dotenv)"]:::compute
            FBClient["Firebase Client\n(firebase_admin)"]:::compute
            Fetcher["Image Fetcher\n(requests, PIL)"]:::compute
            Inference["Inference Engine\n(ultralytics)"]:::compute
            Calculator["Congestion Calculator"]:::compute
            Updater["Database Updater"]:::compute
        end
        Model["yolov8n.pt"]:::resource
    end

    %% Firebase Cloud Services
    CloudFirebase["Firebase Cloud"]:::external
    DB["Realtime Database"]:::storage
    Storage["Cloud Storage"]:::storage

    %% Project Files
    subgraph "Project Files"
        Req["requirements.txt"]:::docs
        Readme["README.md"]:::docs
        Gitignore[".gitignore"]:::docs
        IDE[".idea/"]:::docs
        ImagesDir["images/"]:::resource
    end

    %% Data Flows
    Cron -->|"execute main.py"| PS
    PS -->|"load .env vars"| Env
    PS -->|"init firebase_admin"| FBClient
    PS -->|"read image URL\n(Firebase SDK)"| DB
    FBClient --> DB
    PS -->|"download image bytes\n(HTTP GET)"| Storage
    PS -->|"fetch image bytes"| Fetcher
    PS -->|"infer bounding boxes"| Inference
    Inference -->|"loads model"| Model
    PS -->|"compute congestion"| Calculator
    PS -->|"write results\n(Firebase SDK)"| DB
    PS --> FBClient

    %% Click Events
    click PS "https://github.com/ecocity-the-try-people/ecocity-traffic-prediction/blob/main/main.py"
    click Model "https://github.com/ecocity-the-try-people/ecocity-traffic-prediction/blob/main/yolov8n.pt"
    click ImagesDir "https://github.com/ecocity-the-try-people/ecocity-traffic-prediction/tree/main/images/"
    click Req "https://github.com/ecocity-the-try-people/ecocity-traffic-prediction/blob/main/requirements.txt"
    click Readme "https://github.com/ecocity-the-try-people/ecocity-traffic-prediction/blob/main/README.md"
    click Gitignore "https://github.com/ecocity-the-try-people/ecocity-traffic-prediction/blob/main/.gitignore"
    click IDE "https://github.com/ecocity-the-try-people/ecocity-traffic-prediction/tree/main/.idea/"

    %% Styles
    classDef external fill:#AED6F1,stroke:#217DBB;
    classDef compute fill:#ABEBC6,stroke:#239B56;
    classDef storage fill:#F9E79F,stroke:#B7950B;
    classDef resource fill:#FAD7A0,stroke:#CA6F1E;
    classDef docs fill:#D5D8DC,stroke:#566573;
```
