Odoo x SPIT Mumbai

Team : NexByte

Team Members : Priy Mavani | Mayur Waykar | Krish Shyara | Vanshika Jangam

📅 Appointment Booking System

Smart Digital Platform for Managing Appointments & Services

Transforming appointment management with real-time booking tracking, role-based dashboards, advanced scheduling, and seamless provider coordination for customers, organisers, and admins.

📚 API Documentation • 🚀 Quick Start • 🏗️ Architecture

---

🔗 Project Links

💻 Frontend React Client →

⚙️ Backend Express Server →

⚙️ Postman Documentation Postman Documentation →

🤖 MCP Server

---

🎯 Problem Statement

Traditional appointment and service booking systems face critical operational challenges:

📋 Current Pain Points 🚫 Manual scheduling causing double bookings ❌ No real-time availability synchronization 📊 Inefficient resource management across providers 🕒 Poor visibility into booking status 📉 Lack of analytics for business insights 🔐 Security concerns in credential management

✅ Our Solution ✨ Smart slot management preventing conflicts 📍 Real-time availability across multiple providers 🎯 Resource optimization and allocation 📱 Instant booking confirmation & notifications 📈 Advanced analytics & performance reports 🔒 Secure JWT authentication with role-based access

---

🚀 Key Features

👤 For Customers 🛒 Easy Appointment Booking Browse available services View real-time slot availability Answer custom service questions Instant booking confirmation 📍 Track Appointments Interactive calendar view Real-time booking status updates Appointment history & details Search & filter capabilities 📊 Booking Management View all upcoming appointments Cancel or reschedule bookings View provider & resource details Quick re-booking from history

👕 For Organisers/Providers 🏢 Service Management Create custom appointment types Configure booking rules & availability Set advance payment requirements Add custom pre-booking questions 👥 Resource Management Assign service providers/resources Manage provider availability Track provider performance Update provider information 📦 Booking Operations View incoming booking requests Confirm or reject bookings Manage appointment schedules Generate shareable booking links

🛠️ For Admins

• 📊 System Overview

  • Monitor all bookings and services
  • Track system performance metrics
  • View peak booking patterns
  • Provider utilization analysis

• 👥 User & Access Management

  • Manage all system users
  • Update user roles & permissions
  • Toggle user active/inactive status
  • Monitor user activities

• 📈 Analytics & Reports

  • Peak booking hours visualization
  • Provider performance reports
  • Service utilization metrics
  • System statistics dashboard

🌟 Additional Features

• 🔐 Role-Based Access Control - Different permissions for customers, organisers, and admins
• 🔔 Smart Notifications - Toast alerts for all important events
• 📅 Calendar UI - Interactive month-view calendar with appointment visualization
• 🔗 Shareable Links - Generate public booking links for services
• 🎨 Modern Design - Clean, professional UI with TailwindCSS
• ⚡ Real-time Updates - Instant slot availability synchronization
• 📱 Responsive Design - Fully optimized for all screen sizes
• 🤖 MCP Integration - Claude Desktop tool integration for enhanced automation

---

🛠️ Tech Stack

Frontend

Backend

Tools & Integration

---

📁 Architecture Overview

graph TB
    A[React Frontend] -->|JWT Auth| B[Express Backend]
    B -->|CRUD Operations| C[MongoDB]
    B -->|Slot Validation| D[Slot Lock Manager]
    A -->|State Management| E[Context API + Local Storage]
    A -->|Form Handling| F[React Router]
    B -->|Email Notifications| G[Nodemailer Service]
    A -->|Notifications| H[React Hot Toast]
    I[MCP Server] -->|14 Tools| B
    J[Claude Desktop] -.->|Interact| I

Loading

System Architecture

• Three-Tier Architecture - Clear separation between frontend, API, and database layers
• Role-Based Access Control (RBAC) - Fine-grained permissions for Customer, Organiser, and Admin roles
• RESTful API Design - Clean, predictable endpoints following REST conventions
• Real-time Slot Management - Advanced slot-locking mechanism preventing overbooking
• JWT Authentication - Secure token-based authentication with expiration
• Database Transactions - MongoDB sessions for data consistency
• Scalable Design - Modular architecture supporting multiple services and providers
• MCP Integration - Claude AI integration for enhanced automation capabilities

---

📂 Project Structure

