docs/DOC.md

# Ain El Aql Backend - Comprehensive Technical Documentation

## 1) Purpose and Scope

This document is the single-source technical overview for the Ain El Aql backend.

It covers:

1. System architecture
2. Authentication and authorization
3. Role model and access scope
4. Endpoint catalog and contracts
5. End-to-end data flow
6. Database model and relationships
7. Validation, errors, and operational behavior
8. Production readiness guidance

Primary implementation file:

- `API.py`

Supporting documentation:

- `docs/API_REFERENCE.md`
- `docs/BACKEND_ARCHITECTURE.md`
- `docs/ENVIRONMENT_VARIABLES.md`

---

## 2) System Architecture

The backend is a FastAPI monolith that combines:

1. AI inference orchestration (local YOLO or remote model service)
2. Supabase-backed auth, profile, data persistence, and storage
3. Parking/session lifecycle and event feeds
4. Pricing and occupancy engines
5. Gate/payment decision logic

### Runtime Components

1. API framework: FastAPI
2. CV/ML runtime: OpenCV, NumPy, Ultralytics YOLO
3. Data/auth/storage backend: Supabase (Auth + PostgREST + Storage)
4. Payment provider: Paymob (optional)

### Inference Modes

1. `MODEL_INFERENCE_PROVIDER=local`
   - Inference executed in this service.
2. `MODEL_INFERENCE_PROVIDER=remote`
   - Backend calls external model runtime using `MODEL_SERVICE_URL`.

---

## 3) Authentication and Authorization

The backend supports two authentication paths:

1. Supabase JWT bearer token
2. Barrier/device static token

### 3.1 Supabase Token Auth

- Header: `Authorization: Bearer <supabase_access_token>`
- Validation endpoint: Supabase `GET /auth/v1/user`
- On successful verification:
  - backend derives user id/email
  - backend auto-creates a minimal `profiles` row when missing (best effort)

Why auto-provision profile rows:

- Prevent FK failures on writes referencing `profiles.id`.
- Reduce silent persistence failures when auth users exist but profile rows do not.

### 3.2 Barrier/Device Token Auth

- Header: `Authorization: Bearer <barrier_token>`
- Token sources:
  - `BARRIER_API_TOKEN` (single token)
  - `BARRIER_API_TOKENS` (comma-separated tokens)
- Comparison uses constant-time matching (`hmac.compare_digest`).
- Returns synthetic auth context:
  - `id = BARRIER_SYNTHETIC_USER_ID` (default `barrier-device`)
  - `role = barrier`
  - `auth_type = barrier_token`

Important:

- Barrier auth is intended for machine integrations (camera/barrier clients).
- Barrier auth is not a substitute for end-user mobile/web sessions.

---

## 4) Role Model and Access Scope

Roles in runtime behavior:

1. `user`
2. `admin`
3. `security`
4. `developer`
5. `barrier` (synthetic API role)

### 4.1 Scope Rules

1. User scope:
   - Own records only
2. Staff scope (`admin`, `security`):
   - Global records
   - optional `for_user_id` filtering on feed/history endpoints
3. Barrier scope (`barrier`):
   - Global read scope for operational feeds/history and gate decision checks
   - Not treated as staff for privileged maintenance/payment confirmations
4. Developer scope (`developer`):
   - Access to developer endpoints (`/developer/*`)

---

## 5) Endpoint Catalog

### 5.1 Public/Utility

1. `GET /`
2. `GET /health`
3. `GET /supabase/health`
4. `GET /models`

### 5.2 Developer

1. `GET /developer/models`
2. `POST /developer/predict`

### 5.3 Authentication

1. `POST /auth/register`
2. `POST /auth/login`
3. `POST /auth/otp/request`
4. `POST /auth/otp/verify`
5. `POST /auth/forgot-password`
6. `POST /auth/reset-password/resolve-token`
7. `POST /auth/reset-password`
8. `GET /auth/reset-password-page`
9. `GET /auth/reset-password-bridge`

### 5.4 Profile and Vehicles

1. `PUT /profile/update`
2. `POST /vehicles/add`
3. `GET /vehicles/my`
4. `PUT /vehicles/{vehicle_id}`
5. `DELETE /vehicles/{vehicle_id}`
6. `POST /vehicles/verify`

