DOC INTEL

A comprehensive, modern healthcare management platform built with Next.js 15, designed to streamline hospital operations, patient care, and administrative workflows. This system provides role-based access control for multiple user types including administrators, doctors, nurses, patients, lab technicians, and cashiers.

🚀 Features

Multi-Role System

• Admin Dashboard: Complete system oversight, user management, analytics, and configuration
• Doctor Portal: Patient management, appointment scheduling, medical records, diagnosis, and prescriptions
• Patient Portal: Appointment booking, medical history access, doctor ratings, and profile management
• Nurse Interface: Patient care coordination, vital signs recording, and medical record updates
• Lab Technician: Lab test management, results entry, and service tracking
• Cashier: Billing, payment processing, and financial record management

Core Functionality

• Appointment Management: Schedule, reschedule, cancel, and track appointments with real-time status updates
• Patient Records: Comprehensive medical history, allergies, conditions, insurance information, and emergency contacts
• Doctor Profiles: Specializations, availability schedules, ratings, reviews, and working hours
• Medical Records: Diagnosis, prescriptions, lab requests, treatment plans, and vital signs tracking
• Billing & Payments: Invoice generation, payment processing (cash/card), receipt management, and financial reporting
• Analytics Dashboard: Visual charts and statistics for appointments, revenue, patient demographics, and system usage
• Rating System: Patient feedback and doctor performance ratings
• Audit Logging: Track all system actions for compliance and security

🛠️ Tech Stack

Frontend

• Framework: Next.js 16.1.1 with App Router
• UI Library: React 19
• Styling: Tailwind CSS 4 with custom animations
• UI Components: Radix UI primitives with shadcn/ui styling
• Icons: Lucide React
• Charts: Recharts for data visualization
• Forms: React Hook Form with Zod validation
• Notifications: Sonner toast notifications

Backend & Database

• Database: PostgreSQL
• ORM: Prisma 6.4.1
• Authentication: Clerk with role-based access control
• Date Handling: date-fns

Development Tools

• Package Manager: npm
• Linting: ESLint (Next.js configuration)
• Database Seeding: Faker.js for test data generation

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Node.js: Version 18.17 or higher
• npm: Version 9 or higher
• PostgreSQL: Version 14 or higher
• Git: For version control

🔧 Installation

1. Clone the Repository

git clone <repository-url>
cd DOC_INTEL

2. Install Dependencies

npm install

3. Environment Variables Setup

Create a .env file in the root directory with the following variables:

# Database Configuration
DATABASE_URL="postgresql://username:password@localhost:5432/healthcare_db?schema=public"

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key
CLERK_SECRET_KEY=your_clerk_secret_key

# Clerk URLs (adjust based on your domain)
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/

# Application URL (for production)
NEXT_PUBLIC_APP_URL=http://localhost:3000

Important Notes:

• Replace username, password, and database name in DATABASE_URL with your PostgreSQL credentials
• Get Clerk API keys from Clerk Dashboard
• Configure Clerk metadata to include user roles (admin, doctor, patient, nurse, lab_technician, cashier)

4. Database Setup

Create PostgreSQL Database

# Login to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE healthcare_db;

# Exit PostgreSQL
\q

Run Prisma Migrations

# Generate Prisma Client
npx prisma generate

# Run database migrations
npx prisma migrate dev --name init

# (Optional) Seed database with sample data
npx prisma db seed

5. Configure Clerk Roles

In your Clerk Dashboard:

1. Navigate to Users & Authentication → Metadata
2. Add custom metadata field: role
3. Assign roles to users: admin, doctor, patient, nurse, lab_technician, or cashier

Example metadata structure:

{
  "role": "admin"
}

🚀 Development

Run Development Server

npm run dev

Open http://localhost:3000 in your browser.

Build for Production

npm run build

Start Production Server

npm run start

Lint Code

npm run lint

🌐 Deployment

Deploy to Vercel

This project is optimized for deployment on Vercel.

Prerequisites

1. Create a Vercel account
2. Install Vercel CLI (optional): npm i -g vercel
3. Set up a PostgreSQL database (recommended: Vercel Postgres or Supabase)

Deployment Steps

Option 1: Deploy via Vercel Dashboard (Recommended)

1. Push your code to GitHub/GitLab/Bitbucket
2. Go to Vercel Dashboard
3. Import your repository
4. Configure environment variables (see below)
5. Deploy!

Option 2: Deploy via Vercel CLI

# Login to Vercel
vercel login

# Deploy
vercel