appointment-backend/
├── 📖 README.md
├── 📄 POSTMAN_API_DOCUMENTATION.md
│
└── 🎯 hcakthon-frontend/
    ├── 💻 client/                           # React Frontend
    │   ├── 📦 package.json
    │   ├── ⚙️ vite.config.mts
    │   ├── 🎨 tailwind.config.mjs
    │   ├── postcss.config.mjs
    │   └── 📂 src/
    │       ├── 🎮 App.jsx                   # Main app router
    │       ├── 🎨 index.css                 # Global styles
    │       ├── main.jsx                     # Entry point
    │       ├── 📂 pages/                    # Route pages
    │       │   ├── LandingPage.jsx
    │       │   ├── Login.jsx
    │       │   ├── Signup.jsx
    │       │   ├── VerifyOtp.jsx
    │       │   ├── ForgotPassword.jsx
    │       │   └── 📂 admin/
    │       │       └── Dashboard.jsx        # Admin panel
    │       │   └── 📂 customer/
    │       │       ├── Dashboard.jsx        # Service browsing
    │       │       ├── BookingFlow.jsx      # Slot selection
    │       │       ├── ConfirmBooking.jsx   # Confirmation page
    │       │       └── MyBookings.jsx       # Calendar view
    │       │   └── 📂 organiser/
    │       │       ├── Dashboard.jsx        # Service management
    │       │       ├── CreateService.jsx    # Create appointments
    │       │       ├── ServiceDetail.jsx    # Resource management
    │       │       ├── ManageBookings.jsx   # Booking requests
    │       │       └── SharedBookingPage.jsx # Public booking link
    │       ├── 🧩 components/
    │       │   └── Navbar.jsx               # Navigation & profile modal
    │       ├── 🔌 api/
    │       │   └── auth.js                  # Auth API functions
    │       └── 🛠️ services/
    │           └── api.js                   # Axios instance
    │
    ├── ⚙️ server/                           # Express Backend
    │   ├── 📦 package.json
    │   └── 📂 src/
    │       ├── 🚀 server.js                 # Server entry point
    │       ├── 📱 app.js                    # Express config
    │       ├── 🌱 seed.js                   # Database seeding
    │       ├── 📂 config/
    │       │   ├── db.js                    # MongoDB connection
    │       │   └── env.js                   # Environment validation
    │       ├── 🎮 controllers/              # Route handlers
    │       │   ├── authController.js
    │       │   ├── adminController.js
    │       │   ├── bookingController.js
    │       │   ├── resourceController.js
    │       │   ├── serviceController.js
    │       │   └── slotController.js
    │       ├── 📊 models/                   # Database schemas
    │       │   ├── User.js
    │       │   ├── AppointmentService.js
    │       │   ├── Booking.js
    │       │   ├── Resource.js
    │       │   ├── Schedule.js
    │       │   └── SlotLock.js
    │       ├── 🛣️ routes/                   # API routes
    │       │   ├── authRoutes.js
    │       │   ├── adminRoutes.js
    │       │   ├── bookingRoutes.js
    │       │   ├── resourceRoutes.js
    │       │   ├── serviceRoutes.js
    │       │   └── slotRoutes.js
    │       ├── 🔒 middleware/                # Auth & validation
    │       │   ├── auth.js
    │       │   ├── error.js
    │       │   └── roles.js
    │       └── 🛠️ utils/
    │           ├── dateTime.js
    │           ├── email.js
    │           └── responses.js
    │
    └── 🤖 mcp-server/                       # Claude Desktop Integration
        ├── 📦 package.json
        ├── 📝 README.md
        ├── 🔧 server.js                     # Single-file MCP server
        └── claude_desktop_config.json       # MCP configuration

---

🚀 End-to-End Setup

📋 Prerequisites

Before you begin, ensure you have installed:

• Node.js 18+
• MongoDB (local or cloud - MongoDB Atlas)
• npm or yarn
• Git (for cloning)

---

⚙️ Backend Setup

1️⃣ Navigate to backend directory:

cd server

2️⃣ Install dependencies:

npm install

3️⃣ Create .env file in server/ directory:

# Server Configuration
PORT=5000
NODE_ENV=development

# MongoDB Connection (choose one)
# Local MongoDB:
MONGO_URI=mongodb://localhost:27017/appointment-booking

# MongoDB Atlas (recommended):
# MONGO_URI=mongodb+srv://username:password@cluster.mongodb.net/appointment-booking

# JWT Configuration
JWT_SECRET=your_super_secret_jwt_key_here_min_32_chars
JWT_EXPIRE=7d

# CORS Configuration
FRONTEND_ORIGIN=http://localhost:5173

# Email Configuration (Optional - for notifications)
EMAIL_SERVICE=gmail
EMAIL_USER=your_email@gmail.com
EMAIL_PASSWORD=your_app_password

