Files

Iliyan Angelov c15a7bdbde Start

2025-11-16 02:44:17 +02:00

13 KiB

Raw Permalink Blame History

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

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
API Testing: Use Swagger UI for interactive API testing
Logging: Check console logs for detailed application flow
Email Testing: Use a test Gmail account for development

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

13 KiB Raw Permalink Blame History