Telemedicine Platform API

A comprehensive telemedicine platform API built with Spring Boot that enables secure patient-doctor interactions, appointment management, and AI-powered symptom triage services.

Features

• 🔐 JWT-based Authentication & Authorization - Secure user authentication with role-based access control
• 👥 Multi-role User Management - Support for Patients, Doctors, and Admins
• 📅 Appointment Scheduling - Complete appointment lifecycle management
• 🤖 AI-Powered Triage - Intelligent symptom analysis using Google Gemini AI
• 📧 Email Notifications - Automated email notifications for appointments
• 📊 Admin Dashboard - System statistics and audit trail management
• 📝 API Documentation - Interactive Swagger/OpenAPI documentation

Tech Stack

• Framework: Spring Boot 3.5.6
• Language: Java 25
• Database: PostgreSQL
• Security: Spring Security with JWT (jjwt 0.13.0)
• AI Integration: Google Gemini API 1.23.0
• Email: Spring Boot Starter Mail (Gmail SMTP)
• Migration: Flyway 11.13.1
• Mapping: MapStruct 1.6.3
• Validation: Spring Boot Starter Validation
• Documentation: SpringDoc OpenAPI 2.8.13
• Configuration: Spring DotEnv 4.0.0
• Build Tool: Maven
• Testing: JUnit 5, Mockito, Spring Boot Test

Prerequisites

• Java 17 or higher (Java 25 recommended)
• PostgreSQL 12 or higher
• Maven 3.6+
• Gmail account (for email notifications)
• Google Gemini API key

Getting Started

1. Clone the Repository

git clone <repository-url>
cd telemedicine

2. Database Setup

Create a PostgreSQL database:

CREATE DATABASE telemedicine;

The database schema will be automatically created by Flyway migrations when you first run the application.

Database Migrations

The project uses Flyway for database version control. Migrations are located in src/main/resources/db/migration/:

• V1__initial_migration.sql - Creates the users table with UUID support
• V2__add_patients_and_doctors.sql - Creates patients and doctors tables
• V3__add_appointments.sql - Creates appointments table
• V4__add_ai_triage_audits.sql - Creates ai_triage_audits table

Migrations run automatically on application startup. To manually run Flyway commands:

# Run migrations
mvn flyway:migrate

# Get migration status
mvn flyway:info

# Clean database (⚠️ WARNING: Deletes all data)
mvn flyway:clean

# Repair migration history
mvn flyway:repair

Note: Update database credentials in pom.xml under the flyway-maven-plugin configuration if needed.

3. Environment Configuration

Create a .env file in the project root (use .env.example as template):

JWT_SECRET=your-secret-key-at-least-32-characters
MAIL_USERNAME=your-gmail@gmail.com
MAIL_PASSWORD=your-app-specific-password
GEMINI_API_KEY=your-gemini-api-key

Note: For Gmail, you need to generate an App Password instead of using your regular password.

4. Application Configuration

Update src/main/resources/application.yml with your database credentials:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/telemedicine
    username: postgres
    password: your-password

5. Build and Run

# Build the project
mvn clean install

# Run the application
mvn spring-boot:run

The application will start on http://localhost:8080

6. Access API Documentation

Once the application is running, visit:

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI Docs: http://localhost:8080/v3/api-docs

API Overview

Authentication Endpoints

Method	Endpoint	Description	Auth Required
POST	/auth/login	User login	No
POST	/users/register/doctor	Register as doctor	No
POST	/users/register/patient	Register as patient	No
POST	/users/register/admin	Register as admin	No*

*Admin registration requires email to match configured admin email

Appointment Endpoints

Method	Endpoint	Description	Role
GET	/appointments/patient/{id}	Get patient appointments	Authenticated
GET	/appointments/doctor/{id}	Get doctor appointments	Authenticated
POST	/appointments	Create appointment	DOCTOR
PATCH	/appointments/{id}/cancel	Cancel appointment	Authenticated
PATCH	/appointments/{id}/confirm	Confirm appointment	Authenticated
PATCH	/appointments/{id}/complete	Complete appointment	Authenticated
DELETE	/appointments/{id}	Delete appointment	ADMIN

AI Triage Endpoints

Method	Endpoint	Description	Role
POST	/ai/triage/analyze	Analyze patient symptoms	DOCTOR
POST	/ai/triage/quick-analyze	Quick analysis (no patient ID)	DOCTOR

Admin Endpoints

Method	Endpoint	Description
GET	/admin/users	Get all users
GET	/admin/patients	Get all patients
GET	/admin/doctors	Get all doctors
GET	/admin/stats	Get system statistics
GET	/admin/triages	Get AI triage audits
GET	/admin/triage-audits/patient/{id}	Get patient triage audits
GET	/admin/triage-audits/urgency/{level}	Get audits by urgency
PATCH	/admin/users/{email}/activate	Activate user
PATCH	/admin/users/{email}/deactivate	Deactivate user
PATCH	/admin/doctors/{license}/verify	Verify doctor
PATCH	/admin/doctors/{license}/unverify	Unverify doctor
DELETE	/admin/users/{email}	Delete user

User Roles

PATIENT

• Book and manage appointments
• Use AI triage services (via doctor)
• View personal appointment history

DOCTOR

• Create and manage appointments
• Access AI symptom triage tools
• View patient appointment history
• Analyze patient symptoms

ADMIN

• Full system access
• User management (activate/deactivate/delete)
• Doctor verification
• View system statistics
• Access AI triage audit logs

Database Schema

The application uses Flyway migrations to manage the database schema. The following tables are created:

Core Tables

users (V1__initial_migration.sql)