4️⃣ Seed database with sample data (optional):

npm run seed

5️⃣ Start development server:

npm start

6️⃣ Expected output:

✅ Connected to MongoDB
✅ Server running on http://localhost:5000

Backend is ready for API requests!

---

💻 Frontend Setup

1️⃣ Navigate to frontend directory:

cd client

2️⃣ Install dependencies:

npm install

3️⃣ Create .env file in client/ directory:

# Backend API Configuration
VITE_API_URL=http://localhost:5000

# Application Configuration
VITE_APP_NAME=Appointment Booking System
VITE_APP_VERSION=1.0.0

4️⃣ Start development server:

npm run dev

5️⃣ Open your browser and navigate to:

🌐 http://localhost:5173

---

🤖 MCP Server Setup (Optional - for Claude Desktop)

1️⃣ Navigate to MCP server directory:

cd hcakthon-frontend/mcp-server

2️⃣ Install dependencies:

npm install

3️⃣ Configure Claude Desktop:

Follow the instructions in mcp-server/README.md to set up MCP integration with Claude Desktop.

---

📖 Usage Guide

🔐 Getting Started

For Customers:

1. ✍️ Register/Login with your credentials
2. 🔍 Browse available services on customer dashboard
3. 📅 Select date and time slots
4. ✍️ Answer service-specific questions (if any)
5. ✅ Confirm booking and receive confirmation
6. 📍 Track appointment status in real-time

For Organisers/Providers:

1. ✍️ Register/Login with organiser credentials
2. ➕ Create appointment types with availability rules
3. 👥 Add and manage service providers/resources
4. 📦 Publish services to make them available
5. 📊 Manage incoming booking requests
6. 📈 View bookings and analytics

For Admins:

1. 🔐 Login with admin credentials
2. 👥 Manage all system users and their roles
3. 📊 Monitor booking statistics and trends
4. 📈 View provider performance reports
5. 🔍 Analyze peak booking hours

---

🛒 Customer Booking Flow

Step 1: Browse Services

• Navigate to /customer/dashboard
• Search for desired services
• View service details (duration, provider, rules)

Step 2: Select Date & Slot

• Navigate to booking page for service
• Choose preferred date
• Select available time slot
• View real-time slot availability

Step 3: Provide Information

• Answer custom service questions (if required)
• Optionally select a preferred resource/provider
• Review all selections

Step 4: Confirm Booking

• Review complete booking summary
• Confirm appointment
• Receive instant confirmation and ID

Step 5: Track Appointment

• View in "My Bookings" calendar
• See appointment status updates
• Get notifications on status changes

---

👕 Organiser Service Management

Creating a New Service:

1. Navigate to Organiser Dashboard
2. Click "Create New Service"
3. Fill service details:
   • Title & Description
   • Duration (in minutes)
   • Availability schedules
   • Booking rules (confirmation, payment)
   • Custom questions (optional)
4. Save service

Managing Resources:

1. Go to service details
2. Add service providers/resources:
   • Name
   • Email
3. Toggle resource active/inactive
4. View resource performance

Managing Bookings:

1. Navigate to "Bookings" section
2. View incoming booking requests
3. Confirm or reject requests
4. Optionally assign resources
5. Track booking history

Generating Shareable Links:

1. Open service details
2. Generate public booking link
3. Share with customers
4. Track bookings from link

---

🛠️ Admin Dashboard

Dashboard Overview:

• 📊 System statistics (total users, services, bookings)
• 👥 Active/inactive user count
• 📈 Peak booking patterns visualization

User Management:

• View all system users
• Update user roles
• Toggle user active/inactive status
• Filter by role

Reports & Analytics:

• Peak booking hours (bar chart)
• Provider utilization metrics
• Service performance analysis
• Booking trend reports

---

🔑 Demo Credentials

For quick testing, use these seed credentials:

Admin Account

Email: admin@example.com
Password: Admin123!
Role: Admin

Organiser Account

Email: organiser@example.com
Password: Organiser123!
Role: Organiser

Customer Account

Email: customer@example.com
Password: Customer123!
Role: Customer

---

📜 API Endpoints

Authentication (/auth)

POST   /auth/signup                  # User registration
POST   /auth/verify-otp              # Verify OTP
POST   /auth/login                   # User login
POST   /auth/forgot-password         # Request password reset
POST   /auth/reset-password/:token   # Reset password
GET    /auth/me                      # Get current user
GET    /auth/service-by-token/:token # Get service by share token

