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.