# Gaga Backend Systems Report

This document provides a comprehensive analysis of the internal systems, architectural components, and APIs of the **GAGA Backend** project.

---

## 1. Project Overview
The Gaga Backend is a specialized API-driven platform for on-demand marketplace services (likely food or general delivery). It is built using the **Laravel Framework**, favoring a **Service-Oriented Architecture (SOA)** to handle complex logistics and multi-tenant store management.

### Tech Stack
*   **Framework:** Laravel
*   **Database:** PostgreSQL/MySQL (implied by typical Laravel usage)
*   **Authentication:** Laravel Sanctum (Token-based)
*   **Admin Panel:** Filament PHP (TALL stack-based)
*   **Real-time:** Firebase Cloud Messaging (FCM) & potentially Webhooks
*   **Geospatial:** Google Maps API integration

---

## 2. Core Backend Systems

### A. Authentication & Identity System
A unified yet segregated authentication system supporting three distinct user profiles:
*   **Customer Auth:** OTP-based registration and login via mobile. Includes profile completion and persistent sessions.
*   **Provider Auth:** Specifically for **Drivers** and **Store Owners**, using OTP for security.
*   **Dashboard/Admin Auth:** Email/Password based login for platform administrators.
*   **Security:** Rate limiting (throttling) on OTP endpoints and device registration for push security.

### B. Catalog & Store Management System
Manages the complexity of a multi-tenant marketplace:
1.  **Store Hierarchy:** Store Categories -> Individual Stores -> Branches.
2.  **Rich Menu System:**
    *   **Menus & Categories:** Logical grouping of items.
    *   **Product Management:** Core item details.
    *   **Product Options & Supplements:** Allows for deep customization (e.g., "Add extra cheese", "Size: Large").
3.  **Analytics:** Integrated product analytics for store owners to track performance.

### C. Logistics & Dispatch Engine ("The Engine")
The core proprietary logic of the platform, located primarily in `app/Services/Dispatch`:
*   **Dispatch Orchestrator:** Manages the lifecycle of an order's assignment.
*   **Driver Search System:** Real-time search for available drivers based on proximity and status.
*   **Geo-Location Logic:** Uses `GeoLocationService` and `GoogleDistanceService` to calculate travel times (ETA) and distances.
*   **Dispatcher Service:** Automated assignment logic that matches orders to drivers.
*   **Real-time Tracking:** Endpoints for streaming driver location and order status timeline.

### D. Order Lifecycle & Status System
Manages the transition of orders across multiple states using specialized Enums:
*   **Order Store Status:** Tracking if the shop has received/prepared the order.
*   **Order Driver Status:** Tracking if the driver has picked up/delivered the order.
*   **Order Dispatch Status:** Internal state of the assignment process (Pending, Assigned, etc.).
*   **Timeline:** A dedicated status timeline for customers to track progress.

### E. Financial & Wallet System
Handles internal accounting and payments:
*   **Store Wallets:** Each store has an internal balance.
*   **Ledger System:** `StoreWalletTransaction` tracks every cent (Earnings, Withdrawals, Fees).
*   **Global Transitions:** Generic `Transaction` and `Payment` models for customer-side billing.

### F. Notification & Communication System
Keeps the ecosystem connected:
*   **Fcm Service:** Integration with Firebase for mobile push notifications.
*   **Multi-Device Handling:** Tracks individual user devices (`Device` model) to ensure notifications reach the right hardware.
*   **Notification Feed:** In-app notification center for users to review past alerts.

### G. Search & Discovery System
*   **SearchGlobalService:** Unified search across products, stores, and categories.
*   **Location-Aware Filtering:** Filters results based on the customer's delivery radius.

---

## 3. API Architecture Analysis

The API is strictly versioned (`v1`) and organized into logical groups:

| Prefix | Targeted User | Key Functionality |
| :--- | :--- | :--- |
| `/v1/auth` | All | Login, OTP, Profile management |
| `/v1/customer` | Consumers | Browsing Stores, Ordering, Reviews, Payments |
| `/v1/driver` | Delivery Agents | Shift management, Dispatch acceptance, Pickup/Delivery |
| `/v1/store` | Shop Owners | Menu/Offer management, Wallet tracking, Analytics |
| `/v1/global` | Public/All | Categories, Ads, City lists |
| `/v1/dispatch` | System/Admin | Manual order assignment, Logistics overrides |

---

## 4. Key Architectural Patterns
*   **Services Layer:** Business logic is pulled out of Controllers and placed into `app/Services` (e.g., `OrderDispatchService`, `FcmService`).
*   **Observers:** `StoreObserver` handles automatic actions when a Store record is updated (e.g., clearing cache or notifying admins).
*   **Enums:** State management is strictly controlled via PHP 8.1+ Enums in `app/Enums`.
*   **Helpers:** Custom global functions in `app/Helpers` for cross-cutting concerns (likely formatting/distance).

---

## 5. Critical System Files
*   `routes/api.php`: The map of the entire backend.
*   `app/Services/Dispatch/DispatchOrchestrator.php`: The logic for finding drivers.
*   `app/Models/Order.php`: The central data entity of the platform.
*   `app/Http/Controllers/V1/OrderDispatchController.php`: Entry point for logistic operations.

---
*Report Generated: April 17, 2026*