MedTun - Complete Medical Appointment Platform for Tunisia

MedTun is a comprehensive web application that revolutionizes healthcare access in Tunisia by connecting patients with doctors, specialists, and medical facilities. The platform provides a complete ecosystem for medical appointment management, user administration, and healthcare services discovery.

🚀 Key Features

👥 Multi-Role User System

• Patients: Complete profile management with medical history
• Doctors: Professional profiles with specialties, qualifications, and clinic information
• Administrators: Full system control and management capabilities

📅 Advanced Appointment Management

• Flexible Booking: Book appointments with preferred doctors
• Status Tracking: Real-time appointment status (En attente, Confirmé, Terminé, Annulé)
• Cancellation System: Cancel appointments with detailed reasons
• Complete History: View all past and upcoming appointments

🏥 Doctor Discovery & Management

• Comprehensive Directory: Search doctors by specialty, location, or name
• Detailed Profiles: View doctor qualifications, experience, and clinic information
• Specialty Icons: Consistent visual representation for all medical specialties
• Location-based Search: Find doctors in specific cities

🏪 Pharmacy Locator

• Interactive Map: Find nearby pharmacies with precise locations
• Contact Information: Access pharmacy details and contact info
• Geographic Coverage: Comprehensive pharmacy database across Tunisia

🔐 Security & Authentication

• JWT Authentication: Secure token-based authentication system
• Role-based Access Control: Different permissions for patients, doctors, and admins
• Protected Routes: Secure access to sensitive areas

🛠️ Admin Interface

• Complete System Control: Manage all users, appointments, and system data
• User Management: Create, edit, and delete users of any role
• Appointment Oversight: Monitor and manage all appointments
• Statistics Dashboard: Real-time insights and system analytics
• Bulk Operations: Efficient management of large datasets

🏗️ Technical Architecture

Frontend (React + TypeScript)

• Framework: React 18 with TypeScript for type safety
• Styling: Bootstrap 5 for responsive design and modern UI
• Routing: React Router for seamless navigation
• State Management: React Context for authentication and global state
• API Integration: Axios for HTTP requests with interceptors
• Form Handling: Controlled components with validation

Backend (Spring Boot + Java)

• Framework: Spring Boot 3.x with Java
• Security: Spring Security with JWT authentication
• Database: JPA/Hibernate with MySQL
• API Design: RESTful APIs with proper HTTP status codes
• Architecture: Layered architecture (Controller → Service → Repository)
• Password Security: BCrypt encryption for secure password storage

Database Design

• Relational Model: Well-structured MySQL database
• Entity Relationships: Proper foreign key relationships
• Data Integrity: Constraints and validations
• Performance: Optimized queries and indexing

📁 Project Structure

Frontend Architecture

frontend/
├── public/                    # Static assets
├── src/
│   ├── components/           # Reusable UI components
│   │   ├── admin/           # Admin-specific components
│   │   │   ├── AdminDashboard.tsx
│   │   │   ├── AdminUsersManagement.tsx
│   │   │   ├── AdminAppointmentsManagement.tsx
│   │   │   └── AdminCreateUser.tsx
│   │   ├── layout/          # Layout components
│   │   │   ├── Header.tsx
│   │   │   ├── Footer.tsx
│   │   │   └── Layout.tsx
│   │   └── common/          # Shared components
│   ├── contexts/            # React contexts
│   │   └── AuthContext.tsx  # Authentication state management
│   ├── pages/               # Page components
│   │   ├── admin/           # Admin pages
│   │   ├── auth/            # Authentication pages
│   │   ├── HomePage.tsx
│   │   ├── DoctorsPage.tsx
│   │   ├── AppointmentsPage.tsx
│   │   ├── DashboardPage.tsx
│   │   └── PharmaciesPage.tsx
│   ├── styles/              # Global styles
│   └── types/               # TypeScript definitions
├── package.json
└── tsconfig.json

Backend Architecture

backend/
├── src/
│   ├── main/
│   │   ├── java/com/example/backend/
│   │   │   ├── controller/     # REST endpoints
│   │   │   │   ├── AuthController.java
│   │   │   │   ├── UserController.java
│   │   │   │   ├── AppointmentController.java
│   │   │   │   ├── DoctorController.java
│   │   │   │   └── AdminController.java
│   │   │   ├── model/          # Entity classes
│   │   │   │   ├── User.java
│   │   │   │   ├── Patient.java
│   │   │   │   ├── Doctor.java
│   │   │   │   ├── Admin.java
│   │   │   │   ├── Appointment.java
│   │   │   │   ├── Specialty.java
│   │   │   │   └── Pharmacy.java
│   │   │   ├── repository/     # Data access layer
│   │   │   ├── service/        # Business logic
│   │   │   ├── config/         # Configuration
│   │   │   ├── security/       # Authentication & authorization
│   │   │   └── enums/          # Enumerations
│   │   └── resources/
│   │       ├── application.properties
│   │       └── sample-data/    # Initial data scripts
│   └── test/                   # Test classes
├── pom.xml
└── mvnw.cmd

