# shubanms/parking-lot-occupancy architecture

> Architecture diagram of the GitHub repository shubanms/parking-lot-occupancy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shubanms/parking-lot-occupancy
- Repository: https://github.com/shubanms/parking-lot-occupancy

## Overview

This is a **cloud-hosted computer-vision inference API**:
- **FastAPI** exposes two endpoints:
- `POST /upload_image/` (store an image)
- `GET /get_parking_lot_state/?model_version=v8` (run detection + slot-mapping and return occupancy JSON)
- Core logic: **YOLOv8 vehicle detection** + **PSAT (Parking Slot Alignment Transformation)** to map detections to “virtual parking slots”
- Persistence/integration: **Azure Blob Storage** for uploaded image storage/retrieval
- Deployment target: **Azure App Service** (and optionally Docker/K8s later)
- CI: GitHub Actions workflow exists

Produce **three views** (all derived from the same components). This yields the “most accurate” system design representation.

**Goal:** Who uses it, what external systems exist.
- “Client” (browser, mobile app, operator, or integration)
- “Parking Occupancy API (FastAPI)”
- “Azure Blob Storage”
- (Optional) “YOLOv8 weights/model source” if models are downloaded externally or stored in blob

- Client → API: upload image / get state
- API ↔ Blob: store & retrieve images

**Goal:** Show deployable units + runtime boundaries on Azure.
- “Azure App Service (Linux)”
- contains “FastAPI app (uvicorn)”
- contains “Inference runtime (YOLOv8 + PSAT)”
- “Azure Blob Storage (Container)”
- “Client”

- HTTPS Client → App Service
- App Service → Blob Storage (upload/download)
- Internal callouts: endpoint handlers → service layer → detector/blob manager

Annotate:
- Language: Python 3.11+
- Key libs: FastAPI, Ultralytics YOLOv8, Azure Storage SDK

**Goal:** Show the code-level components as they appear in `src/`.
- `main.py` (API routes)
- `schemas.py` (request/response models)
- `services.py` (orchestration)
- `blob_manager.py` (storage adapter)
- `detector.py` (YOLOv8 + PSAT pipeline)
- `configs.py` (configuration provider)

##### `POST /upload_image/`
- Route (main.py) → `services.upload_image(...)`
- `services` → `blob_manager.upload(...)` → Azure Blob Storage
- Return: blob URL / object key / success payload
##### `GET /get_parking_lot_state/`
- Route → `services.get_parking_lot_state(model_version)`
- `services` → `blob_manager.download(...)` (fetch most recent or referenced image)
- `services` → `detector.run(image, model_version)`
- “Preprocess image”
- “YOLOv8 detect vehicles”
- “PSAT transform / slot alignment”
- “Slot occupancy computation”
- `services` → returns `schemas.ParkingLotStateResponse` (or equivalent)

- `services`, `blob_manager`, `detector` → `configs` (for credentials, container name, defaults)
- `main.py` ↔ `schemas` (validation/serialization)

Make these flows impossible to misread:
- **State is derived from an image**: occupancy depends on the latest uploaded blob (or a specified blob key if implemented).
- **Blob storage is the system of record for images**: API is stateless aside from model caching.
- **Model version parameter** influences detector behavior**: show `model_version` as an input to detector/model selection.

##### Architectural patterns present (call them out visually)
- **Layered architecture**:
- API layer: `main.py`, `schemas.py`
- Service/application layer: `services.py`
- Domain/core: `detector.py` (YOLO + PSAT)
- Infrastructure adapter: `blob_manager.py` (Azure Blob)
- Configuration: `configs.py`
- **Adapter pattern** for cloud storage: `BlobManager` isolates Azure SDK calls.
- **DTO/schema boundary** (Pydantic) between HTTP and internal logic.

A small “Delivery” lane or side panel:
- GitHub Repo
- GitHub Actions (`.github/workflows/main_parking-occupancy.yml`)
- Deploy target: Azure App Service
- Config injection: environment variables / secrets (Blob credentials)

- Git push → GitHub Actions → Azure deploy

From this repo structure, avoid implying:
- A separate DB (none shown)
- A message queue/worker pool (none shown)
- A distinct “frontend” app (none shown)

