Welcome to HomeMaid! We're revolutionizing how you find and book home services with the power of AI. Think of it as your personal home service concierge that actually understands what you need, when you need it.
Got a leaky faucet at 2 AM? Just tell our AI: "My kitchen sink is dripping and driving me crazy!" We'll instantly connect you with the right plumber. It's that simple.
- Talk to Our AI Like a Friend: No more browsing endless categories! Just describe your problem in plain English: "My garden looks terrible and the neighbors are judging me" -> We'll find you the perfect landscaper
- Smart Service Discovery: Browse services by category or let our AI surprise you with perfect matches
- Hassle-Free Booking: Found the right service? Book it in under 2 minutes. Seriously.
- Stay in the Loop: Track everything from booking to completion. No more wondering "Did they forget about me?"
- Your Personal Space: Manage your profile, view your service history, and keep everything organized
- Command Central: See everything happening in your business at a glance
- Easy Service Management: Add new services, update existing ones, or pause bookings when you're swamped
- Order Tracking: Keep tabs on every order and update customers in real-time
- Consultation Hub: Manage consultations and keep detailed notes for follow-ups
- Privacy-First AI: Your conversations stay on our servers - no sending your data to Big Tech
- Lightning Fast: Local AI means instant recommendations without the wait
- Always Learning: Our fine-tuned Llama 3.2-1B model gets smarter with every interaction
- Backup Plans: Even if our AI takes a coffee break, you'll still get great service suggestions
We've built HomeMaid with modern, reliable technologies that just work:
- Frontend Magic: React 18.2.0 + Vite 5.0.0 (Fast loading? Yes! Smooth experience? Yes!)
- Styling That Doesn't Suck: Tailwind CSS 3.4.0 (Beautiful on every device)
- Smart Navigation: React Router DOM 6.20.0 (No confusing page jumps)
- Rock-Solid Backend: Supabase (PostgreSQL + Authentication that scales)
- Our AI Brain: Fine-tuned Llama 3.2-1B (Runs locally for your privacy)
- Reliable Communications: Axios 1.6.2 (Because broken forms are the worst)
- Time Made Simple: date-fns 3.0.0 (No more "When was that again?")
- Forms That Actually Work: React Hook Form 7.49.0 (Submit once, not seventeen times)
- Smart State Management: Zustand 4.4.7 (Keeps everything in sync)
Don't worry - it's not as scary as it sounds! Here's what you need:
- Node.js 16+ (Think of it as the engine that runs everything)
- Python 3.8+ (For our AI buddy to work)
- Supabase Account (Free tier works perfectly for getting started)
- Hugging Face Account (Also free - needed for our AI model)
cd homemaid
npm installGrab a coffee while this downloads everything you need
- Head over to supabase.com and create your free account
- Create a new project (pick any name you like!)
- Go to the SQL Editor and run our database setup from
DATABASE_SCHEMA.md - Copy your project URL and anon key (we'll need these in a sec)
cp .env.example .envOpen that new .env file and add your Supabase details:
VITE_SUPABASE_URL=your_supabase_project_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
VITE_AI_API_URL=http://localhost:5000/api/recommendcd ai_server
python -m venv venv
source venv/bin/activate # Windows users: venv\Scripts\activate
pip install -r requirements.txt
# Login to Hugging Face (this unlocks our AI model)
huggingface-cli login
# Fire up the AI server
python ai_server.pyPro tip: Check ai_server/README.md if you want to dive deeper into the AI setup
npm run devBoom! Visit http://localhost:5173 and watch the magic happen!
Here's the organized chaos that makes HomeMaid work:
homemaid/
|-- ai_server/ # Our AI's cozy home
| |-- ai_server.py # The AI brain itself
| |-- requirements.txt # What the AI needs to survive
| `-- README.md # AI setup secrets revealed
|-- src/
| |-- components/ # Reusable UI pieces (the good stuff!)
| | |-- Navbar.jsx # That nice top bar you see
| | |-- ServiceCard.jsx # Pretty service displays
| | |-- AIRecommendation.jsx # Where AI magic happens
| | `-- ProtectedRoute.jsx # Bouncer for private pages
| |-- pages/ # All the screens you'll see
| | |-- Home.jsx # Your landing pad
| | |-- Login.jsx # Welcome back portal
| | |-- Signup.jsx # New friend registration
| | |-- Services.jsx # The service catalog
| | |-- PurchaseService.jsx # Checkout made simple
| | |-- BookConsultancy.jsx # Expert consultation booking
| | |-- MyOrders.jsx # Your order history
| | |-- MyConsultancies.jsx # Your consultation tracker
| | |-- Profile.jsx # Your personal space
| | `-- admin/ # Admin control center
| | |-- AdminDashboard.jsx # The command bridge
| | |-- ServiceManagement.jsx # Service control panel
| | |-- OrderManagement.jsx # Order mission control
| | `-- ConsultancyManagement.jsx # Consultation HQ
| |-- hooks/ # Custom React superpowers
| | `-- useAuth.jsx # Authentication magic
| |-- services/ # API connection wizards
| | `-- aiService.js # Talks to our AI
| |-- lib/ # Helpful utilities
| | `-- supabase.js # Database connection
| |-- App.jsx # Main app with all the routes
| `-- main.jsx # The launch pad
|-- DATABASE_SCHEMA.md # Database blueprint
|-- .env.example # Secret configuration template
`-- README.md # This very guide you're reading!
Our database is like a well-organized filing cabinet with these important sections:
- profiles - Where we keep your personal info (safely!)
- services - All the amazing services we offer
- orders - Your purchase history and status
- consultancies - Your expert consultation bookings
- admin_users - Special access for service managers
Curious about the nitty-gritty? Check out DATABASE_SCHEMA.md for all the technical details!
- Discover and buy services that solve your problems
- Book one-on-one consultations with experts
- Keep track of everything in your personal dashboard
- Manage your profile like a boss
- Everything homeowners can do, plus:
- Create and manage services (add, edit, or pause when busy)
- Track and update order statuses in real-time
- Manage consultation bookings and add helpful notes
Want to become an admin? The setup instructions are in DATABASE_SCHEMA.md
Here's how our smart assistant works its magic:
- You Speak Naturally - Tell us what's bothering you: "My bathroom looks like it's from 1985"
- AI Brain Activation - Our locally hosted, fine-tuned Llama 3.2-1B model thinks deeply about your problem
- Smart Matching - Get the top 3 services that actually solve your specific issue
- Always Reliable - If our AI is taking a nap, we'll show you popular services instead
- Your Privacy Matters - Your problems stay between you and us - no data mining here!
- Lightning Fast - No waiting for responses from distant servers
- No Surprise Bills - Zero API costs means we can focus on helping you, not counting pennies
- Gets Smarter Daily - Our model learns and improves specifically for home services
Look for the little indicator that shows if our AI is awake and ready to help - it's like a green light for getting great recommendations!
- Home (
/) - Your first impression! See our hero section and get instant AI recommendations - Services (
/services) - Browse our full catalog with smart filtering options - Login (
/login) - Welcome back, friend! Quick and easy sign-in - Signup (
/signup) - Join the family! Creating your account takes 30 seconds
- Purchase Service (
/purchase/:serviceId) - Found what you need? Let's make it happen! - Book a Consultation (
/book-consultancy) - Need expert advice? Schedule a chat - My Orders (
/my-orders) - Track everything you've ordered (including that emergency plumbing!) - My Consultations (
/my-consultancies) - See all your expert meetings in one place - Profile (
/profile) - Make it yours - update info, preferences, everything
- Dashboard (
/admin) - The bird's eye view with stats and quick actions - Service Management (
/admin/services) - Your service control room (create, edit, pause, activate) - Order Management (
/admin/orders) - Keep customers happy by tracking and updating orders - Consultation Hub (
/admin/consultancies) - Manage meetings and keep detailed notes
We use Supabase's battle-tested authentication system:
- Email & Password - Simple, secure, familiar
- Auto Session Management - Stay logged in (until you want to log out)
- Row Level Security - Your data stays YOUR data
- Smart Route Protection - Only see what you're supposed to see
- Admin-Only Areas - Special features for special people
- Responsive Everything - Looks amazing on your phone, tablet, or computer
- No More Waiting - Smart loading states so you know something's happening
- Friendly Notifications - Toast messages that actually help instead of annoy
- Forms That Work - Validation that catches mistakes before you make them
- Error Handling - When things go wrong, we'll tell you what happened (and how to fix it)
- Smooth Transitions - Everything flows naturally
- Actually Accessible - Built for everyone to use comfortably
Making HomeMaid live on the internet is easier than you think:
- Push to GitHub - Get your code up there (you've probably done this already!)
- Connect & Deploy - Link your repository to Vercel or Netlify (they'll walk you through it)
- Add Your Secret Codes - Set these environment variables in your deployment settings:
VITE_SUPABASE_URL(your database connection)VITE_SUPABASE_ANON_KEY(your database access key)VITE_AI_API_URL(where your AI lives - see below!)
- Hit Deploy - Watch the magic happen!
Since our AI runs locally with your fine-tuned model, you have options:
** Option 1: Keep It Local (Perfect for Development)**
- Let the AI server chill on your machine
- Frontend talks to
http://localhost:5000 - Great for testing and development
** Option 2: Share With the World (Great for Demos)** Make your local AI accessible from anywhere:
# Using ngrok (super easy!)
ngrok http 5000
# Or try localtunnel
npm install -g localtunnel
lt --port 5000Update VITE_AI_API_URL in your deployment to use the public URL you get.
** Option 3: Full Cloud Power (For Serious Business)** Deploy your AI server to the cloud:
- Railway.app - Simple, affordable, great for AI workloads
- Render.com - Easy setup with free tier options
- Hugging Face Spaces - Perfect for AI models (they get it!)
- AWS/Google Cloud/Azure - The big guns (if you need serious power)
Note: AI models love GPU power, so consider that for production deployments
Supabase is already hosted and ready to scale. One less thing to worry about!
Make sure everything works before you celebrate:
- New user can sign up and log in smoothly
- Service browsing and filtering works like a charm
- AI recommendations are firing on all cylinders
- Service purchase flow doesn't break anyone's heart (or wallet flow)
- Consultation booking actually books consultations
- Order history shows up correctly
- Profile editing saves changes properly
- Admin can manage services without pulling their hair out
- Admin order management keeps customers informed
- Admin consultation management works smoothly
- Everything looks good on phones, tablets, and computers
# Fire up development mode
npm run dev
# Build for the world to see
npm run build
# Preview what production will look like
npm run preview
# Wake up the AI brain
cd ai_server && python ai_server.py- Check if it's running:
python ai_server.pyin the ai_server folder - Verify the connection: Make sure
VITE_AI_API_URLin.envpoints to the right place - Port problems: Flask should be running on port 5000 (check for conflicts)
- Double-check your secrets: Make sure environment variables are set correctly
- Permission issues: Check Row Level Security policies in your Supabase dashboard
- Missing tables: Ensure you ran all the SQL from
DATABASE_SCHEMA.md
- Nuclear option: Delete
node_modulesandpackage-lock.json, thennpm install - Cache problems: Clear Vite's cache with
rm -rf node_modules/.vite - Still broken?: Check the error message - it's usually more helpful than it looks!
| Variable | What It Does | Example Value |
|---|---|---|
VITE_SUPABASE_URL |
Your database home address | https://yourproject.supabase.co |
VITE_SUPABASE_ANON_KEY |
Database access pass | eyJhbGciOiJIUzI1NiI... |
VITE_AI_API_URL |
Where to find your AI assistant | http://localhost:5000/api/recommend |
This is a complete marketplace, but there's always room to grow:
- Real Payments - Add Stripe or PayPal for actual transactions
- Live Chat - Real-time customer support chat
- Smart Notifications - Email updates for order status
- Reviews & Ratings - Let customers share their experiences
- Mobile App - Native iOS/Android versions
- Better AI - More specialized AI models for different service types
This project was created for educational purposes. Feel free to learn from it, build upon it, and make it your own!
We couldn't have built this without:
- Supabase - For making backend development not horrible
- Meta - For the incredible Llama 3.2-1B model
- Hugging Face - For making AI accessible to everyone
- Tailwind CSS - For making our design system not look like it's from 2005
- The Open Source Community - For all the amazing tools and libraries
Stuck on something? Here's your action plan:
- Database Issues? Check
DATABASE_SCHEMA.mdfor setup details - AI Problems? Dive into
ai_server/README.mdfor AI-specific help - Mystery Errors? Open your browser's developer console - it knows things
- Environment Variables? Double-check that everything is set correctly
- Still Stuck? The error messages are usually friendlier than they look!
Built with love, lots of coffee, and a genuine desire to make home services actually enjoyable
Ready to revolutionize how people find home services? Let's make it happen!