Services (/services)

GET    /services                     # Get all published services
GET    /services/:id                 # Get service details
POST   /services                     # Create service (organiser only)
PUT    /services/:id                 # Update service (organiser only)
DELETE /services/:id                 # Delete service (organiser only)
PATCH  /services/:id/publish         # Publish/unpublish service
POST   /services/:id/share-link      # Generate shareable link
GET    /services/:id/resources       # Get service resources

Slots (/slots)

GET    /slots                        # Get available slots for date
POST   /slots                        # Lock slot (internal use)

Bookings (/bookings)

GET    /bookings/my                  # Get customer's bookings
GET    /bookings/organiser           # Get organiser's bookings (with filters)
POST   /bookings                     # Create new booking
PATCH  /bookings/:id/confirm         # Confirm booking (organiser)
PATCH  /bookings/:id/cancel          # Cancel booking
PATCH  /bookings/:id/resource        # Assign resource to booking

Resources (/services/:serviceId/resources)

GET    /services/:serviceId/resources     # List resources
POST   /services/:serviceId/resources     # Create resource
PATCH  /resources/:id                     # Update resource
DELETE /resources/:id                     # Delete resource

Admin (/admin)

GET    /admin/stats                  # Get system statistics
GET    /admin/users                  # List all users
PATCH  /admin/users/:id/toggle       # Toggle user active status
PATCH  /admin/users/:id/role         # Update user role
GET    /admin/reports/peak-hours     # Peak booking hours report
GET    /admin/reports/provider-utilization # Provider performance

---

🔒 Security Features

🔐 Security Best Practices Implemented:

• ✅ JWT Authentication - Secure token-based authentication with expiration
• ✅ Password Hashing - Bcrypt encryption (salt rounds: 10)
• ✅ Role-Based Access Control - Permission validation on every protected route
• ✅ Input Validation - Mongoose schema validation and request sanitization
• ✅ CORS Protection - Configured origin restrictions
• ✅ Helmet.js - HTTP security headers
• ✅ Error Handling - Global error middleware with safe error messages
• ✅ Slot Locking - Distributed locking to prevent race conditions
• ✅ Transaction Support - MongoDB sessions for data consistency

⚠️ Production Checklist:

• 🔐 Use strong JWT_SECRET (minimum 32 characters, randomized)
• 🌐 Enable HTTPS/TLS for all communications
• 🔒 Implement rate limiting on login endpoints
• 📝 Regular security audits and dependency updates
• 🔑 Rotate JWT secrets periodically
• 📊 Enable comprehensive logging and monitoring
• 🛡️ Use environment-specific configurations
• 🚀 Deploy with proper error logging (Sentry, DataDog, etc.)

---

📊 System Metrics

Performance Targets

• ⚡ Page Load Time: < 2 seconds
• 🔄 API Response Time: < 500ms
• 📈 Slot Query Performance: < 100ms
• 👥 Concurrent Users: 1000+
• 📊 Database Query Optimization: Indexed fields

Success Metrics

• ✅ 100% Uptime (with proper deployment)
• 📉 Zero overbooking (slot-lock mechanism)
• ⏱️ < 1 second booking confirmation
• 😊 95%+ User satisfaction rate

---

📊 Database Models

User Schema

{
  name: String,
  email: String,
  password: String (hashed),
  role: Enum['customer', 'organiser', 'admin'],
  isVerified: Boolean,
  isActive: Boolean,
  otp: String,
  otpExpiry: Date,
  createdAt: Date,
  updatedAt: Date
}

AppointmentService Schema

{
  title: String,
  description: String,
  duration: Number,
  organiserId: ObjectId,
  published: Boolean,
  bookingRules: {
    maxBookingsPerSlot: Number,
    manualConfirmation: Boolean,
    advancePayment: Boolean
  },
  schedules: Array,
  questions: Array,
  shareToken: String,
  createdAt: Date,
  updatedAt: Date
}

Booking Schema

{
  userId: ObjectId,
  serviceId: ObjectId,
  resourceId: ObjectId,
  date: Date,
  startTime: String,
  status: Enum['pending', 'confirmed', 'cancelled'],
  answers: Array,
  createdAt: Date,
  updatedAt: Date
}

---

📈 Future Enhancements

Phase 1 (Current) ✅

• Basic appointment booking system
• Role-based authentication
• Real-time slot availability
• Resource/provider management
• Admin dashboard with analytics
• Calendar view for appointments
• MCP server integration

Phase 2 (Planned) 🔄