# Deploy to production
vercel --prod

Environment Variables for Vercel

Add these environment variables in your Vercel project settings:

# Database (use your production PostgreSQL URL)
DATABASE_URL=postgresql://user:password@host:port/database?schema=public

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_xxxxx
CLERK_SECRET_KEY=sk_live_xxxxx
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/

# Application URL (your Vercel domain)
NEXT_PUBLIC_APP_URL=https://your-app.vercel.app

Post-Deployment Setup

After deployment, run Prisma migrations on your production database:

# Using Vercel CLI
vercel env pull .env.production
npx prisma migrate deploy

# Or connect directly to your production database
DATABASE_URL="your-production-url" npx prisma migrate deploy

Other Deployment Platforms

This Next.js app can also be deployed to:

• Railway: Railway Deployment Guide
• Render: Render Deployment Guide
• AWS Amplify: AWS Amplify Guide
• DigitalOcean App Platform: DigitalOcean Guide

📁 Project Structure

DOC_INTEL/
├── app/                          # Next.js App Router
│   ├── (auth)/                   # Authentication routes (sign-in, sign-up)
│   ├── (protected)/              # Protected routes (role-based access)
│   │   ├── admin/                # Admin dashboard and management
│   │   ├── doctor/               # Doctor portal
│   │   ├── patient/              # Patient portal
│   │   ├── staff/                # Staff (nurse, lab tech, cashier) portal
│   │   └── record/               # Medical records and user management
│   ├── actions/                  # Server actions
│   ├── globals.css               # Global styles
│   ├── layout.js                 # Root layout
│   └── page.js                   # Home page
├── components/                   # React components
│   ├── appointment/              # Appointment-related components
│   ├── charts/                   # Chart components (Recharts)
│   ├── dialogs/                  # Modal dialogs
│   ├── forms/                    # Form components
│   ├── settings/                 # Settings components
│   ├── tables/                   # Data table components
│   └── ui/                       # shadcn/ui components
├── lib/                          # Utility libraries
│   ├── db.js                     # Prisma client instance
│   ├── routes.js                 # Route access control configuration
│   ├── schema.js                 # Zod validation schemas
│   └── utils.js                  # Utility functions
├── prisma/                       # Prisma ORM
│   ├── migrations/               # Database migrations
│   ├── schema.prisma             # Database schema
│   └── seed.js                   # Database seeding script
├── public/                       # Static assets
├── utils/                        # Additional utilities
│   ├── roles.js                  # Role definitions and helpers
│   ├── services/                 # Service layer functions
│   └── settings.js               # Application settings
├── middleware.js                 # Clerk authentication middleware
├── next.config.mjs               # Next.js configuration
└── package.json                  # Dependencies and scripts

🔐 Authentication & Authorization

Clerk Integration

This application uses Clerk for authentication and user management:

• Sign-up/Sign-in: Pre-built authentication UI
• Session Management: Secure session handling
• User Metadata: Custom role assignment via metadata
• Protected Routes: Middleware-based route protection

Role-Based Access Control (RBAC)

The system implements granular access control through middleware (middleware.js) and route configuration (lib/routes.js):

Role	Access Level	Permissions
Admin	Full System Access	User management, system configuration, all records, analytics
Doctor	Medical Staff	Patient records, appointments, diagnosis, prescriptions, staff records
Patient	Personal Access	Own appointments, medical history, doctor ratings, profile
Nurse	Care Coordination	Patient records, vital signs, medical updates, appointments
Lab Technician	Laboratory	Lab tests, results entry, service management
Cashier	Financial	Billing, payments, invoices, financial records

Route Protection

Routes are automatically protected based on user roles. Unauthorized access attempts redirect users to their role-specific dashboard.

🗄️ Database Schema

Key Models (Prisma)

• Patient: Personal info, medical history, allergies, insurance, emergency contacts
• Doctor: Credentials, specialization, availability, working hours, ratings
• Staff: Nurses, lab technicians, cashiers with role-based attributes
• Appointment: Scheduling, status tracking, patient-doctor relationships
• MedicalRecords: Diagnosis, prescriptions, lab requests, treatment plans
• VitalSigns: Body temperature, blood pressure, heart rate, oxygen saturation
• Diagnosis: Symptoms, diagnosis details, medications, follow-up plans
• Payment: Billing, payment methods, receipts, financial tracking
• Rating: Patient feedback and doctor performance reviews
• Services: Medical services catalog with pricing
• LabTest: Laboratory test management and results
• AuditLog: System activity tracking for compliance

