Project Concept & Value Proposition

This platform implements a dual-sided subscription monetization model designed to build a high-quality, spam-free local service directory. Rather than taking transactional commissions, the platform charges service providers a membership fee to activate their visibility and listings, and charges customers a subscription fee to unlock booking and chat functionalities.

With automated location-based matching (GEO), the system ensures that service searches are highly relevant to the user's city and local pincode, making it a perfect fit for hyperlocal operations in major metropolitan areas globally.

👥 User Roles & Portals

1. 🙋‍♂️ Customer (User) Portal

Discover local talent: Browse and filter service listings by category (e.g., Cleaning, Plumbing, Electrical Repair) and current city.
Smart Search: Hyperlocal sorting based on city, state, pincode, or latitude/longitude coordinates.
Premium Engagement: Subscribe to the customer plan (₹399/year) to unlock real-time direct chat and instant booking mechanisms.
Reputation Engine: Leave verified ratings and reviews for services consumed to ensure community trust.

2. 🛠️ Service Provider Portal

Digital Storefront: Create a detailed profile showcasing bio, address, categories, and service photo galleries.
Dynamic Listing Control: Add services with pricing details. Services are stored as pending_payment and automatically hidden until subscription is active.
Subscription Gating: Pay a membership fee (₹499/year) to activate service visibility. Laravel webhooks handle immediate state transitions once payment is processed.
Lead Dashboard: Track active bookings, review scores, customer messages, and revenue statistics.

3. 👑 Central Administration Suite (Super Admin)

Real-time Metrics: High-level dashboard showing platform revenue, service distribution, subscriber growth, and provider onboarding funnels.
Resource Management: Full CRUD capabilities over users, providers, service listings, and media assets.
No-Code Dynamic Configs: Change app settings (e.g., SMTP details, Razorpay API credentials, support contact, and global subscription prices) directly from the UI. Config changes take effect immediately across web, backend, and mobile apps.

🛠️ Architecture & Technology Stack

graph TD
    A[Flutter Mobile App<br/>Android & iOS / Provider] 
-->|HTTPS REST APIs| C[Laravel 11 REST API<br/>Sanctum Auth / Sanctum Middleware]
    B[React JS Web App<br/>Vite / Tailwind CSS] -->|HTTPS REST APIs| C
    C -->|Database Queries| D[(MySQL / SQLite)]
    C -->|Dynamic Config| E[.env & Site Settings]
    C -->|Real-time Events| F[Pusher / WebSockets]
    A <-->|Direct Chat| F
    B <-->|Direct Chat| F

Backend (API Gateway & Database)

Framework: Laravel 11
Authentication: Laravel Sanctum (Secure token-based auth for mobile & stateful session protection for web)
Database: Robust schema mapping users, service details, localized categories, images, and payment-linked subscriptions.
Real-time Eventing: WebSockets via Pusher for instant messaging between clients.
Asset Storage: Laravel Local Storage or AWS S3 integration for optimized media delivery.

Frontend Web (React JS)

Build Tool: Vite (Ultra-fast development and optimized production builds)
Styling: Tailwind CSS (Modern, responsive grid layouts with light/dark modes)
State Management: React Context / Zustand for seamless user state orchestration.
Features: Admin revenue metrics dashboards, dynamic configuration forms, provider profile image cropping tools.

Mobile Application (Flutter)

Language: Dart (Native performance on both Android & iOS)
State Management: Provider / BLoC pattern for clean data flow.
Geolocator Integration: Automated fetching of user GPS coordinates to query nearby services.
Deep Linking: Dynamic linking support to guide users straight to service pages.

🔒 Automated Workflows & Payment Gating

Service Provider Visibility Lifecycle

Onboarding: Provider registers and inputs profile details.
Creation: Provider adds service listing with descriptions and images. The service status defaults to pending_payment.
Checkout: The provider is redirected to the payment gateway checkout page.
Activation Webhook: On successful payment callback, the webhook updates:
- service_providers.subscription_status ➡️ active
- services.status ➡️ active
Publish: The service instantly becomes visible under search indexes and city directories.

Dynamic Admin SMTP & Gateway Updates

Instead of modifying server files or restarting services, the Admin Panel features direct database-to-config mapping. When the administrator updates SMTP mail settings or Razorpay API keys, Laravel reads the updated database values and dynamically modifies the environment variables at runtime, preventing downtime and maintaining a continuous service stream.

⚙️ Quick Installation & Running Guide

Ensure you have PHP 8.2+, Composer, Node.js (v18+), and the Flutter SDK installed locally.

1. Backend API (Laravel 11)

cd backend
copy .env.example .env
# Create database file
New-Item -ItemType File -Path database\database.sqlite -Force
composer install
php artisan key:generate
php artisan migrate --seed
php artisan serve

API Host: http://127.0.0.1:8000
API Base URL: http://127.0.0.1:8000/api

2. Web Frontend (React + Vite)

cd frontend
npm install
npm run dev

Local Web URL: Usually http://localhost:5173
Note: To connect to local API, set baseURL: 'http://localhost:8000/api' in frontend/src/api/axios.js.

3. Mobile Client (Flutter)

cd mobile
flutter pub get
# List emulators and run
flutter emulators
flutter emulators --launch YOUR_EMULATOR_NAME
flutter run

Note: Set local backend URL in mobile/lib/src/core/api_client.dart (http://10.0.2.2:8000/api for Android Emulator or LAN IP for physical device).

🧪 Quality Assurance & Test Suites

Run Backend Tests: cd backend && php artisan test
Run Flutter Tests: cd mobile && flutter test
Run Web Linter: cd frontend && npm run lint

On-Demand Service Marketplace (Urban Company Clone)

Project Screenshots

Project Description