• Payment gateway integration (Stripe, PayPal)
• SMS/Email notification system
• Video consultation support
• Appointment reminders
• User reviews and ratings
• Service categories and filters

Phase 3 (Future) 📅

• Mobile app (React Native)
• Multi-location support
• Subscription and pricing tiers
• AI-powered recommendations
• Analytics export and reports
• Integration with calendar services (Google, Outlook)

---

🧪 Testing

Manual Testing

1. Test booking flow end-to-end
2. Verify slot availability updates
3. Test role-based access control
4. Verify email notifications
5. Test calendar interactions

API Testing

• Use Postman collection (see POSTMAN_API_DOCUMENTATION.md)
• Test all endpoints with valid/invalid inputs
• Verify error responses

---

🐛 Troubleshooting

❌ MongoDB Connection Error

Solution:

• Ensure MongoDB is running: mongod --version
• Check MONGO_URI in .env file
• For MongoDB Atlas:
  • Verify network access is configured
  • Check database user permissions
  • Ensure password is URL-encoded
• Restart backend after environment changes

❌ JWT Authentication Fails

Solution:

• Verify JWT_SECRET is set in backend .env
• Clear browser localStorage: localStorage.clear()
• Login again to get fresh token
• Check token format in Authorization header: Bearer <token>
• Verify token hasn't expired

❌ CORS Error from Frontend

Solution:

• Verify FRONTEND_ORIGIN matches frontend URL (default: http://localhost:5173)
• Check backend CORS configuration in app.js
• Restart backend after .env changes
• Clear browser cache

❌ Booking Submission Fails

Solution:

• Verify all required fields: serviceId, date, startTime
• Check date format: must be YYYY-MM-DD
• Ensure date is not in the past
• Verify user is authenticated (valid JWT token)
• Check backend logs for validation errors
• Verify service is published

❌ Slot Not Available

Solution:

• Check service availability schedules
• Verify slot is within operating hours
• Ensure maximum bookings per slot not exceeded
• Check for past dates
• Verify selected date has available slots

❌ Frontend Can't Reach Backend

Solution:

• Verify backend is running on port 5000
• Check VITE_API_URL in frontend .env
• Ensure CORS is properly configured
• Check network connectivity
• Try accessing API directly: http://localhost:5000/api/services

---

🎨 UI/UX Highlights

• 🎯 Intuitive Navigation - Role-specific dashboards for different user types
• 📱 Mobile-First Design - Fully responsive across all devices
• 🎨 Modern Interface - Clean, professional design with TailwindCSS
• ⚡ Fast Loading - Optimized performance with lazy loading
• 🔔 Smart Notifications - Toast alerts for all important events
• 📊 Data Visualization - Charts and statistics for analytics
• 🌐 Responsive Grids - Adaptive layouts for all screen sizes
• ♿ Accessibility - Semantic HTML and keyboard navigation

---

📦 Deployment

Frontend Deployment (Vercel/Netlify)

npm run build
# Deploy the dist/ folder to your hosting service

Backend Deployment

1. Set environment variables in deployment platform
2. Ensure MongoDB Atlas is accessible
3. Deploy using Render, Railway, or Heroku
4. Update FRONTEND_ORIGIN for CORS

MCP Server Deployment

Follow mcp-server README for Claude Desktop configuration.

---

🤝 Contributing

We welcome contributions! Here's how you can help:

1. 🍴 Fork the repository
2. 🌿 Create your feature branch (git checkout -b feature/AmazingFeature)
3. 💻 Commit your changes (git commit -m 'Add some AmazingFeature')
4. 📤 Push to the branch (git push origin feature/AmazingFeature)
5. 🔀 Open a Pull Request

---

📄 License

This project is licensed under the ISC License - see the LICENSE file for details.

---

📧 Contact & Support

Need help or have questions?

📧 Email: Email
💼 LinkedIn: Profile
🐙 GitHub: Profile

👨‍💻 Developer: Mayur Waykar

Found this project helpful? Give it a ⭐ on GitHub!

---

🚀 Quick Commands Reference

# Backend
cd hcakthon-frontend/server
npm install
npm start              # Start server
npm run seed           # Seed database

# Frontend
cd hcakthon-frontend/client
npm install
npm run dev            # Start dev server
npm run build          # Build for production
npm run preview        # Preview production build

# MCP Server
cd hcakthon-frontend/mcp-server
npm install
node server.js         # Start MCP server

---

📅 Transforming Appointment Management, One Booking at a Time

Made with 💙 and ☕ by Mayur

Happy Booking! ✨

---

Last Updated: December 2025