• Core user information for all user types
• Fields: id (UUID), email, password (encrypted), role, first_name, last_name, phone_number, is_active, created_at, updated_at
• Unique constraint on email
• Uses UUID extension for primary keys

patients (V2__add_patients_and_doctors.sql)

• Patient-specific data
• Fields: id (UUID), user_id (FK to users), emergency_contact_name, emergency_contact_phone, blood_type, allergies (array), created_at
• Blood type validation: A+, A-, B+, B-, AB+, AB-, O+, O-
• CASCADE delete on user deletion

doctors (V2__add_patients_and_doctors.sql)

• Doctor-specific data
• Fields: id (UUID), user_id (FK to users), medical_license_number (unique), specialization, years_of_experience, biography, consultation_fee, is_verified, created_at
• CASCADE delete on user deletion

appointments (V3__add_appointments.sql)

• Appointment scheduling and management
• Fields: id (UUID), patient_id (FK), doctor_id (FK), scheduled_date, scheduled_time, duration_minutes, status, created_at
• Status values: SCHEDULED, CANCELLED, CONFIRMED, COMPLETED
• CASCADE delete on patient/doctor deletion

ai_triage_audits (V4__add_ai_triage_audits.sql)

• AI analysis audit trail
• Fields: id (UUID), patient_id (FK), user_input (symptoms), ai_output (analysis), urgency_level, created_at
• Urgency levels: LOW, MEDIUM, HIGH, EMERGENCY
• CASCADE delete on patient deletion

Database Relationships

users (1) ←→ (1) patients
users (1) ←→ (1) doctors
patients (1) ←→ (∞) appointments
doctors (1) ←→ (∞) appointments
patients (1) ←→ (∞) ai_triage_audits

Migration Management

To view the current migration status:

mvn flyway:info

To apply pending migrations:

mvn flyway:migrate

All migrations are idempotent and safe to run multiple times.

Project Structure

telemedicine/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/gnx/telemedicine/
│   │   │       ├── config/            # Configuration(Swagger UI)
│   │   │       ├── controller/        # REST controllers
│   │   │       ├── dto/               # Data Transfer Objects
│   │   │       ├── exception/         # Custom exceptions
│   │   │       ├── mappers/           # MapStruct mappers
│   │   │       ├── model/             # JPA entities
│   │   │       ├── repository/        # Spring Data repositories
│   │   │       ├── security/          # Security configuration
│   │   │       └── service/           # Business logic
│   │   └── resources/
│   │       ├── db/migration/          # Flyway migrations
│   │       └── application.yml        # Application configuration
│   └── test/                          # Test files
├── .env                               # Environment variables
├── .env.example                       # Example for .env file
├── .gitignore
├── pom.xml                            # Maven configuration
└── README.md

AI Triage System

The AI triage system uses Google Gemini to analyze patient symptoms and provides:

• Urgency Level: LOW, MEDIUM, HIGH, EMERGENCY
• Recommended Specialty: Suggested medical specialty
• Key Questions: Follow-up questions for doctors
• Triage Notes: Analysis summary
• Audit Trail: All analyses are logged for review

Example Triage Request

{
  "patientId": "uuid-here",
  "symptomDescription": "Patient experiencing chest pain and shortness of breath"
}

Example Response

{
  "patientId": "uuid-here",
  "urgency": "EMERGENCY",
  "recommendedSpecialty": "Cardiology",
  "keyQuestions": [
    "When did symptoms start?",
    "Any history of heart disease?"
  ],
  "triageNotes": "Severe symptoms requiring immediate attention",
  "disclaimer": "AI analysis for triage assistance only. Not medical advice."
}

Email Notifications

The system automatically sends email notifications for:

• Appointment confirmations (to both patient and doctor)
• Appointment cancellations
• Status updates

Testing

Run the test suite:

# Run all tests
mvn test

# Run with coverage
mvn test jacoco:report

The project includes:

• Unit tests for services
• Integration tests for controllers
• Repository tests
• Security tests

Security

• Passwords are encrypted using BCrypt
• JWT tokens expire after 24 hours (configurable)
• Role-based access control (RBAC)
• CSRF protection disabled for REST API
• Stateless session management

Error Handling

The API uses standard HTTP status codes:

• 200 - Success
• 201 - Created
• 204 - No Content
• 400 - Bad Request (validation errors)
• 401 - Unauthorized (authentication required)
• 403 - Forbidden (insufficient permissions)
• 500 - Internal Server Error

All errors return a consistent JSON format:

{
  "status": "400",
  "error": "Error Type",
  "message": "Detailed error message",
  "timestamp": "2025-10-22T10:30:00"
}

Configuration Properties

Key application properties in application.yml:

jwt:
  secret: ${JWT_SECRET}      # JWT signing key
  expiration: 86400          # Token expiration (seconds)

gemini:
  api-key: ${GEMINI_API_KEY} # Google Gemini API key

spring:
  mail:
    host: smtp.gmail.com
    port: 587
    username: ${MAIL_USERNAME}
    password: ${MAIL_PASSWORD}

Development Tips

1. Database Migrations:

   • Flyway automatically runs migrations on startup
   • Never modify existing migration files
   • Create new migration files with format: V{version}__{description}.sql
   • Check migration status: mvn flyway:info

2. API Testing: Use Swagger UI for interactive API testing

3. Logging: Check console logs for detailed application flow

4. Email Testing: Use a test Gmail account for development

5. Maven Compilation: The project uses annotation processors for Lombok and MapStruct

   # Clean build
   mvn clean install
   
   # Skip tests during build
   mvn clean install -DskipTests
   

License

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

Author

GNX Soft LTD

• Email: sales@gnxsoft.com