How shubanms/parking-lot-occupancy works
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