### 5.5 Notifications

1. `POST /notifications/fcm-token`
2. `GET /notifications/my`

### 5.6 Inference and Model Runtime

1. `POST /predict`
2. `POST /model/infer`

### 5.7 Parking/Events/History

1. `GET /parking/locations`
2. `GET /parking/occupancy`
3. `GET /events/entered-cars`
4. `GET /events/leaving-cars-within-5-minutes`
5. `GET /events/new-cars`
6. `GET /events/left-cars`
7. `GET /events/inside-cars`
8. `GET /parking/history`

### 5.8 Payments and Gate

1. `POST /payments/paymob/create`
2. `POST /payments/paymob/webhook`
3. `POST /payments/manual/cash-confirm`
4. `POST /gate/decision`

### 5.9 Maintenance

1. `POST /admin/maintenance/weekly-refresh`

---

## 6) End-to-End Data Flow

## 6.1 Predict Request Flow (`POST /predict`)

1. Authenticate request (Supabase token or barrier token).
2. Validate optional inputs:
   - `event_type` in `{entry, exit, ocr_scan}`
   - `parking_location` pattern
   - `camera_source` pattern
3. Run inference pipeline (local or remote).
4. Build normalized plate payload.
5. Persist output to Supabase:
   - upload raw and processed images to storage buckets
   - resolve vehicle from OCR plate
   - resolve/create session depending on event type
   - create `car_events` row
   - optionally emit notification events
6. Compute and return:
   - `payment_status`
   - `pricing`
   - `gate_decision`
   - persistence metadata

## 6.2 Vehicle Resolution Logic

The backend now matches OCR plates using both formats:

1. Arabic plate fields: `plate_letters_ar + plate_numbers_ar`
2. English plate fields: `plate_letters_en + plate_numbers_en`

Matching order:

1. Owner-scoped lookup (when authenticated Supabase user id is available)
2. Global lookup fallback

Effect:

- Reduces false negatives where OCR returns one language format but not the other.

## 6.3 Session Lifecycle

1. `entry`
   - create or reuse open session
2. `exit`
   - use open session
   - if paid and within 5 minutes: close session (`status=exited`)
   - if paid but grace expired: keep open with `status=overstayed`
   - if unpaid: keep open (gate deny path)
3. `ocr_scan`
   - read context only, no session state transition

## 6.4 Unmatched Fallback Flow

When a plate is detected but not linked to a registered vehicle/session:

1. Event is still stored in `car_events` (with nullable `vehicle_id`/`session_id`).
2. Backend builds inferred unmatched rows from entry/exit event streams by plate key.
3. Inferred rows are merged into:
   - `GET /parking/locations`
   - `GET /parking/occupancy`
   - `GET /events/inside-cars`
   - `GET /parking/history`

Response markers for inferred rows:

1. `inferred_unmatched=true`
2. `plate` object (key/arabic/english)
3. `event_count`

Occupancy responses also include source breakdown:

1. `inside_from_registered_sessions`
2. `inside_from_inferred_unmatched`

---

## 7) Database Model (Supabase)

Core relational tables:

1. `profiles`
   - user identity/profile metadata
   - role and staff metadata
2. `vehicles`
   - vehicle registration and ownership
3. `parking_sessions`
   - parking lifecycle state
4. `car_events`
   - entry/exit/scan event stream
5. `payment_transactions`
   - payment ledger for paymob/manual cash

Notifications and app links:

1. `notification_device_tokens`
2. `notification_events`
3. `app_links`

### Key Relationships

1. `profiles.id` -> `auth.users.id`
2. `vehicles.owner_id` -> `profiles.id`
3. `parking_sessions.vehicle_id` -> `vehicles.id`
4. `car_events.session_id` -> `parking_sessions.id` (nullable)
5. `car_events.vehicle_id` -> `vehicles.id` (nullable)

### Storage Buckets

1. `SUPABASE_RAW_BUCKET` (raw uploads)
2. `SUPABASE_PROCESSED_BUCKET` (split/admin images)

---

## 8) Security and Data Integrity

### 8.1 RLS and Role Design

- Supabase RLS is enabled for core business tables.
- Backend writes are performed via service role credentials.
- Client-facing authorization is enforced in API layer by user role/scope.

