🏥 MediConnect — Doctor Appointment Booking System

Tagline: Bridging Doctors and Patients Anytime, Anywhere.

A full-stack Java application to manage online & offline doctor appointments, including doctor verification, emergency bookings, health history, ratings/reviews, video consultations, and payments. Designed to start as a well-structured monolith and evolve into microservices.

📚 Table of Contents

Project Overview
Tech Stack
Core Roles & Responsibilities
Feature Matrix
Domain Model Overview
API Standards
Authentication & Authorization
API Endpoints (Overview)
Error Handling & Responses
Logging, Auditing & Monitoring
Transactions, Concurrency & Performance
Versioning & Deprecation
Environment & Configuration
Backend Setup & Run
Contribution & Branching
Coding Standards & Docs
Roadmap to Microservices

🎯 Project Overview

MediConnect enables:

Doctors to register, manage their profiles, availability, certifications, and consult patients.
Customers (Patients) to discover doctors, book/reschedule/cancel appointments, view health history, leave ratings.
Super Admin to verify doctors, manage platform data, handle escalations, analytics, and compliance.

🧰 Tech Stack

Backend: Java 17, Spring Boot (Web, Validation, Security), Spring Data JPA, Lombok
Database: PostgreSQL, Flyway/Liquibase (migrations)
Auth: JWT (access + refresh), Spring Security RBAC
Docs: SpringDoc OpenAPI (Swagger UI)
Messaging/Async: Spring Events / (later) Kafka/RabbitMQ
Frontend: React, Bootstrap (later Tailwind optional)
DevOps: Docker, Docker Compose, GitHub Actions (CI), Logback

👤 Core Roles & Responsibilities

1) Customer (Patient)

Register/login, manage profile
Search/filter doctors by specialization, rating, location, availability
Book/reschedule/cancel appointments (online/offline)
Request emergency appointment
Maintain & view health history, upload reports
Rate & review doctors
Join video consultation, make payments

2) Doctor

Register/login, submit certifications & degrees
Manage profile, specializations, clinic locations
Set availability slots & fees
Approve/decline appointments (optional policy)
Start video session for online consults
View patient history and add medical notes/prescriptions

3) Super Admin

Verify/reject doctors (KYC, certification checks)
Manage users, roles, and platform configurations
Moderate reviews, handle escalations
View system analytics, audit logs
Manage global catalogs (specializations, hospitals/clinics)

✅ Feature Matrix

Feature	Customer	Doctor	Super Admin
Registration & Login	✅	✅	✅
Profile Management	✅	✅	✅
Doctor Discovery & Search	✅	❌	✅
Appointment Booking	✅	✅ (manage slots)	✅ (override)
Emergency Appointment	✅	✅ (receive)	✅
Health History & Reports	✅	✅ (view/add notes)	✅
Ratings & Reviews	✅	✅ (respond)	✅ (moderate)
Video Consultation	✅	✅	❌
Payments	✅	✅ (settlements view)	✅
Doctor Verification	❌	✅ (submit docs)	✅
Admin Analytics & Audit	❌	❌	✅

🧩 Domain Model Overview

User (abstract) → Patient, Doctor, Admin
Doctor: id, name, specialties, certifications, clinics, fees, availability, status (PENDING/VERIFIED/REJECTED)
Patient: id, name, contact, healthRecords, paymentMethods
Appointment: id, doctorId, patientId, type (ONLINE/OFFLINE/EMERGENCY), status (BOOKED/CONFIRMED/CANCELLED/COMPLETED), schedule, paymentStatus
AvailabilitySlot: doctorId, date, startTime, endTime, capacity
HealthRecord: patientId, files, notes, prescriptions
Review: patientId, doctorId, rating (1–5), comment, createdAt
VideoSession: appointmentId, sessionId, signalingUrl
Payment: appointmentId, amount, currency, provider, status
Certification: doctorId, fileUrl, verifiedBy, verifiedAt, status

Use UUIDs for identifiers and timestamps in ISO-8601.

📏 API Standards

Base URL: /api/v1
Content Type: application/json
Auth: Bearer JWT (access token); Refresh token for renewal
Pagination: page, size; Sorting: sort=field,asc|desc
Filtering: Query params (e.g., specialization, city, ratingGte)
Idempotency: For payments & emergency booking via Idempotency-Key header
Time Format: ISO-8601 (UTC)

🔐 Authentication & Authorization

Roles: ROLE_PATIENT, ROLE_DOCTOR, ROLE_SUPER_ADMIN

