ClinicPlus - Medical Clinic Platform

📋 Project Overview

ClinicPlus is a full-stack medical clinic management platform built with modern web technologies. It provides a comprehensive solution for clinic operations, including patient management, doctor profiles, appointment scheduling, medical history tracking, and administrative controls.

🛠️ Technology Stack

Core Framework

• Next.js 16 (App Router architecture)
• TypeScript (type-safe development)

Frontend

• React 19
• Tailwind CSS 4 (styling)
• shadcn/ui (component library)
• MUI (Material UI 7) (admin dashboard components)
• Chart.js (data visualization)
• MUI X Charts (advanced charting)
• Lucide React & Tabler Icons (icon libraries)

Backend & Database

• MongoDB (database)
• Mongoose 9 (ODM - Object Document Mapper)

Authentication

• NextAuth.js 4 (authentication framework)
• Google OAuth (social login provider)

Media & Storage

• Cloudinary (image/file upload and management)

Utilities

• Lodash (utility functions)
• React Hot Toast (notifications)
• Class Variance Authority (component variants)

🏗️ Project Architecture

Directory Structure

graduateion_project/
├── app/ # Next.js App Router
│ ├── (public)/ # Public-facing pages (no auth required)
│ │ ├── page.tsx # Home page
│ │ ├── doctors/ # Doctors listing
│ │ ├── doctors/[id]/ # Individual doctor profile
│ │ ├── about/ # About/Team page
│ │ └── statics/ # Analytics/Statistics page
│ │
│ ├── (dashboard)/ # Protected dashboard routes
│ │ ├── admin/ # Admin dashboard
│ │ │ ├── users/ # User management
│ │ │ ├── doctors/ # Doctor management
│ │ │ └── ... # Admin features
│ │ └── profile/ # User profile pages
│ │
│ ├── api/ # Backend API routes
│ │ ├── auth/[...nextauth]/ # Authentication endpoints
│ │ ├── profile/ # Profile management APIs
│ │ ├── admin/ # Admin operation APIs
│ │ ├── doctors/ # Public doctor APIs
│ │ └── upload/ # File upload API
│ │
│ ├── Components/ # Shared UI components
│ ├── layout.tsx # Root layout with metadata
│ └── globals.css # Global styles
│
├── components/
│ └── ui/ # Reusable UI primitives (shadcn)
│
├── models/ # Mongoose database models
│ ├── User.ts # User schema
│ ├── Doctors.ts # Doctor schema
│ ├── Review.ts # Review schema
│ ├── MedicalHistory.ts # Medical history schema
│ └── UpcomingDates.ts # Appointments schema
│
├── lib/ # Utility libraries
│ ├── db.ts # Database connection
│ ├── auth.ts # Auth configuration
│ └── ... # Helper functions
│
├── types/ # TypeScript type definitions
├── public/ # Static assets
├── next.config.ts # Next.js configuration
├── tsconfig.json # TypeScript configuration
├── tailwind.config.ts # Tailwind CSS configuration
└── package.json # Dependencies & scripts

👥 User Roles & Access Control

1. Guest (Unauthenticated)

• Browse public pages (home, about, statistics)
• View doctors directory
• View doctor public profiles and reviews
• Search doctors

2. Authenticated User (Patient)

• All Guest permissions
• Edit personal profile
• Submit reviews/ratings for doctors
• View and manage medical history
• View upcoming appointments

3. Doctor

• All Authenticated User permissions
• Access doctor-specific profile page
• Manage doctor profile information
• View patient reviews
• Manage appointments

4. Administrator

• All permissions
• Access /admin dashboard
• Manage all users (view, edit, delete)
• Manage doctors (add, edit, remove)
• Add users as doctors
• View system analytics

Admin Access Control: Defined by AUTH_ADMINS environment variable (comma-separated email list)

📦 Database Models

User Model

• Personal information (name, email, avatar)
• Role assignments (patient, doctor, admin)
• Authentication linkage (Google OAuth)
• Profile settings

Doctors Model

• Doctor profile details
• Specialization
• Rating and review aggregates
• Availability information
• Profile images

Review Model

• Reviewer reference (user)
• Doctor reference
• Rating (numeric score)
• Comment text
• Timestamp

MedicalHistory Model

• Patient reference
• Medical records
• Diagnosis information
• Treatment history
• Date tracking

UpcomingDates Model

• Appointment scheduling
• Patient-doctor linkage
• Date/time management
• Status tracking

🔌 API Endpoints

Public APIs (No Authentication Required)

GET /api/doctors # List all doctors (with search & pagination)
GET /api/doctors/[id] # Get doctor by ID
POST /api/doctors/[id]/reviews # Submit a review (requires auth)

Profile APIs (Authentication Required)

GET /api/profile # Get user profile
PATCH /api/profile # Update user profile
GET /api/profile/doctor/medical-history # Get medical history
POST /api/profile/doctor/medical-history # Add medical history
GET /api/profile/doctor/appointments # Get appointments
POST /api/profile/doctor/appointments # Add appointment

Admin APIs (Admin Authentication Required)

GET /api/admin/users # List all users
GET /api/admin/users/[id] # Get user details
PATCH /api/admin/users/[id] # Update user
GET /api/admin/doctors # List all doctors
POST /api/admin/doctors # Add new doctor
GET /api/admin/doctors/[id] # Get doctor details
PATCH /api/admin/doctors/[id] # Update doctor
DELETE /api/admin/doctors/[id] # Delete doctor

Other APIs

POST /api/upload # Upload file to Cloudinary
GET/POST /api/auth/[...nextauth] # NextAuth authentication

🌐 Application Flow

User Journey

1. Landing & Browsing (Guest)

