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.