Access token TTL: 15 min; Refresh token TTL: 7 days (configurable)
Secure endpoints via RBAC; sensitive actions require ownership checks (patient/doctor must match resource owner)
Password hashing: BCrypt
Account states: ACTIVE, SUSPENDED, DELETED (soft delete)

Auth Flow

Register → Email verification (optional) → Login
Login → Issue access + refresh tokens
Use access token in Authorization: Bearer <token> header
Refresh token endpoint to renew access

🔗 API Endpoints (Overview)

Detailed examples below show request/response bodies. Prefix all paths with /api/v1.

1) Auth & Users

POST /auth/register/patient
POST /auth/register/doctor
POST /auth/login
POST /auth/refresh
POST /auth/logout
GET /users/me (profile of logged-in user)
PATCH /users/me (update profile)

Example: Register Doctor

{
  "fullName": "Dr. Aditi Sharma",
  "email": "aditi@example.com",
  "password": "Secure@123",
  "phone": "+91-9999999999",
  "specializations": ["Cardiology"],
  "clinics": [{"name": "City Heart", "city": "Noida"}]
}

Example: Login Response

{
  "accessToken": "<jwt>",
  "refreshToken": "<jwt>",
  "expiresIn": 900,
  "tokenType": "Bearer"
}

2) Doctor Management

GET /doctors (list/search)
GET /doctors/{id}
PATCH /doctors/{id} (self)
POST /doctors/{id}/availability (create slots)
GET /doctors/{id}/availability?date=2025-01-01
POST /doctors/{id}/certifications (upload metadata)
GET /doctors/{id}/reviews

Search Example: /doctors?specialization=Cardiology&city=Noida&ratingGte=4.5&page=0&size=20

Create Availability Slot

{
  "date": "2025-01-05",
  "startTime": "10:00",
  "endTime": "13:00",
  "capacity": 8,
  "type": "OFFLINE"
}

3) Patient (Customer)

GET /patients/{id} (self)
PATCH /patients/{id} (self)
GET /patients/{id}/health-records
POST /patients/{id}/health-records
GET /patients/{id}/appointments

Add Health Record

{
  "title": "Blood Test Report",
  "notes": "High LDL",
  "fileUrl": "s3://reports/ldl-123.pdf"
}

4) Appointments

POST /appointments (book)
GET /appointments/{id}
PATCH /appointments/{id}/reschedule
PATCH /appointments/{id}/cancel
PATCH /appointments/{id}/confirm (doctor/admin)
PATCH /appointments/{id}/complete (doctor)
POST /appointments/emergency (priority booking)

Book Appointment

{
  "doctorId": "uuid-doctor",
  "patientId": "uuid-patient",
  "type": "ONLINE",
  "scheduledAt": "2025-01-05T10:30:00Z",
  "notes": "Chest pain"
}

Appointment Response

{
  "id": "uuid-apt",
  "status": "BOOKED",
  "paymentStatus": "PENDING",
  "videoSession": null
}

Emergency Booking

{
  "patientId": "uuid-patient",
  "symptoms": "Severe headache",
  "preferredSpecialization": "Neurology"
}

5) Payments

POST /payments/intent (create payment intent/order)
POST /payments/webhook (provider callback)
GET /payments/{appointmentId} (status)

Payment Intent

{
  "appointmentId": "uuid-apt",
  "amount": 899.00,
  "currency": "INR",
  "provider": "razorpay"
}

6) Reviews & Ratings

POST /reviews (patient → doctor)
GET /reviews?doctorId=...
PATCH /reviews/{id} (owner or admin)
DELETE /reviews/{id} (owner or admin)

Create Review

{
  "doctorId": "uuid-doctor",
  "rating": 5,
  "comment": "Very attentive and helpful!"
}

7) Video Consultation

POST /video/sessions (create for appointment)
GET /video/sessions/{appointmentId}
POST /video/sessions/{appointmentId}/start (doctor)
POST /video/sessions/{appointmentId}/end

Create Session

{
  "appointmentId": "uuid-apt",
  "provider": "webrtc",
  "signalingUrl": "wss://signal.mediconnect.app/session/uuid"
}

8) Admin & Verification

GET /admin/doctors?status=PENDING
PATCH /admin/doctors/{id}/verify (approve/reject)
GET /admin/users (list)
PATCH /admin/users/{id}/suspend
GET /admin/analytics
GET /admin/audit-logs

Verify Doctor

{
  "status": "VERIFIED",
  "remarks": "Certification validated",
  "verifiedBy": "admin-uuid"
}

9) Notifications