Home Page → Browse Doctors → View Doctor Profile → (Optionally Sign Up)

2. Patient Workflow

Sign In (Google OAuth)
↓
Dashboard/Profile
↓
├─ Edit Profile Settings
├─ View Medical History
├─ Book Appointments
├─ Rate/Review Doctors
└─ Manage Account

3. Doctor Workflow

Sign In (Google OAuth)
↓
Doctor Profile Page
↓
├─ Update Professional Info
├─ View Patient Reviews
├─ Manage Appointments
└─ View Medical History (if also a patient)

4. Admin Workflow

Sign In (Google OAuth - must be in AUTH_ADMINS)
↓
Admin Dashboard (/admin)
↓
├─ Users Management
│ ├─ View User List
│ ├─ Edit User Details
│ └─ Manage User Roles
│
├─ Doctors Management
│ ├─ View Doctor Cards
│ ├─ Add New Doctor
│ ├─ Edit Doctor Profile
│ └─ Remove Doctor
│
└─ System Analytics

🔐 Authentication Flow

User clicks "Sign In"
↓
Google OAuth Redirect
↓
NextAuth validates credentials
↓
User session created
↓
├─ If new user → Create User document in MongoDB
├─ If existing user → Load profile
└─ If admin email in AUTH_ADMINS → Grant admin access
↓
Redirect to appropriate page (profile/dashboard)

🎨 UI/UX Features

Public Pages

• Hero Section: Engaging landing area
• Features Section: Platform highlights
• Doctors Directory: Searchable, paginated list
• Doctor Profile: Detailed view with reviews
• About/Team: Organization information
• Statistics: Analytics dashboard (public metrics)

Dashboard Pages

• User Profile: Tabbed interface for settings
• Admin Dashboard: Data tables, charts, management tools
• Responsive Design: Mobile-first approach
• Modern UI: Clean, professional medical aesthetic

⚙️ Environment Configuration

Create .env.local file with the following variables:

# Database
MONGODB_URI=mongodb://...

# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# NextAuth
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your_secret_key

# Admin Access (comma-separated emails)
AUTH_ADMINS=admin@example.com,doctor@example.com

# Cloudinary (for image uploads)
CLOUDINARY_CLOUD_NAME=your_cloudinary_cloud_name
CLOUDINARY_API_KEY=your_cloudinary_api_key
CLOUDINARY_API_SECRET=your_cloudinary_api_secret

# Optional (for metadata)
NEXT_PUBLIC_SITE_URL=http://localhost:3000

🚀 Getting Started

Installation

# Install dependencies
npm install

# Start development server
npm run dev

# Open browser
http://localhost:3000

Available Scripts

npm run dev # Start development server
npm run build # Build for production (with Turbopack)
npm run start # Start production server

📊 Key Features Summary

Feature

Description

Public Website

SEO-optimized pages with metadata, Open Graph support

Doctor Directory

Search, filter, and paginate through doctor listings

Review System

Authenticated users can rate and review doctors

User Profiles

Personalized profile management for patients

Doctor Profiles

Professional profile with appointments and reviews

Medical History

Track patient medical records and history

Appointments

Schedule and manage upcoming appointments

Admin Dashboard

Full CRUD operations for users and doctors

Google OAuth

Secure authentication via Google Sign-In

Image Upload

Cloudinary integration for profile pictures

Analytics

Statistics and data visualization

Responsive UI

Mobile-first design with Tailwind CSS

🔧 Technical Highlights

• Server Components: Leverages Next.js 16 RSC (React Server Components)
• API Routes: RESTful backend within Next.js app
• Type Safety: Full TypeScript coverage
• Database: MongoDB with Mongoose schema validation
• Session Management: NextAuth with JWT sessions
• Optimizations: Next.js automatic code splitting, image optimization
• SEO: Meta tags, Open Graph, Twitter cards configured
• Error Handling: Server and client-side error boundaries

✅ Deployment Checklist

• Set all environment variables on hosting platform
• Verify MongoDB connection
• Configure Google OAuth redirect URI for production domain
• Set NEXTAUTH_URL to production URL
• Set NEXT_PUBLIC_SITE_URL to production URL
• Verify AUTH_ADMINS emails
• Test Cloudinary upload integration
• Run npm run build successfully
• Test authentication flow
• Verify admin access control
• Check SEO metadata and Open Graph images
• Test responsive design on mobile devices

🐛 Common Issues & Solutions

1. Windows Development (ENOENT errors)

Issue: .next/static/development/_buildManifest.js.tmp.* errors Solution:

• Delete .next folder
• Restart dev server: npm run dev

2. Mongoose MissingSchemaError

Issue: Schema not found during populate Solution: Import required models in route file before using populate

3. ObjectId Serialization

Issue: Passing MongoDB ObjectId to Client Components Solution: Convert to string: String(doc._id)

📈 Future Enhancements

• Automated testing suite (API + UI tests)
• Input validation schemas (Zod/Yup)
• Audit logging for admin actions
• Rate limiting for public endpoints
• CI/CD pipeline integration
• Email notifications for appointments
• Real-time chat system
• Advanced search filters
• Multi-language support (i18n)
• Export reports (PDF/CSV)

📞 Support & Documentation

For detailed setup instructions and troubleshooting, refer to:

• README.md - Quick start guide
• PROJECT_GUIDE_EN.md - Comprehensive English guide
• PROJECT_GUIDE_AR.md - Comprehensive Arabic guide
• Official Next.js documentation: https://nextjs.org/docs

Built with: Next.js 16, TypeScript, MongoDB, NextAuth, Tailwind CSS, shadcn/ui, MUI, Chart.js, Cloudinary