docs/BACKEND_ARCHITECTURE.md

# Backend Architecture

## Overview

The backend is a FastAPI service that combines:

1. AI inference pipeline (vehicle, plate, OCR)
2. Supabase data and storage persistence
3. Parking session lifecycle management
4. Dynamic pricing and occupancy calculations
5. Gate and payment decision flows

## Core Runtime Components

- API framework: FastAPI
- Inference runtime: Ultralytics YOLO + OpenCV + NumPy
- Data/Auth backend: Supabase REST + Supabase Auth token validation
- Device auth option: static barrier tokens (`BARRIER_API_TOKEN` / `BARRIER_API_TOKENS`)
- Deployment target (current): Hugging Face Spaces (Docker)
- Alternative deployment targets: Fly.io and Render

## Request Processing Flow (`POST /predict`)

1. Validate request body and optional inputs (`event_type`, `parking_location`, `camera_source`).
2. Decode uploaded image to OpenCV matrix.
3. Run AI pipeline:
   - vehicle detection on full image
   - plate detection on selected vehicle crop
   - OCR model on selected plate crop
4. Build user/admin image outputs and plate payload.
5. Resolve/apply session state in Supabase.
   - Vehicle matching uses both Arabic and English OCR plate formats.
6. Persist event metadata and storage paths.
7. Compute pricing and gate decision.
8. Return unified response for Flutter client.

## Session Lifecycle

The backend tracks session lifecycle through events and `parking_sessions` records.

Typical journey:

1. Entry event creates or reuses open session (`status=entered`).
2. Payment confirms session (`status=paid`).
3. Exit event closes session (`status=exited`) or marks overstayed.
4. `left_within_5_minutes` is used by policy feeds and gate logic.

## Role Model and Access

Roles are stored in Supabase `profiles.role`:

1. `user`
2. `admin`
3. `security`
4. `barrier` (API-only synthetic role from barrier token auth)

Scope behavior:

- user: own records only
- admin/security: all records, with optional `for_user_id` filtering on feed/history APIs
- barrier: global read scope for operational feeds/history and gate decision checks

## Dynamic Pricing Engine

Pricing is computed in backend code using env-driven policies.

Policy dimensions:

1. billing mode (`hourly` or `daily`)
2. base rate
3. extra fee after first billing window
4. app service fee
5. location-specific overrides

The backend returns pricing as structured JSON, not a UI-formatted string.

## Occupancy Engine

Occupancy is derived from two sources:

1. open registered sessions (`check_out_at is null`)
2. inferred unmatched inside cars from `car_events` (for plates not linked to a session)

Outputs include:

1. garage occupancy (`inside`, `left`, `display`, `total_capacity`)
2. per-location occupancy (`inside`, `left`, `display`, `total_capacity`)
3. occupancy source breakdown (`inside_from_registered_sessions`, `inside_from_inferred_unmatched`)

## Payment Integration

Two flows are supported:

1. Card flow (Paymob) via create + webhook endpoints
2. Manual cash confirmation flow for staff roles

## Supabase Persistence Areas

Main tables:

1. `profiles`
2. `vehicles`
3. `parking_sessions`
4. `car_events`
5. `payment_transactions`

Storage buckets:

1. `car-raw-images`
2. `car-processed-images`

## Operational Endpoints

Health and operations endpoints:

1. `/health`
2. `/supabase/health`
3. `/admin/maintenance/weekly-refresh`

These endpoints support deployment validation and maintenance tasks.