POST /notifications (send to user)
GET /notifications?userId=...
PATCH /notifications/{id}/read

🚨 Error Handling & Responses

Standard error envelope:

{
  "timestamp": "2025-01-05T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "code": "VALIDATION_FAILED",
  "message": "scheduledAt must be in the future",
  "path": "/api/v1/appointments"
}

Use meaningful code values: AUTH_FAILED, ACCESS_DENIED, NOT_FOUND, CONFLICT, RATE_LIMITED.
Validation errors return field-level details.

🧾 Logging, Auditing & Monitoring

Logback: JSON logs with correlation id (X-Request-Id) and user id
Levels: INFO (business events), WARN (soft errors), ERROR (exceptions), DEBUG (dev)
Audit: Record critical actions (login, booking, cancel, payment, verification)
Metrics: Expose /actuator (health, metrics). Add Prometheus later.

⚙️ Transactions, Concurrency & Performance

Transactional Booking: Check slot availability → lock/update capacity → create appointment → emit notification (async)
Optimistic Locking: On AvailabilitySlot with version field to avoid double-booking
Multithreading: Async email/SMS notifications; video session provisioning
Caching: Frequently accessed catalogs (specializations)
Rate Limiting: Emergency booking & payment intent endpoints

🔁 Versioning & Deprecation

URI versioning: /api/v1 (default), future /api/v2 for breaking changes
Deprecation: Include Deprecation and Sunset headers when deprecating endpoints; document migration

🔧 Environment & Configuration

Environment variables (application.yml override via env):

server:
  port: 8080
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/mediconnect
    username: mediconnect
    password: changeme
  jpa:
    hibernate:
      ddl-auto: validate
    properties:
      hibernate:
        format_sql: true
jwt:
  issuer: mediconnect
  accessTokenTtlMinutes: 15
  refreshTokenTtlDays: 7
logging:
  level:
    root: INFO

▶️ Backend Setup & Run

Prerequisites: Java 17, Maven, PostgreSQL, Docker (optional)
Database: Create DB mediconnect and user
Run Migrations: Configure Flyway/Liquibase
Start: mvn spring-boot:run or Docker Compose
API Docs: Swagger UI at http://localhost:8080/swagger-ui.html

🤝 Contribution & Branching

Default branches: main (stable), dev (integration)
Feature branches: feature/backend-auth, feature/backend-appointments, feature/frontend-ui, feature/payments
Workflow: Branch from dev → PR → Code Review → Merge → Release to main
Commit convention: Conventional Commits (feat:, fix:, docs:, refactor:)
PR checklist: Tests pass, Swagger updated, Javadoc added, logging in place

✍️ Coding Standards & Docs

Java: Clean Architecture (Controller → Service → Repository), DTOs, validation annotations, global exception handler
Comments: Javadoc for public classes/methods; inline comments for non-obvious logic
API Docs: OpenAPI annotations; generate HTML if needed
Security: Never log secrets/tokens; mask PII in logs

🧭 Roadmap to Microservices

Phase after prototype:

Extract Auth Service, Appointment Service, Notification Service
Use Spring Cloud Gateway, Eureka for service discovery
Centralized config via Spring Cloud Config
Async communication via Kafka/RabbitMQ
Observability: Zipkin/Jaeger for tracing

📄 License

MIT — use freely with attribution.

🗂 Suggested Repo Structure (for reference)

/doctor-appointment-system
├── backend
│   ├── src/main/java/com/mediconnect
│   │   ├── controller
│   │   ├── service
│   │   ├── repository
│   │   ├── entity
│   │   ├── dto
│   │   ├── security
│   │   └── exception
│   ├── src/main/resources
│   │   ├── application.yml
│   │   └── logback.xml
│   └── pom.xml
├── frontend
│   ├── src
│   │   ├── components
│   │   ├── pages
│   │   └── services
│   └── package.json
└── docs
    ├── API-specifications.md
    └── architecture-diagram.png

🧪 Testing Strategy (Backend)

Unit Tests: JUnit + Mockito for services
Integration: Testcontainers (PostgreSQL) for repositories
API Tests: Spring MVC test for controllers
Security Tests: Access control per role

🛡️ Data Privacy & Compliance

Store minimal PII; encrypt sensitive fields where applicable
Role-based access to health records; audit access
GDPR-like principles (consent, right to delete/export health records)

📬 Support & Contact

For issues, open a GitHub Issue or contact the maintainers.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.mvn/wrapper		.mvn/wrapper
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
Important.md		Important.md
README.md		README.md
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml

Folders and files

Latest commit

History

Repository files navigation