425 lines
13 KiB
Markdown
425 lines
13 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd telemedicine
|
|
```
|
|
|
|
### 2. Database Setup
|
|
|
|
Create a PostgreSQL database:
|
|
|
|
```sql
|
|
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:
|
|
|
|
```bash
|
|
# 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):
|
|
|
|
```properties
|
|
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](https://support.google.com/accounts/answer/185833) instead of using your regular password.
|
|
|
|
### 4. Application Configuration
|
|
|
|
Update `src/main/resources/application.yml` with your database credentials:
|
|
|
|
```yaml
|
|
spring:
|
|
datasource:
|
|
url: jdbc:postgresql://localhost:5432/telemedicine
|
|
username: postgres
|
|
password: your-password
|
|
```
|
|
|
|
### 5. Build and Run
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
mvn flyway:info
|
|
```
|
|
|
|
To apply pending migrations:
|
|
|
|
```bash
|
|
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
|
|
|
|
```json
|
|
{
|
|
"patientId": "uuid-here",
|
|
"symptomDescription": "Patient experiencing chest pain and shortness of breath"
|
|
}
|
|
```
|
|
|
|
### Example Response
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```json
|
|
{
|
|
"status": "400",
|
|
"error": "Error Type",
|
|
"message": "Detailed error message",
|
|
"timestamp": "2025-10-22T10:30:00"
|
|
}
|
|
```
|
|
|
|
## Configuration Properties
|
|
|
|
Key application properties in `application.yml`:
|
|
|
|
```yaml
|
|
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
|
|
```bash
|
|
# 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](LICENSE) file for details.
|
|
|
|
## Author
|
|
|
|
**GNX Soft LTD**
|
|
- Email: sales@gnxsoft.com |