# zade-samir/healthcare-full architecture

> Architecture diagram of the GitHub repository zade-samir/healthcare-full, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zade-samir/healthcare-full
- Repository: https://github.com/zade-samir/healthcare-full

## Overview

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: [`HealthCare-Backend/api-gateway/src/main/java/com/healthcare/api_gateway/ApiGatewayApplication.java`](https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/api-gateway/src/main/java/com/healthcare/api_gateway/ApiGatewayApplication.java) (API Gateway), [`HealthCare-Backend/billing-service/src/main/java/com/healthcare/billing_service/BillingServiceApplication.java`](https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/billing-service/src/main/java/com/healthcare/billing_service/BillingServiceApplication.java) (Billing Service), [`HealthCare-Backend/appointment-service/src/main/java/com/healthcare/appointment_service/AppointmentServiceApplication.java`](https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/appointment-service/src/main/java/com/healthcare/appointment_service/AppointmentServiceApplication.java) (Appointment Service), [`HealthCare-Backend/patient-service/src/main/java/com/healthcare/patient_service/PatientServiceApplication.java`](https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/patient-service/src/main/java/com/healthcare/patient_service/PatientServiceApplication.java) (Patient Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser(("Browser<br/>client"))
  node_spa["React SPA<br/>ui shell<br/>[App.jsx]"]
  node_authctx["Auth Context<br/>state/auth<br/>[AuthContext.jsx]"]
  node_protected["Protected Route<br/>route guard<br/>[ProtectedRoute.jsx]"]
  node_api_client["API Client<br/>http client<br/>[api.js]"]
end

subgraph group_platform["Backend Platform"]
  node_gateway["API Gateway<br/>edge gateway"]
  node_eureka["Eureka Server<br/>service registry"]
end

subgraph group_services["Domain Services"]
  node_authsvc["Auth Service<br/>identity service"]
  node_patientsvc["Patient Service<br/>patient domain"]
  node_doctorsvc["Doctor Service<br/>doctor domain"]
  node_apptsvc["Appointment Service<br/>appointment domain"]
  node_recordsvc["Record Service<br/>medical record domain"]
  node_billingsvc["Billing Service<br/>billing domain"]
  node_razorpay(("Razorpay<br/>external payment api"))
end

subgraph group_data["Data Stores"]
  node_authdb[("authDB<br/>postgresql")]
  node_patientdb[("patientDB<br/>postgresql")]
  node_doctordb[("doctorDB<br/>postgresql")]
  node_apptdb[("appointmentDB<br/>postgresql")]
  node_recorddb[("medicalRecordsDB<br/>postgresql")]
  node_billingdb[("billingDB<br/>postgresql")]
end

node_browser -->|"uses"| node_spa
node_spa -->|"auth state"| node_authctx
node_spa -->|"guards routes"| node_protected
node_spa -->|"API calls"| node_api_client
node_api_client -->|"HTTPS"| node_gateway
node_gateway -->|"discovers"| node_eureka
node_gateway -->|"open auth"| node_authsvc
node_gateway -->|"routes"| node_patientsvc
node_gateway -->|"routes"| node_doctorsvc
node_gateway -->|"routes"| node_apptsvc
node_gateway -->|"routes"| node_recordsvc
node_gateway -->|"routes"| node_billingsvc
node_authsvc -->|"owns data"| node_authdb
node_patientsvc -->|"owns data"| node_patientdb
node_doctorsvc -->|"owns data"| node_doctordb
node_apptsvc -->|"owns data"| node_apptdb
node_recordsvc -->|"owns data"| node_recorddb
node_billingsvc -->|"owns data"| node_billingdb
node_apptsvc -->|"Feign validate"| node_patientsvc
node_apptsvc -->|"Feign validate"| node_doctorsvc
node_recordsvc -->|"Feign validate"| node_patientsvc
node_recordsvc -->|"Feign validate"| node_doctorsvc
node_billingsvc -->|"Feign validate"| node_apptsvc
node_billingsvc -->|"Feign validate"| node_patientsvc
node_billingsvc -->|"payments"| node_razorpay

click node_spa "https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Frontend/src/App.jsx"
click node_authctx "https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Frontend/src/context/AuthContext.jsx"
click node_protected "https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Frontend/src/components/ProtectedRoute.jsx"
click node_api_client "https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Frontend/src/services/api.js"
click node_gateway "https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/api-gateway/src/main/java/com/healthcare/api_gateway/ApiGatewayApplication.java"
click node_eureka "https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/eureka-server/src/main/java/com/healthcare/eureka_server/EurekaServerApplication.java"
click node_authsvc "https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/auth-service/src/main/java/com/healthcare/auth_service/AuthServiceApplication.java"
click node_patientsvc "https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/patient-service/src/main/java/com/healthcare/patient_service/PatientServiceApplication.java"
click node_doctorsvc "https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/doctor-service/src/main/java/com/healthcare/doctor_service/DoctorServiceApplication.java"
click node_apptsvc "https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/appointment-service/src/main/java/com/healthcare/appointment_service/AppointmentServiceApplication.java"
click node_recordsvc "https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/medical-record-service/src/main/java/com/healthcare/medical_record_service/MedicalRecordServiceApplication.java"
click node_billingsvc "https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/billing-service/src/main/java/com/healthcare/billing_service/BillingServiceApplication.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_spa,node_authctx,node_protected,node_api_client toneBlue
class node_gateway,node_eureka toneAmber
class node_authsvc,node_patientsvc,node_doctorsvc,node_apptsvc,node_recordsvc,node_billingsvc,node_razorpay toneMint
class node_authdb,node_patientdb,node_doctordb,node_apptdb,node_recorddb,node_billingdb toneRose
```

## Components

### Frontend

React/Vite single-page app with role-aware routing and page shells.

- **Browser**: client · User traffic enters the system here.
- [React SPA](https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Frontend/src/App.jsx): ui shell · Vite/React application with role-specific pages and layouts. · `HealthCare-Frontend/src/App.jsx`
- [Auth Context](https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Frontend/src/context/AuthContext.jsx): state/auth · Holds login state, role, and session-aware UI behavior. · `HealthCare-Frontend/src/context/AuthContext.jsx`
- [Protected Route](https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Frontend/src/components/ProtectedRoute.jsx): route guard · Blocks unauthorized navigation based on auth state and role. · `HealthCare-Frontend/src/components/ProtectedRoute.jsx`
- [API Client](https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Frontend/src/services/api.js): http 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](https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/api-gateway/src/main/java/com/healthcare/api_gateway/ApiGatewayApplication.java): edge 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](https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/eureka-server/src/main/java/com/healthcare/eureka_server/EurekaServerApplication.java): service registry · 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](https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/auth-service/src/main/java/com/healthcare/auth_service/AuthServiceApplication.java): identity service · Owns users, roles, registration codes, and JWT issuance. · `HealthCare-Backend/auth-service/src/main/java/com/healthcare/auth_service/AuthServiceApplication.java`
- [Patient Service](https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/patient-service/src/main/java/com/healthcare/patient_service/PatientServiceApplication.java): patient domain · Manages patient profiles and soft delete. · `HealthCare-Backend/patient-service/src/main/java/com/healthcare/patient_service/PatientServiceApplication.java`
- [Doctor Service](https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/doctor-service/src/main/java/com/healthcare/doctor_service/DoctorServiceApplication.java): doctor domain · Manages doctor profiles, availability, and specialization filters. · `HealthCare-Backend/doctor-service/src/main/java/com/healthcare/doctor_service/DoctorServiceApplication.java`
- [Appointment Service](https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/appointment-service/src/main/java/com/healthcare/appointment_service/AppointmentServiceApplication.java): appointment domain · Owns booking and appointment status lifecycle. · `HealthCare-Backend/appointment-service/src/main/java/com/healthcare/appointment_service/AppointmentServiceApplication.java`
- [Record Service](https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/medical-record-service/src/main/java/com/healthcare/medical_record_service/MedicalRecordServiceApplication.java): medical record domain · Stores diagnoses and prescriptions after appointments. · `HealthCare-Backend/medical-record-service/src/main/java/com/healthcare/medical_record_service/MedicalRecordServiceApplication.java`
- [Billing Service](https://github.com/zade-samir/healthcare-full/blob/main/HealthCare-Backend/billing-service/src/main/java/com/healthcare/billing_service/BillingServiceApplication.java): billing domain · Generates bills, tracks payments, and integrates with Razorpay. · `HealthCare-Backend/billing-service/src/main/java/com/healthcare/billing_service/BillingServiceApplication.java`
- **Razorpay**: external payment api · Third-party payment provider used by billing.

### Data Stores

One PostgreSQL database per service, no shared schemas or cross-service joins.

- **authDB**: postgresql · Private database for auth users and roles.
- **patientDB**: postgresql · Private database for patient profiles.
- **doctorDB**: postgresql · Private database for doctor profiles and availability.
- **appointmentDB**: postgresql · Private database for appointment lifecycle data.
- **medicalRecordsDB**: postgresql · Private database for diagnoses and prescriptions.
- **billingDB**: postgresql · Private database for bills and payment state.

## Connections

- 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.