### 8.2 Notification Event Hardening

Current model:

1. Notification content is server-owned.
2. Authenticated users can read own notifications.
3. Authenticated users can only mark own notifications as read.
4. Client-side insert/delete/content edits are blocked.

### 8.3 Created-By FK Protection

For persistence writes:

- `created_by` is now populated only for Supabase-authenticated users.
- Barrier-auth requests do not inject synthetic ids into FK-backed columns.

This prevents FK violations and silent persistence drop scenarios.

---

## 9) Validation and Error Contract

Common input validations:

1. Auth header format (`Bearer ...`)
2. `event_type` allowed values
3. parking location format
4. camera source format
5. file type and non-empty uploads
6. payment amount positive integer rules

Common error statuses:

1. `400` invalid input
2. `401` auth missing/invalid/expired
3. `403` role or scope violation
4. `404` missing session/resource
5. `502` upstream integration failure
6. `503` missing critical configuration

---

## 10) Production Readiness Checklist

## 10.1 Required Environment

1. `SUPABASE_URL`
2. `SUPABASE_ANON_KEY`
3. `SUPABASE_SERVICE_ROLE_KEY`
4. `SUPABASE_ENFORCE_AUTH=true` (recommended)
5. model runtime config (`MODEL_INFERENCE_PROVIDER` + remote/local settings)

Optional but recommended:

1. `PASSWORD_RESET_REDIRECT_URL`
2. `BARRIER_API_TOKEN` or `BARRIER_API_TOKENS` (if device auth is needed)
3. pricing/capacity config
4. paymob config if card payments enabled

## 10.2 Database Migration Baseline

Ensure latest SQL is applied, including:

1. `supabase/04_auth_profile_vehicle_upgrade.sql`
2. `supabase/05_multi_vehicle_auth_notifications.sql`
3. `supabase/06_profile_name_parts_upgrade.sql`

## 10.3 Smoke Tests

1. `GET /health`
2. `GET /supabase/health`
3. Auth login/register flow
4. `POST /predict` (entry + exit)
5. `GET /parking/locations`
6. `GET /events/inside-cars`
7. `GET /parking/history`
8. Gate decision endpoint
9. Password reset flow (bridge + page + resolver)

## 10.4 Operational Guardrails

1. Rotate service secrets and barrier tokens regularly.
2. Keep `SUPABASE_SERVICE_ROLE_KEY` backend-only.
3. Monitor `response.supabase.saved` from `/predict` integrations.
4. Alert on repeated `saved=false` responses and 5xx spikes.

---

## 11) Troubleshooting Guide

### Symptom: feeds/history are empty

Checks:

1. Confirm requests are authenticated and role scope is correct.
2. Verify `/predict` responses include `supabase.saved=true`.
3. Verify vehicle resolution fields (Arabic/English plate matching).
4. Confirm sessions are being created (`parking_sessions`) and linked to events.
5. If traffic is mostly unregistered, verify inferred rows are visible (`inferred_unmatched=true`).

### Symptom: barrier token rejected

Checks:

1. Token present as Bearer token
2. `BARRIER_API_TOKEN` or `BARRIER_API_TOKENS` set in deployment env
3. No hidden whitespace in configured token

### Symptom: auth user exists but no data persists

Checks:

1. Confirm `profiles` row exists for that auth user id.
2. Confirm Supabase service role key is valid and backend can write tables.
3. Inspect backend logs for persistence exceptions.

---

## 12) Notes on Backward Compatibility

1. Existing Supabase auth clients continue to work unchanged.
2. Barrier token support is additive.
3. Feed/history response shape is preserved.
   - Added optional inferred markers and source-breakdown fields.
4. Role checks remain strict for maintenance and payment confirmation endpoints.

---

## 13) Recommended Next Improvements

1. Add structured audit logs for auth path used (`supabase` vs `barrier`).
2. Add metrics counters for vehicle-match source (`arabic`, `english`, fallback).
3. Add integration tests for:
   - missing-profile auto-provision
   - barrier gate decision authorization
   - plate matching variants (Arabic-only, English-only, mixed)
4. Add a migration to introduce an explicit persistent `barrier` app role if database-level modeling is desired.