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.