Apis DOCS/FULL_API_DOCUMENTATION.md

# Ain El Aql - Full System Architecture & API Documentation

This document serves as the ultimate reference for the Ain El Aql backend, covering everything from the database model to all endpoints, and specifically detailing the **Role-Based Access Control (RBAC)** that governs the User, Admin, and Security roles.

---

## 1. Role-Based Access Control (RBAC)

The backend uses a single set of APIs whose behavior changes dynamically based on the authenticated user's role.

### Roles
1. **`user`**: Regular customers. They can only see their own registered vehicles, notifications, and parking history.
2. **`admin` & `security` (Staff)**: Privileged roles that unlock **God View**. When a staff member calls an endpoint like `/events/entered-cars`, they bypass the user filter and see **all cars** in the entire facility. They also gain access to manual override endpoints like `/payments/manual/cash-confirm`.
3. **`barrier`**: A synthetic machine role intended for the camera/gate systems. They authenticate using a static `BARRIER_API_TOKEN` to run OCR scans and query gate decisions without needing a user account.
4. **`developer`**: Has access to backend debugging endpoints.

---

## 2. Database Model (Supabase)

The relational data is stored in PostgreSQL via Supabase.

### Core Tables
*   **`profiles`**: Links to `auth.users.id`. Stores user identity (`first_name`, `email`, `phone_number`, `national_id`), as well as their `role` (e.g., user, admin).
*   **`vehicles`**: Links to `profiles.id` (`owner_id`). Stores the registration data (Arabic/English plates, car make, color, verification status).
*   **`parking_sessions`**: Tracks the lifecycle of a car parking. Links to `vehicles.id`. A session starts on `entry` and closes on `exit`.
*   **`car_events`**: The immutable ledger of everything that happens. Every entry, exit, or OCR scan creates a row here.
*   **`payment_transactions`**: The ledger for payments, linking Paymob callbacks or Manual Cash confirmations to a parking session.
*   **`notification_device_tokens` & `notification_events`**: Handles FCM (Firebase) push notifications.

### Storage Buckets
*   `car-raw-images`: Stores the full uncropped images from the CCTV cameras.
*   `car-processed-images`: Stores cropped plates and annotated UI images.

---

## 3. Comprehensive API Endpoints Catalog

### 🏠 Public & Utility
*   `GET /` - Base API check.
*   `GET /health` - API health check.
*   `GET /supabase/health` - Checks database connectivity.

### 🔐 Authentication (`/auth`)
*   `POST /auth/register` - Creates a new user in Supabase Auth.
*   `POST /auth/login` - Returns a JWT. If the user is staff, `"is_staff": true` is injected into the response.
*   `POST /auth/otp/request` - Requests an OTP (Email/Phone).
*   `POST /auth/otp/verify` - Verifies an OTP.
*   `POST /auth/forgot-password` - Triggers the Supabase password reset email.
*   `POST /auth/reset-password/resolve-token` - Validates the reset token.
*   `POST /auth/reset-password` - Sets the new password.
*   `GET /auth/reset-password-page` - Web UI fallback for password resets.
*   `GET /auth/reset-password-bridge` - Mobile deep link bridge.

### 👤 Profile & Vehicles (`/profile`, `/vehicles`)
*   `PUT /profile/update` - Modifies `profiles` table data.
*   `POST /vehicles/add` - Registers a new vehicle to the user.
*   `GET /vehicles/my` - Lists the authenticated user's vehicles.
*   `PUT /vehicles/{vehicle_id}` - Edits a vehicle's details.
*   `DELETE /vehicles/{vehicle_id}` - Unlinks a vehicle.
*   `POST /vehicles/verify` - Submits a vehicle for administrative verification.

### 🔔 Notifications (`/notifications`)
*   `POST /notifications/fcm-token` - Registers a mobile device token.
*   `GET /notifications/my` - Retrieves the user's unread/read notifications.

### 🤖 AI Models & Inference Core
*   `GET /models` - Lists available YOLO models.
*   `GET /developer/models` - Internal diagnostic for models.
*   `POST /predict` - **The core pipeline endpoint.** Receives an image, runs YOLO car detection -> YOLO plate detection -> OCR. Records the event in Supabase and returns the gate decision and pricing.
*   `POST /model/infer` - Executed by the Hugging Face space when running in remote inference mode.
*   `POST /developer/predict` - Testing endpoint for developers.

### 🅿️ Parking, Events, and History
*(Note: All endpoints below return "Own Data" for Users, and "Global Data" for Admin/Security)*
*   `GET /parking/locations` - Returns garage capacities, pricing rules, and current overall occupancy.
*   `GET /parking/occupancy` - Returns pure occupancy counts.
*   `GET /events/entered-cars` - Feed of cars that have successfully entered.
*   `GET /events/leaving-cars-within-5-minutes` - Feed of cars currently in their exit grace period.
*   `GET /events/left-cars` - Feed of closed sessions.
*   `GET /events/inside-cars` - Live view of all cars physically inside the garage right now.
*   `GET /parking/history` - The permanent ledger of all past parking sessions.

### 💳 Payments & Gate Control
*   `POST /payments/paymob/create` - Generates a Paymob iframe URL for credit card checkout.
*   `POST /payments/paymob/webhook` - Secure listener for Paymob status updates.
*   `POST /gate/decision` - Calculates if a specific car is allowed to exit right now based on its payment status.

### 🛡️ Exclusive Admin / Security Endpoints
*(Restricted entirely to the `admin` and `security` roles)*
*   `GET /events/new-cars` - Real-time polling feed of cars directly at the camera right now.
*   `POST /payments/manual/cash-confirm` - Allows a guard to confirm they received cash, bypassing the credit card flow and opening the gate.
*   `POST /admin/maintenance/weekly-refresh` - System cleanup script.

---

## 4. End-to-End Flow Example: The `/predict` Pipeline

When a camera sends an image to `POST /predict`:
1. **Auth:** Checked against `BARRIER_API_TOKEN` or a user JWT.
2. **AI Inference:** The image is passed through 3 AI models (Car -> Plate -> OCR).
3. **Matching Logic:** The detected plate string is normalized and searched in the `vehicles` table (matching both Arabic and English variants).
4. **Session Logic:** 
   * If `event_type=entry`, a new `parking_sessions` row is created.
   * If `event_type=exit`, the pricing engine calculates the fee.
5. **Persistence:** Images are uploaded to Supabase Storage, and the `car_events` ledger is updated.
6. **Response:** Flutter receives a massive JSON containing the plate text, pricing breakdown, and `gate_decision.allowed = true/false`.