KooliHub is a comprehensive multi-vendor super app platform that enables businesses to manage and sell products across multiple service categories including groceries, electronics, fashion, handyman services, car rentals, and more. Built with modern web technologies and scalable architecture.
- Grocery & Food Delivery: Fresh produce, packaged goods, and quick commerce
- Electronics & Appliances: Consumer electronics, mobile devices, and accessories
- Fashion & Beauty: Clothing, cosmetics, and lifestyle products
- Handyman Services: On-demand home services and repairs
- Car Rental: Vehicle booking and rental management
- Trip Booking: Travel and transportation services
- Multi-vendor onboarding and management
- Vendor-specific product catalogs
- Service area management with geospatial support
- Dynamic pricing and inventory control
- Real-time vendor dashboard
- Comprehensive product management
- Vendor oversight and analytics
- Order processing and tracking
- Custom field management for different service types
- Dynamic attribute system for products
- Multi-language support with translations
- Real-time product search and filtering
- Shopping cart and wishlist
- Multiple payment options (Stripe, Razorpay)
- Location-based service discovery
- Push notifications via Firebase
- Order tracking and history
- Row Level Security (RLS) with Supabase
- Authentication with session management
- Optimized database queries with indexing
- Real-time data synchronization
- Responsive design with mobile-first approach
- Framework: React 18.3 with TypeScript
- Routing: React Router 6
- State Management: React Context + React Query
- UI Components: Radix UI + TailwindCSS 3
- Icons: Lucide React
- Forms: React Hook Form + Zod validation
- Maps: Leaflet + React Leaflet
- 3D Graphics: Three.js + React Three Fiber
- Animations: Framer Motion
- Server: Express.js 5
- Database: Supabase PostgreSQL
- Authentication: Supabase Auth
- File Storage: Supabase Storage + Multer
- Push Notifications: Firebase Cloud Messaging
- Payment Processing: Stripe & Razorpay
- Build Tool: Vite 7
- Package Manager: PNPM
- Testing: Vitest
- Code Quality: Prettier, TypeScript strict mode
- Deployment: Netlify compatible
koolihub/
├── client/ # Frontend React application
│ ├── pages/ # Route components
│ ├── components/ # Reusable UI components
│ │ ├── ui/ # Radix UI component library
│ │ ├── admin/ # Admin-specific components
│ │ ├── auth/ # Authentication components
│ │ └── ... # Feature-specific components
│ ├── contexts/ # React context providers
│ ├── hooks/ # Custom React hooks
│ ├── lib/ # Utility functions and configs
│ ├── domain/ # Domain entities and services
│ └── infrastructure/ # Infrastructure layer
├── server/ # Backend Express server
│ ├── routes/ # API endpoint handlers
│ └── lib/ # Server utilities
├── shared/ # Shared TypeScript types
├── supabase/ # Database migrations
│ └── migrations/ # SQL migration files
├── public/ # Static assets
└── docs/ # Documentation
- Node.js: v18+ recommended
- PNPM: v10+ (required)
- Supabase Account: For database and authentication
- Firebase Account: For push notifications (optional)
- Clone the repository
git clone https://github.com/yourusername/koolihub.git
cd koolihub- Install dependencies
pnpm install- Environment Setup
Create a .env file in the root directory:
# Supabase Configuration
VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
# Firebase Configuration (Optional)
VITE_FIREBASE_API_KEY=your_firebase_api_key
VITE_FIREBASE_AUTH_DOMAIN=your_firebase_auth_domain
VITE_FIREBASE_PROJECT_ID=your_firebase_project_id
VITE_FIREBASE_STORAGE_BUCKET=your_firebase_storage_bucket
VITE_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
VITE_FIREBASE_APP_ID=your_firebase_app_id
VITE_FIREBASE_MEASUREMENT_ID=your_measurement_id
VITE_FIREBASE_VAPID_KEY=your_vapid_key
# Payment Gateways
VITE_STRIPE_PUBLIC_KEY=your_stripe_public_key
STRIPE_SECRET_KEY=your_stripe_secret_key
VITE_RAZORPAY_KEY_ID=your_razorpay_key_id
RAZORPAY_KEY_SECRET=your_razorpay_key_secret
# Google Maps (Optional)
VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key- Database Setup
Run the SQL migrations in your Supabase SQL editor:
# Execute migrations in order from supabase/migrations/
# Or use the SQL files in the sql/ directory- Start Development Server
pnpm devThe application will be available at http://localhost:8080
| Script | Description |
|---|---|
pnpm dev |
Start development server (client + server) |
pnpm build |
Build for production |
pnpm build:client |
Build client only |
pnpm build:server |
Build server only |
pnpm start |
Start production server |
pnpm test |
Run tests with Vitest |
pnpm typecheck |
Run TypeScript type checking |
pnpm format.fix |
Format code with Prettier |
The project uses TypeScript path aliases for cleaner imports:
@/*→client/- Client-side code@shared/*→shared/- Shared types between client and server
Example:
import { supabase } from '@/lib/supabase';
import { ApiResponse } from '@shared/api';- Clear separation of concerns with domain, infrastructure, and presentation layers
- Domain-driven design for business logic
- Repository pattern for data access
- Single Responsibility Principle
- Open/Closed Principle
- Dependency Inversion
- Interface segregation
- Repository Pattern for data access
- Factory Pattern for entity creation
- Observer Pattern for real-time updates
- Strategy Pattern for payment processing
The application uses Supabase real-time subscriptions for:
- Product inventory changes
- Order status updates
- Vendor availability
- Cart synchronization
- Service area management with PostGIS
- Distance calculations for delivery
- Geocoding and reverse geocoding
- Map-based vendor discovery
- Service-specific custom fields
- Hierarchical attribute inheritance
- Multi-language attribute translations
- Flexible validation rules
- Customer Authentication: Email/password, magic links
- Vendor Authentication: Separate vendor portal with role-based access
- Admin Authentication: Super admin access with comprehensive permissions
- Row Level Security: PostgreSQL RLS policies for data isolation
- Stripe: Credit/debit cards, digital wallets
- Razorpay: UPI, cards, net banking, wallets
- Secure payment intent creation
- Client-side payment confirmation
- Webhook verification
- Order status update
pnpm build- Netlify: Configured with
netlify.toml - Vercel: Compatible with Edge Functions
- Custom Server: Node.js server deployment
Ensure all production environment variables are set in your deployment platform.
The database uses PostgreSQL with the following key tables:
vendors- Vendor profiles and settingsproducts- Product catalog with dynamic attributesorders- Order management and trackingservice_areas- Geospatial service coveragecustom_fields- Dynamic field definitionstranslations- Multi-language content
See sql/ directory for complete schema and migrations.
# Run all tests
pnpm test
# Run tests in watch mode
pnpm test --watch
# Run with coverage
pnpm test --coverageComprehensive documentation is available in the docs/ directory:
- Architecture guides
- API documentation
- Database schema documentation
- Component library documentation
- Deployment guides
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow TypeScript best practices
- Use functional components with hooks
- Implement proper error handling
- Write meaningful commit messages
- Add tests for new features
This project is private and proprietary.
Built with ❤️ by the KooliHub development team.
For support and queries, please contact:
- Email: support@koolihub.com
- Documentation: See
docs/directory
- Radix UI for accessible component primitives
- Supabase for backend infrastructure
- Vite for blazing fast development
- TailwindCSS for utility-first styling
Note: This is an active development project. Features and documentation are continuously evolving.