# Bharat Seva — System Flows & API Walkthrough

Welcome to the **Bharat Seva** flow documentation. This directory provides an end-to-end blueprint of the platform's core functional paths, backend API endpoints, database interactions, and system components. 

Bharat Seva operates as an on-demand service marketplace, connecting **Customers** in need of home services (plumbing, repair, electrical, etc.) with verified **Vendors**.

---

## Document Index

Please click on the links below to view the comprehensive flow documentation for each system domain:

### 1. 🔑 [Customer Onboarding Flow](file:///d:/WHIZZACT/bharatseva_backend/docs/customer_onboarding_flow.md)
*Documents customer authentication, registration, phone verification, and session setup.*
* **Primary Endpoints**: `/v1/auth/customer/register`, `/v1/auth/customer/verify-otp`, `/v1/auth/customer/resend-otp`
* **Key Entities**: [User](file:///d:/WHIZZACT/bharatseva_backend/app/Models/User.php) (with role alias `CUST`)

### 2. 🏪 [Vendor Registration & Business Onboarding Flow](file:///d:/WHIZZACT/bharatseva_backend/docs/vendor_registration_flow.md)
*Documents vendor account creation and the 6-step business onboarding wizard.*
* **Onboarding Steps**:
  1. Business Registration (`POST /v1/vendor/business/register` — Profile 10%)
  2. Shop Details & Logo/Banner (`POST /v1/vendor/business/details` — Profile 30%)
  3. Operating Hours (`POST /v1/vendor/business/operating-hours` — Profile 50%)
  4. Serviceable Regions (`POST /v1/vendor/business/serviceable-regions` — Profile 70%)
  5. Social Links (`POST /v1/vendor/business/social-links` — Profile 85%)
  6. Government ID Uploads (`POST /v1/vendor/business/government-id-registration` — Profile 100%)
* **Key Entities**: [VendorBusiness](file:///d:/WHIZZACT/bharatseva_backend/app/Models/VendorBusiness/VendorBusiness.php), [VendorBusinessDetail](file:///d:/WHIZZACT/bharatseva_backend/app/Models/VendorBusiness/VendorBusinessDetail.php), [VendorOperatingHour](file:///d:/WHIZZACT/bharatseva_backend/app/Models/VendorBusiness/VendorOperatingHour.php), [VendorServiceableRegion](file:///d:/WHIZZACT/bharatseva_backend/app/Models/VendorBusiness/VendorServiceableRegion.php), [VendorSocialLink](file:///d:/WHIZZACT/bharatseva_backend/app/Models/VendorBusiness/VendorSocialLink.php)

### 3. 🛡️ [Vendor KYC & Verification Flow](file:///d:/WHIZZACT/bharatseva_backend/docs/vendor_verification_flow.md)
*Documents vendor status tracking, tiered KYC rules (Tiers 1 to 4), and the administrative/volunteer verification flow.*
* **Verification Targets**: Government IDs, Business Registrations, and Staff Details/Documents
* **Key Entities**: [VendorGovernmentId](file:///d:/WHIZZACT/bharatseva_backend/app/Models/VendorBusiness/VendorGovernmentId.php), [VendorBusinessRegistration](file:///d:/WHIZZACT/bharatseva_backend/app/Models/VendorBusiness/VendorBusinessRegistration.php), [BusinessStaffDocument](file:///d:/WHIZZACT/bharatseva_backend/app/Models/VendorBusiness/BusinessStaffDocument.php)

### 4. ⚙️ [Functional Flow of the Entire Project](file:///d:/WHIZZACT/bharatseva_backend/docs/functional_flow.md)
*Documents the transactional core of the platform: discovery, catalog, direct booking, and broadcast bidding (RFQ).*
* **Core Flows**:
  * **Flow A (Direct Booking)**: Customer books a specific vendor directly.
  * **Flow B (Broadcast RFQ)**: Customer requests quotes; vendors bid; customer selects vendor; vendor inspects & quotes; customer accepts; work starts via secure OTP verification.
* **Secondary Features**: Product catalog management, staff allocation, QR code scans, emblems, and reviews.
* **Key Entities**: [Lead](file:///d:/WHIZZACT/bharatseva_backend/app/Models/Lead.php), [LeadQuotation](file:///d:/WHIZZACT/bharatseva_backend/app/Models/LeadQuotation.php), [LeadVendor](file:///d:/WHIZZACT/bharatseva_backend/app/Models/LeadVendor.php), [ProductDetail](file:///d:/WHIZZACT/bharatseva_backend/app/Models/VendorBusiness/ProductDetails/ProductDetail.php)

---

## Architecture Diagram

The diagram below illustrates how these flows interface across the client applications, the backend API gateway, and the database/service layers.

```mermaid
graph TD
    Client[Client App: Mobile/Web] -->|API Gateway| Auth[v1/auth Route Group]
    Client -->|Protected| Vend[v1/vendor Protected Group]
    Client -->|Protected| Cust[v1/customer Protected Group]
    Client -->|Admin Web| Admin[web.php Admin Group]

    subgraph Authentication & Onboarding Flows
        Auth -->|Onboard Customer| CustomerFlow[Customer Onboarding Flow]
        Auth -->|Register Account| VendorReg[Vendor Registration Flow]
        Vend -->|6-Step Profile Wizard| VendorReg
    end

    subgraph Trust & Quality Assurance
        Admin -->|Verify Documents & Assign Volunteers| KYC[Vendor KYC & Verification Flow]
    end

    subgraph Service Execution Flows
        Cust -->|Discover & Book| Txn[Functional Flows: Direct Book / RFQ]
        Vend -->|Bidding & Quote Submission| Txn
    end

    CustomerFlow --> DB[(MySQL Database)]
    VendorReg --> DB
    KYC --> DB
    Txn --> DB
```