##### Minimal checklist for “best and most accurate”
- [ ] 3 views: Context, Container (Azure), Component (FastAPI internals)
- [ ] Explicit endpoint flows for both routes
- [ ] Explicit separation: API vs Services vs Detector vs Blob adapter vs Config vs Schemas
- [ ] Show YOLOv8 + PSAT as sub-stages inside detector
- [ ] Show Azure Blob as the persistence boundary
- [ ] Show CI/CD workflow and deploy target

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% View A: System Context (C4 L1)
    %% =========================
    subgraph "A) System Context (C4 Level 1)"
        direction TB

        Client["Client\n(Browser/Mobile/Operator/Integration)"]:::external

        subgraph "Parking Occupancy System"
            direction TB
            APIContext["Parking Occupancy API\n(FastAPI)"]:::api
        end

        Blob["Azure Blob Storage\n(Image containers)"]:::storage
        ModelSrc["YOLOv8 model weights source\n(Local packaged or external download)"]:::externalDep

        Client -->|"HTTPS multipart/form-data\nPOST /upload_image/\n(image bytes)"| APIContext
        Client -->|"HTTPS GET\nGET /get_parking_lot_state/?model_version=v8\n(occupancy JSON)"| APIContext

        APIContext -->|"Azure Blob SDK\n(upload image bytes)\n(blob key/url)"| Blob
        APIContext -->|"Azure Blob SDK\n(download latest/requested)\n(image bytes)"| Blob

        APIContext -.->|"loads/uses\n(model weights by version)"| ModelSrc
    end

    %% =========================
    %% View B: Container (C4 L2)
    %% =========================
    subgraph "B) Container Diagram (C4 Level 2) - Azure Deployment"
        direction TB

        ClientB["Client"]:::external

        subgraph "Azure (Managed Platform)"
            direction TB

            subgraph "Azure App Service (Linux)"
                direction TB
                FastAPIContainer["FastAPI app (Uvicorn)\nPython 3.11+\nEndpoints: /upload_image/, /get_parking_lot_state/"]:::api
                InferenceRuntime["Inference runtime\nUltralytics YOLOv8 + PSAT\n(sync in-process)"]:::core
            end

            BlobB["Azure Blob Storage\n(Container for uploaded images)"]:::storage
        end

        ClientB -->|"HTTPS\nmultipart/form-data + JSON\n(image bytes / occupancy JSON)"| FastAPIContainer
        FastAPIContainer -->|"in-process call\n(sync inference request)"| InferenceRuntime

        FastAPIContainer -->|"Azure Blob SDK\nupload/download\n(image bytes, blob key/url)"| BlobB
        InferenceRuntime -.->|"model_version selects\nweights/pipeline config"| InferenceRuntime
    end

    %% =========================
    %% View C: Component (C4 L3)
    %% =========================
    subgraph "C) Component Diagram (C4 Level 3) - FastAPI Container Internals"
        direction TB

        subgraph "FastAPI App (single process, stateless except model caching)"
            direction TB

            Main["API Routes & App Setup\n(main.py)"]:::api
            Schemas["Schemas/DTOs (Pydantic)\n(src/schemas/schemas.py)"]:::cross
            Services["Service Layer (Orchestration)\n(src/service/services.py)"]:::service

            BlobMgr["Azure Blob Adapter\n(src/blob/blob_manager.py)"]:::integration
            Configs["Config/Env Provider\n(src/config/configs.py)"]:::cross

            subgraph "Detector Component\n(src/core/detector.py)"
                direction TB
                Detector["Detector\n(YOLOv8 + PSAT + occupancy)"]:::core
                Pre["Preprocess image"]:::coreStage
                Yolo["YOLOv8 detect vehicles\n(model_version-dependent)"]:::coreStage
                PSAT["PSAT transform / slot alignment"]:::coreStage
                Occupancy["Slot occupancy computation\n(occupied/free per virtual slot)"]:::coreStage

                Detector -->|"stage"| Pre
                Pre -->|"stage"| Yolo
                Yolo -->|"detections"| PSAT
                PSAT -->|"mapped slots"| Occupancy
            end
        end

        BlobC["Azure Blob Storage\n(System of record for images)"]:::storage

        %% Endpoint flow 1: upload_image
        Main -->|"POST /upload_image/\nHTTPS multipart/form-data\n(image bytes)"| Services
        Main <-->|"Pydantic validation/serialization\n(request/response DTOs)"| Schemas
        Services -->|"Azure Blob SDK\nupload(image bytes)\n(return blob key/url)"| BlobMgr
        BlobMgr -->|"Azure Blob SDK\nPUT blob\n(image bytes)"| BlobC
        Services -->|"return payload\n(blob key/url + status)"| Main

        %% Endpoint flow 2: get_parking_lot_state
        Main -->|"GET /get_parking_lot_state/\nHTTPS GET\n(model_version param)"| Services
        Services -->|"Azure Blob SDK\ndownload(latest/requested)\n(image bytes)"| BlobMgr
        BlobMgr -->|"Azure Blob SDK\nGET blob\n(image bytes)"| BlobC
        Services -->|"run(image, model_version)\n(sync inference)"| Detector
        Detector -->|"occupancy state\n(occupancy JSON)"| Services
        Services -->|"return\nSchemas response DTO\n(occupancy JSON)"| Main

        %% Cross-cutting config dependencies
        Services -.->|"reads\n(container name/defaults)"| Configs
        BlobMgr -.->|"reads\n(credentials/container)"| Configs
        Detector -.->|"reads\n(default model version/paths)"| Configs
    end

    %% =========================
    %% Delivery / CI-CD lane
    %% =========================
    subgraph "Delivery (CI/CD)"
        direction TB
        Repo["GitHub Repository"]:::external
        GHA["GitHub Actions Workflow\n(.github/workflows/main_parking-occupancy.yml)"]:::cicd
        Deploy["Deploy to Azure App Service\n(config via env vars/secrets)"]:::cicd

        Repo -->|"git push"| GHA
        GHA -->|"build/test/package\n+ deploy"| Deploy
        Deploy -->|"release artifact\n& settings injection"| FastAPIContainer
    end

    %% =========================
    %% Click Events (from component mapping)
    %% =========================
    click Main "https://github.com/shubanms/parking-lot-occupancy/blob/main/main.py"
    click Services "https://github.com/shubanms/parking-lot-occupancy/blob/main/src/service/services.py"
    click Detector "https://github.com/shubanms/parking-lot-occupancy/blob/main/src/core/detector.py"
    click BlobMgr "https://github.com/shubanms/parking-lot-occupancy/blob/main/src/blob/blob_manager.py"
    click Configs "https://github.com/shubanms/parking-lot-occupancy/blob/main/src/config/configs.py"
    click Schemas "https://github.com/shubanms/parking-lot-occupancy/blob/main/src/schemas/schemas.py"
    click GHA "https://github.com/shubanms/parking-lot-occupancy/blob/main/.github/workflows/main_parking-occupancy.yml"

    %% =========================
    %% Styles
    %% =========================
    classDef external fill:#F5F7FA,stroke:#6B7280,stroke-width:1px,color:#111827
    classDef externalDep fill:#EEF2FF,stroke:#4F46E5,stroke-width:1px,color:#111827,stroke-dasharray: 4 3
    classDef api fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1.5px,color:#0B1220
    classDef service fill:#E0F2FE,stroke:#0369A1,stroke-width:1.5px,color:#0B1220
    classDef core fill:#DCFCE7,stroke:#16A34A,stroke-width:1.5px,color:#052e16
    classDef coreStage fill:#BBF7D0,stroke:#16A34A,stroke-width:1px,color:#052e16
    classDef integration fill:#FFEDD5,stroke:#C2410C,stroke-width:1.5px,color:#1F1300
    classDef storage fill:#FFE4E6,stroke:#BE123C,stroke-width:1.5px,color:#1F0A0A
    classDef cross fill:#E5E7EB,stroke:#374151,stroke-width:1.2px,color:#111827
    classDef cicd fill:#FEF3C7,stroke:#B45309,stroke-width:1.5px,color:#1F1300
```
