How zade-samir/healthcare-full works
1. This repository is a split-system healthcare platform with two major halves: a React/Vite frontend and a Spring Boot microservices backend. The backend is the core of the architecture and is organized as independent deployable services, each with its own codebase, security layer, data model, and PostgreSQL database.
2. The backend entry point for all client traffic is the API Gateway on port 8080. It is the only public routing surface for business APIs, and it distinguishes open routes (/auth/register, /auth/login, /eureka/**) from secured routes. For secured requests it validates the JWT, then forwards traffic to downstream services and injects an internal trust header (X-Internal-Secret).
3. Eureka Server on port 8761 provides service discovery. The gateway and the Feign-based service-to-service calls rely on Eureka-backed logical service names rather than hardcoded host/port addresses. This is what makes the system dynamically routable and horizontally scalable.
4. Auth Service on port 9000 owns identity and token issuance. It manages the User and Role model, handles registration with role-specific codes for admin/doctor creation, and issues JWTs after Spring Security authentication. The JWT utility is shared conceptually across services as the common authentication token format.
5. The domain services are split by business ownership:
- Patient Service: patient profiles and soft delete
- Doctor Service: doctor profiles, availability, specialization filters, soft delete
- Appointment Service: booking and appointment status lifecycle
- Medical Record Service: diagnoses and prescriptions after appointments
- Billing Service: bill generation and payment tracking
6. Each domain service follows the same internal layering: controller → service interface/impl → repository, with DTOs mapped to entities via MapStruct-style mapper classes. This keeps API contracts separate from persistence models and makes each service self-contained.
7. The data boundary is strict: every microservice has its own PostgreSQL database (authDB, patientDB, doctorDB, appointmentDB, billingDB, medicalRecordsDB). There are no cross-service database joins or shared schemas. Relationships such as appointment.patientId or billing.appointmentId are logical references, not physical foreign keys across databases.
8. Inter-service communication is synchronous and mostly validation-oriented, using OpenFeign clients. Appointment Service calls Patient and Doctor services before creating an appointment; Medical Record Service validates patient and doctor existence before saving a record; Billing Service calls Appointment and Patient services to verify billing eligibility and fraud conditions. These calls are protected with Resilience4j circuit breakers so a downstream outage degrades gracefully instead of cascading.
9. Security is layered:
- gateway-level JWT validation on incoming secured requests
- service-level JWT filters that re-validate the token and populate the Spring Security context
- method-level role checks on controllers/services
- internal-secret header to discourage direct calls that bypass the gateway
This creates a defense-in-depth boundary around every service.
10. Billing is the one service that connects to an external payment provider. It contains Razorpay-specific configuration and a RazorpayService, so payment processing is not purely internal state management; it also orchestrates an outbound integration to a third-party payment API.
11. The frontend is a role-aware single-page app built with React. Its structure mirrors the backend domains: admin dashboards, doctor screens, patient screens, appointment pages, records pages, billing pages, and auth pages. AuthContext, ProtectedRoute, and role-specific sidebars indicate that frontend routing is also gated by auth state and user role.
12. Operationally, the services are intended to start in dependency order: Eureka first, then the gateway, then the domain services. The frontend calls the backend only through the gateway, so the architecture diagram should show browser/client traffic entering at the frontend, then the gateway, then fan-out to individual services, with Eureka sitting as the discovery backbone and PostgreSQL isolated behind each service.
Main entry points: ApiGatewayApplication.java API Gateway · BillingServiceApplication.java Billing Service · AppointmentServiceApplication.java Appointment Service · PatientServiceApplication.java Patient Service
Components 20
Frontend
React/Vite single-page app with role-aware routing and page shells.
- Browser · User traffic enters the system here.
- React SPA · Vite/React application with role-specific pages and layouts.
HealthCare-Frontend/src/App.jsx - Auth Context · Holds login state, role, and session-aware UI behavior.
HealthCare-Frontend/src/context/AuthContext.jsx - Protected Route · Blocks unauthorized navigation based on auth state and role.
HealthCare-Frontend/src/components/ProtectedRoute.jsx - API Client · Frontend backend access layer used by pages and features.
HealthCare-Frontend/src/services/api.js
Backend Platform
Spring Boot microservices, discovery, gateway, and security boundary.
- API Gateway · Single public backend entry point; validates JWT, routes open and secured traffic, and adds internal trust headers.
HealthCare-Backend/api-gateway/src/main/java/com/healthcare/api_gateway/ApiGatewayApplication.java - Eureka Server · Service discovery backbone for gateway and Feign clients.
HealthCare-Backend/eureka-server/src/main/java/com/healthcare/eureka_server/EurekaServerApplication.java
Domain Services
Business-owned microservices with isolated data and synchronous Feign calls.
- Auth Service · Owns users, roles, registration codes, and JWT issuance.
HealthCare-Backend/auth-service/src/main/java/com/healthcare/auth_service/AuthServiceApplication.java - Patient Service · Manages patient profiles and soft delete.
HealthCare-Backend/patient-service/src/main/java/com/healthcare/patient_service/PatientServiceApplication.java - Doctor Service · Manages doctor profiles, availability, and specialization filters.
HealthCare-Backend/doctor-service/src/main/java/com/healthcare/doctor_service/DoctorServiceApplication.java - Appointment Service · Owns booking and appointment status lifecycle.
HealthCare-Backend/appointment-service/src/main/java/com/healthcare/appointment_service/AppointmentServiceApplication.java - Record Service · Stores diagnoses and prescriptions after appointments.
HealthCare-Backend/medical-record-service/src/main/java/com/healthcare/medical_record_service/MedicalRecordServiceApplication.java - Billing Service · Generates bills, tracks payments, and integrates with Razorpay.
HealthCare-Backend/billing-service/src/main/java/com/healthcare/billing_service/BillingServiceApplication.java - Razorpay · Third-party payment provider used by billing.
Data Stores
One PostgreSQL database per service, no shared schemas or cross-service joins.
- authDB · Private database for auth users and roles.
- patientDB · Private database for patient profiles.
- doctorDB · Private database for doctor profiles and availability.
- appointmentDB · Private database for appointment lifecycle data.
- medicalRecordsDB · Private database for diagnoses and prescriptions.
- billingDB · Private database for bills and payment state.
Connections 25
- Browser → React SPA: uses · Users interact with the frontend application.
- React SPA → Auth Context: auth state · Application routing and UI read login state and role.
- React SPA → Protected Route: guards routes · Sensitive pages are wrapped with route protection.
- React SPA → API Client: API calls · Pages call backend APIs through a shared client layer.
- API Client → API Gateway: HTTPS · Frontend talks only to the gateway, not to services directly.
- API Gateway → Eureka Server: discovers · Gateway resolves service locations through the registry.
- API Gateway → Auth Service: open auth · Public registration and login routes bypass secured gateway checks.
- API Gateway → Patient Service: routes · Secured patient traffic is forwarded after JWT validation.
- API Gateway → Doctor Service: routes · Secured doctor traffic is forwarded after JWT validation.
- API Gateway → Appointment Service: routes · Secured appointment traffic is forwarded after JWT validation.
- API Gateway → Record Service: routes · Secured record traffic is forwarded after JWT validation.
- API Gateway → Billing Service: routes · Secured billing traffic is forwarded after JWT validation.
- Auth Service → authDB: owns data · Auth service is the only writer for auth identities and roles.
- Patient Service → patientDB: owns data · Patient service persists profile state in its own database.
- Doctor Service → doctorDB: owns data · Doctor service persists profiles and availability in its own database.
- Appointment Service → appointmentDB: owns data · Appointment service persists booking and status records.
- Record Service → medicalRecordsDB: owns data · Medical record service persists clinical records.
- Billing Service → billingDB: owns data · Billing service persists invoices and payment state.
- Appointment Service → Patient Service: Feign validate · Appointment creation checks patient existence before booking.
- Appointment Service → Doctor Service: Feign validate · Appointment creation checks doctor availability before booking.
- Record Service → Patient Service: Feign validate · Medical record creation verifies patient existence.
- Record Service → Doctor Service: Feign validate · Medical record creation verifies doctor existence.
- Billing Service → Appointment Service: Feign validate · Billing verifies appointment eligibility and status.
- Billing Service → Patient Service: Feign validate · Billing verifies patient identity and fraud conditions.
- Billing Service → Razorpay: payments · Billing service orchestrates outbound payment processing.