Enums

• Role: ADMIN, DOCTOR, PATIENT, NURSE, LAB_TECHNICIAN, CASHIER
• AppointmentStatus: PENDING, SCHEDULED, CANCELLED, COMPLETED
• PaymentStatus: PAID, UNPAID, PART
• Gender: MALE, FEMALE
• Status: ACTIVE, INACTIVE, DORMANT

📊 Key Features Breakdown

Appointment System

• Real-time availability checking
• Conflict prevention
• Status workflow (Pending → Scheduled → Completed/Cancelled)
• Email/SMS notifications (via Clerk)

Medical Records

• HIPAA-compliant data storage
• Comprehensive patient history
• Vital signs tracking
• Lab test integration
• Prescription management

Analytics Dashboard

• Appointment trends
• Revenue analytics
• Patient demographics
• Doctor performance metrics
• System usage statistics

🤝 Contributing

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Commit changes: git commit -m 'Add some feature'
4. Push to branch: git push origin feature/your-feature-name
5. Open a Pull Request

Code Standards

• Follow existing code style and conventions
• Write meaningful commit messages
• Add comments for complex logic
• Update documentation as needed
• Test thoroughly before submitting

🔒 Security

Security Best Practices

This application implements several security measures:

• Authentication: Clerk provides secure, production-ready authentication
• Role-Based Access Control: Middleware-level route protection
• Environment Variables: Sensitive data stored in environment variables
• HTTPS: Always use HTTPS in production
• Database Security: PostgreSQL with SSL connections in production

Security Updates

Important: Always keep dependencies up to date to patch security vulnerabilities.

# Check for outdated packages
npm outdated

# Update all packages to latest versions
npm update

# Update Next.js specifically (recommended)
npm install next@latest react@latest react-dom@latest

Recent Security Fixes

• Next.js 16.1.1: Addresses CVE-2025-66478 (Critical RCE vulnerability)
• React 19: Latest stable version with security patches

Environment Variable Security

Never commit .env files to version control!

• ✅ Use .env.local for local development (gitignored by default)
• ✅ Use Vercel Environment Variables for production
• ✅ Rotate API keys regularly
• ✅ Use different keys for development and production
• ❌ Never expose CLERK_SECRET_KEY or DATABASE_URL publicly

📝 License

This project is private and proprietary. All rights reserved.

🐛 Troubleshooting

Common Issues

Next.js Configuration Warnings

If you see warnings about deprecated configuration options:

# Warning: experimental.serverComponentsExternalPackages is deprecated
# Solution: Already fixed in next.config.mjs using serverExternalPackages

# Warning: swcMinify is deprecated
# Solution: Already removed (enabled by default in Next.js 15+)

Security Vulnerability: CVE-2025-66478

Critical RCE vulnerability in Next.js 15.x. Solution: Update to Next.js 16.1.1+

npm install next@latest react@latest react-dom@latest

Vercel Build Failing: "Cannot find module '@prisma/client'"

This is fixed by the postinstall script in package.json. If you still encounter this:

# Ensure postinstall script exists in package.json
"postinstall": "prisma generate"

# Verify Prisma is in dependencies (not devDependencies)
# Check that DATABASE_URL is set in Vercel environment variables

Database Connection Error

# Verify PostgreSQL is running (local development)
sudo service postgresql status

# Check DATABASE_URL in .env file
# Ensure credentials and database name are correct

# For Vercel: Verify DATABASE_URL is set in environment variables
# Make sure the database allows connections from Vercel IPs

Prisma Client Not Generated

# Generate Prisma Client manually
npx prisma generate

# If using Vercel, this runs automatically via postinstall script

Clerk Authentication Issues

• Verify API keys in .env (development) or Vercel environment variables (production)
• Check Clerk Dashboard for application status
• Ensure user metadata includes role field
• For production, use pk_live_ and sk_live_ keys (not pk_test_)

Build Errors

# Clear Next.js cache
rm -rf .next

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Regenerate Prisma Client
npx prisma generate

Vercel Deployment: Database Migration Issues

# After first deployment, run migrations on production database
DATABASE_URL="your-production-url" npx prisma migrate deploy

# Or use Vercel CLI
vercel env pull .env.production
npx prisma migrate deploy

TypeScript Errors (if using TypeScript in future)

# Regenerate Prisma types
npx prisma generate

# Check for type errors
npm run build

📞 Support

For issues, questions, or contributions, please open an issue in the repository.

---

Built with ❤️ using Next.js 15 and modern web technologies