Apis DOCS/FLUTTER_INTEGRATION_GUIDE.md

# Flutter Integration Guide

## Goal

Connect Flutter app to Ain El Aql backend to produce a complete parking product:

1. camera-based ANPR detection
2. parking session and payment lifecycle
3. occupancy and location-aware pricing dashboards

## Responsibility Split

### Backend + AI team (already implemented)

1. AI inference pipeline
2. Session/event persistence in Supabase
3. Dynamic pricing and capacity logic
4. Gate decision logic
5. Payment endpoints (Paymob + manual cash)
6. Role-aware history/feed APIs

### Flutter team

1. Backend auth screens and token management
2. API client layer and request retries
3. UI for user/admin/security experiences
4. Detection screens and result rendering
5. Payment/gate operation UI flow
6. Dashboard and reporting screens

## Integration Steps

1. Configure API base URL in Flutter.
2. Register/Login through backend auth endpoints and keep access token.
3. Send token as `Authorization: Bearer ...` to protected endpoints.
4. Use `POST /predict` for main camera action.
5. Use `/parking/locations` and `/parking/occupancy` for location cards and dashboard.
6. Use feeds/history endpoints for timeline and operational views.

## Current Cloud Base URL

- `https://pant0x-ealpr-ocr.hf.space`

Sanity checks:

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

Current deployment mode is `SUPABASE_ENFORCE_AUTH=false` to unblock integration.
Before production launch, switch to `true` and ensure token headers are sent on protected calls.

## Recommended Flutter Screens

1. Auth (login/register/reset)
2. Home/scan screen
3. Detection result screen
4. Inside/entered/left monitoring screens
5. Parking history screen
6. Location pricing + occupancy screen
7. Payment and gate validation screen
8. Admin/security operations panel

## Request/Response Mapping

### `POST /auth/register`

Flutter sends:

1. `first_name` (recommended)
2. `last_name` (recommended)
3. `username` (required)
4. `phone` (required)
5. `password` (required)
6. `email` (optional)
7. `nid` (optional)
8. optional vehicle payload:
   - `plate_letters_ar`, `plate_numbers_ar`
   - `plate_letters_en`, `plate_numbers_en`
   - `car_model`, `car_color`

Flutter reads:

1. `user.role` and `user.is_staff`
2. `session.access_token`
3. `vehicle` (if provided during registration)

### `POST /auth/login`

Flutter sends:

1. `identifier` (username OR phone OR email OR nid)
2. `password`

Flutter reads:

1. `user.role` and `user.is_staff`
2. `session.access_token`
3. `session.refresh_token`

### `POST /predict`

Flutter sends:

1. image file
2. event_type (`entry`/`exit`/`ocr_scan`)
3. parking_location (named value like `OPERA`)

Flutter reads:

1. `plate_info` / `plate`
2. `pricing`
3. `payment_status`
4. `gate_decision`
5. `user_page.split_image_base64`
6. `admin_page.annotated_image_base64`

### Occupancy dashboards

Use:

1. `GET /parking/locations`
2. `GET /parking/occupancy`

Render:

1. `garage.display` (X/total)
2. each location pricing mode/rates
3. each location occupancy display and left capacity

## Role-based UI Recommendations

1. `user`
   - own history/feeds
   - pricing and availability
2. `admin`
   - all-user operations, analytics, payment controls
3. `security`
   - gate operations and live occupancy monitoring

Role source is backend `user.role` from the `profiles` table.

## End-to-End Product Pipeline

1. Driver arrives and selects location in app.
2. Camera scan sends image to `/predict` with `event_type=entry`.
3. Backend detects plate, creates/updates session, calculates pricing context.
4. Driver views status and fee preview.
5. On exit, app sends `/predict` with `event_type=exit`.
6. Backend validates payment state and returns gate decision.
7. Staff can use payment endpoints when required.
8. Dashboards reflect occupancy in near-real-time from open sessions.

## Launch Checklist

1. Cloud host `/`, `/health`, and `/supabase/health` pass.
2. Supabase tables/buckets configured and secure.
3. Auth enforced in production (`SUPABASE_ENFORCE_AUTH=true`).
4. Pricing/capacity env values loaded in deployment.
5. Flutter role routing and token flow tested.
6. Entry/exit/manual payment QA completed.
7. Security key rotation completed for exposed secrets.