================================================================================ BHARAT SEVA BACKEND — FLOWCHART COMPARISON & GAP ANALYSIS ================================================================================ This document provides a detailed comparison between the 5 flowchart workflows provided and the current state of implementation in the codebase (located at d:\WHIZZACT\bharatseva_backend). It also details the technical requirements needed to fully implement the remaining or partially implemented flows. -------------------------------------------------------------------------------- 1. COMPREHENSIVE STATUS SUMMARY OF FLOWCHARTS -------------------------------------------------------------------------------- +-------------------------------------------------------------+----------------+ | Flowchart Name | Status | +-------------------------------------------------------------+----------------+ | 1. Vendor Registration & Code Creation | PARTIAL | | 2. Customer Code Creation | MOSTLY MISSING | | 3. Customer Order to Service Provider | PARTIAL | | 4. Customer Order (Shop) | MOSTLY MISSING | | 5. Customer Order (Small Vendor / Hawker / Street Food) | MOSTLY MISSING | +-------------------------------------------------------------+----------------+ --- -------------------------------------------------------------------------------- 2. DETAILED FLOWCHART COMPARISON -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- FLOWCHART 1: Executive Workflow – Vendor Registration & Code Creation -------------------------------------------------------------------------------- * FLOW DESCRIPTION: Establishes a vendor user role, profile wizard completion, assigning volunteers, verifying KYC details, and creating a unique vendor code. ● IMPLEMENTED IN CODEBASE: - Account Registration: Managed via `POST /api/v1/auth/vendor/register` (registers name, phone, email, password, and consents). - 6-Step Onboarding Wizard: Completed via `POST /api/v1/vendor/business/...` routes (collects basic details, logo/banner, operating hours, serviceable regions, social profiles, and government IDs). - Volunteer Assignment: Route `POST /assign-volunteer` maps a volunteer to a vendor business. - Document Verification: Routes like `/verify-government-registration/{id}` and `/verify-registration/{id}` allow volunteers/admins to approve or reject KYC. - Admin Approval: Admin can mark the overall verification status as approved. - Vendor Code Created: The `vendor_businesses` table has a `unique_code` field. ● NOT IMPLEMENTED / GAPS: - Volunteer sends one-time registration link: No automatic SMS/WhatsApp/Email dispatch is integrated inside the Admin panel (e.g. `ReferralController`). The volunteer must copy the link manually from the dashboard and send it. ( don't implement this ) - Vendor selects language: There is no language selector/locale attribute in the registration payload or user/business schemas. - Vendor Code creation trigger: The `unique_code` is generated during Emblem generation (`POST /api/v1/vendor/generate-emblem/{businessId}`), rather than automatically upon final Admin approval. - Send Link/Code with PDF: There is no PDF compiler (e.g., laravel-dompdf) or message dispatcher (Email, SMS, WhatsApp, Arattai) integrated to send the registration confirmation PDF to the vendor. -------------------------------------------------------------------------------- FLOWCHART 2: Executive Workflow – Customer Code Creation -------------------------------------------------------------------------------- * FLOW DESCRIPTION: Distributes a download link, processes customer registration with extensive fields (Aadhaar, Family, etc.), performs admin Aadhaar verification, creates a customer code, and activates the account. ● IMPLEMENTED IN CODEBASE: - App Access & Registration: Customers register with Name, Email, Phone via `POST /api/v1/auth/customer/register`. - OTP Verification: Verifies phone via 6-digit OTP code (`CustomerVerifyOtp`), which sets the `phone_verified_at` timestamp. - Activation: Account `is_active` defaults to 1. ● NOT IMPLEMENTED / GAPS: - Send WhatsApp with Play Store/App Store link: No automated download link sender is built. ( don't implement) - Extended Fields: The database schema and controller validate only Name, Email, and Phone. Fields for Address, PIN, Aadhaar, Family Members, and Reference Source are completely missing on the customer user profile. - Upload Aadhaar/Masked Aadhaar: The customer side lacks any file upload/KYC submission tables, models, or API endpoints. ( don't implement) - Admin Aadhaar Verification: No admin page or government database integration exists for checking customer Aadhaar validity. ( don't implement) - Create Customer Code: No unique customer code is generated or stored.When user register generate a unique_code - Approval Cycle: Customers bypass any admin screening or approval, becoming active immediately upon OTP verification. ( don't implement) -------------------------------------------------------------------------------- FLOWCHART 3: Workflow Chart – Customer Order to Service Provider -------------------------------------------------------------------------------- * FLOW DESCRIPTION: A customer books a service provider directly or broadcasts a request to all within 10 km, select/assigned vendor visits, submits quotation, customer accepts, vendor starts work via OTP, completes, and feedback is recorded. ● IMPLEMENTED IN CODEBASE: - Booking Enquiry with GPS: Customer latitude & longitude coordinates are stored. - Radius Search: Finds active vendors within 10 km (`$radius = 10;`) using Haversine formula. - Direct Booking: Creates lead with `is_direct = true` targeting a `vendor_id`. - Broadcast Booking: Creates lead with `is_direct = false` and alerts all nearby vendors. Bidding is recorded in `lead_vendors`. - Vendor Choose & Notify: `chooseVendorV2` assigns the selected bidder and rejects other vendors. - Vendor Quotation: `POST /api/v2/vendor/leads/{leadId}/quotation` records price, schedule time, and description, setting lead to `quotation_pending`. - Quotation Response: `POST /api/v2/customer/bookings/{leadId}/quotation/respond` generates a 4-digit `start_otp` upon acceptance. - Work Execution: Vendor calls `/lead/start/{id}` (verifying OTP) and `/lead/complete/{id}`. - Review & Feedback: Customer submits ratings via `submitReview`. ● NOT IMPLEMENTED / GAPS: - Previous vendor reuse: The matching algorithm in `createBookingV2` does not check the customer's transaction history to automatically reuse previous vendors. - In-App Call/Chat: There are no integrated VoIP or real-time messaging services (only phone numbers are provided for offline dialing/whatsapp redirection). - Schedule Visit & Customer Confirms Visit: There are no independent status states or APIs for a customer to verify a scheduled visit *before* the work quotation is raised. - Vendor visits tracking: No GPS check-in or visit confirmation state in the lead lifecycle. -------------------------------------------------------------------------------- FLOWCHART 4: Executive Workflow – Customer Order (Shop) -------------------------------------------------------------------------------- * FLOW DESCRIPTION: Directs customers to shops within 10 km / 2 km based on order type selection, allows dialing, scanning shop emblem upon arrival, entering a purchase amount, and finalizing transaction feedback. ● IMPLEMENTED IN CODEBASE: - Geolocation Discovery: Customer coordinates are collected. - Search & Display: Nearby vendor listing returns locations and phone numbers. - Scan Emblem: The `QrController@verifyBusiness` endpoint verifies QR codes and checks vendor validation badges. ● NOT IMPLEMENTED / GAPS: - Order Type "Shop": There is no option/logic in the backend schema distinguishing a "Shop" booking/order from a service provider lead. - Previous Purchase Check: No verification of past purchases to reuse vendor. - Selected Area 2 km Radius: The search radius remains hardcoded to 10 km for all customer discovery query pathways. - Visit Shop & Scan Emblem Transaction: Scanning QR verifies business status but does not initiate a purchase transaction or log shop visit status. - Enter Purchase Amount: No payment gateways or numeric purchase amount logging exist. - Purchase Confirmation & Feedback: No separate closure state for shop purchases. -------------------------------------------------------------------------------- FLOWCHART 5: Executive Workflow – Customer Order (Small Vendor / Hawker / Street Food) -------------------------------------------------------------------------------- * FLOW DESCRIPTION: Directs customers to small hawkers/street vendors within a 2 km radius, allows scanning emblem, entering a purchase amount, and providing feedback. ● IMPLEMENTED IN CODEBASE: - Discovery: Geolocation and vendor directory fetch. - QR Code scanning: Basic business verification via `verifyBusiness/{code}`. ● NOT IMPLEMENTED / GAPS: - Hawker Selection / Order Type: "Street Hawkers" only exists as a category name in DB seeders, not as a functional workflow model in bookings. - Hawker Radius Filter: Search does not default to 2 km for hawker category queries. - Previous Vendor Check: No lookup of previous hawker bookings. - Reach Vendor & Scan Emblem Transaction: Scans only verify badges, without initiating transaction states. - Enter Purchase Amount / Payment: No purchase input or cash/digital payment logging. - Confirm Purchase & Feedback: Missing closure flow. --- -------------------------------------------------------------------------------- 3. TECHNICAL REQUIREMENTS TO ACHIEVE REMAINING FLOWS -------------------------------------------------------------------------------- To achieve 100% compliance with all five flowcharts, the following backend changes must be implemented: A. COMMUNICATION & DELIVERY INTEGRATIONS: 1. SMS / WhatsApp APIs: Implement a notification dispatch service using a provider like MSG91 or Twilio to automate: - Sending the one-time registration link to vendors. - Sending the app download link via WhatsApp to customers. - Sending the registration summary PDF to vendors on approval. 2. PDF Generator: Install a Laravel PDF library (e.g., `barryvdh/laravel-dompdf`) to assemble and export the vendor's registration summary. B. DATABASE SCHEMA EXPANSIONS: 1. Vendor Language Settings: Add `language_code` or `locale` to `users` and `vendor_businesses` tables. 2. Customer KYC & Profile details: Add columns to the `users` table or create a `customer_profiles` table to store: - Aadhaar number (encrypted). - PIN, Address. - Family Members count/details. - Reference Source. - Unique Customer Code. 3. Customer Documents: Create a `customer_documents` table to manage customer Aadhaar document uploads. 4. Order Types & Radius: Add `order_type` (Enum: 'service', 'shop', 'hawker') to the `leads` table to differentiate order pathways. C. API ENDPOINTS & FLOW WORKFLOWS: 1. Language preference API: Build endpoints for registering and updating language selection during onboarding. 2. Customer document upload API: Build endpoints for uploading Aadhaar/masked Aadhaar and submitting profiles for verification. 3. Admin Customer Verification Panel: Create controllers and views to list pending customer registrations, check customer Aadhaar, and activate accounts. 4. Dynamic Search Radius: Update `createBookingV2` and `nearby` endpoints to accept a dynamic radius parameter, defaulting to: - 10 km for Service Providers. - 2 km for Shops and Hawkers. 5. Previous Vendor Lookup: Add a query layer in booking services that looks up the client's previous successful bookings and prioritizes those vendors. 6. In-App Call/Chat: Integrate a WebRTC or third-party chatting engine (e.g., Pusher) and voice dialer. 7. Visit Scheduling API: Add explicit `POST /leads/{id}/schedule-visit` and `POST /bookings/{id}/confirm-visit` endpoints. 8. Purchase & Scan Transaction System: - Create an `orders` or `purchases` table mapping scanning transactions. - Build a `POST /api/v1/customer/purchase` endpoint allowing customers to submit purchase amounts (and trigger payments) after scanning a QR/Emblem. - Hook up reviews and ratings to this specific purchase record. ================================================================================