🛠️ Installation & Setup

Prerequisites

• Node.js 16+ and npm
• Java 11 or higher
• MySQL 8.0+
• Maven (included via wrapper)

Database Setup

1. Create MySQL database:

CREATE DATABASE medtun_db;

2. Update database configuration in backend/src/main/resources/application.properties:

spring.datasource.url=jdbc:mysql://localhost:3306/medtun_db
spring.datasource.username=your_username
spring.datasource.password=your_password

Backend Setup

cd backend
./mvnw clean install
./mvnw spring-boot:run

The API will be available at http://localhost:8080/api

Frontend Setup

cd frontend
npm install
npm start

The application will be available at http://localhost:3000

🔧 Admin Access

Creating Admin User

1. Start the backend server
2. Use your database management tool to insert an admin user:

INSERT INTO users (email, password, role, first_name, last_name, phone_number, created_at, updated_at) 
VALUES ('admin@medtun.com', '$2a$10$encoded_password_hash', 'ADMIN', 'Admin', 'User', '+216 XX XXX XXX', NOW(), NOW());

Accessing Admin Interface

1. Login with admin credentials at http://localhost:3000/login
2. Navigate to http://localhost:3000/admin or click the "Administration" link in the navigation
3. Access complete system management features

🎯 Admin Interface Features

Dashboard

• System Statistics: Total users, appointments, and system metrics
• Real-time Data: Live updates of system status
• Quick Actions: Fast access to common administrative tasks

User Management

• View All Users: Paginated list with role filtering
• Edit Users: Modify user information and roles
• Delete Users: Remove users from the system
• Create Users: Add new patients, doctors, or admins

Appointment Management

• View All Appointments: Complete appointment oversight
• Status Management: Change appointment statuses
• Filter & Search: Find specific appointments quickly
• Bulk Operations: Manage multiple appointments efficiently

🌟 Key Implemented Features

Recent Enhancements

1. Appointment Cancellation System

   • Added cancellation reasons tracking
   • Display cancellation details in appointment history
   • Status management for cancelled appointments

2. Visual Consistency

   • Standardized specialty icons across the platform
   • Consistent UI/UX design patterns
   • Responsive design for all devices

3. Form Optimization

   • Removed duplicate fields in patient registration
   • Streamlined user input processes
   • Enhanced form validation

4. Complete Admin System

   • Full CRUD operations for all entities
   • Role-based access control
   • Comprehensive system monitoring

🔒 Security Features

• JWT Authentication: Secure token-based authentication
• Password Encryption: BCrypt hashing for all passwords
• Role-based Authorization: Different access levels for each user type
• Protected API Endpoints: Secure backend routes
• Input Validation: Frontend and backend validation
• CORS Configuration: Secure cross-origin requests

🚀 API Endpoints

Authentication

• POST /api/auth/login - User login
• POST /api/auth/register - User registration

User Management

• GET /api/users/profile - Get current user profile
• PUT /api/users/profile - Update user profile

Appointments

• GET /api/appointments - Get user appointments
• POST /api/appointments - Create new appointment
• PUT /api/appointments/{id}/cancel - Cancel appointment

Admin Endpoints

• GET /api/admin/dashboard - Get system statistics
• GET /api/admin/users - Get all users with pagination
• POST /api/admin/users - Create new user
• DELETE /api/admin/users/{id} - Delete user
• GET /api/admin/appointments - Get all appointments

🎨 UI/UX Features

• Responsive Design: Works on desktop, tablet, and mobile
• Modern Interface: Clean and intuitive user interface
• Accessibility: WCAG compliant design elements
• Loading States: User feedback during API calls
• Error Handling: Graceful error messages and recovery
• Consistent Branding: Unified design language throughout

🔮 Future Enhancements

• Real-time Notifications: Push notifications for appointments
• Video Consultations: Telemedicine integration
• Payment Gateway: Online payment for consultations
• Mobile App: Native mobile applications
• AI Recommendations: Smart doctor and specialty recommendations
• Multi-language Support: Arabic and French language options

📊 Performance & Scalability

• Optimized Queries: Efficient database operations
• Pagination: Handle large datasets efficiently
• Lazy Loading: Component-based code splitting
• Caching Strategy: Strategic caching for improved performance
• Scalable Architecture: Designed for horizontal scaling

🤝 Contributing

This project follows standard development practices:

• Clean code principles
• Comprehensive error handling
• Proper documentation
• Type safety with TypeScript
• RESTful API design