Start
This commit is contained in:
Iliyan Angelov
425
README.md
Normal file
425
README.md
Normal file
@@ -0,0 +1,425 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user