# athisii/patient-management architecture

> Architecture diagram of the GitHub repository athisii/patient-management, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/athisii/patient-management
- Repository: https://github.com/athisii/patient-management

## Overview

This repository implements a patient-management system as several Spring services. A client sends patient requests through the API gateway to patient CRUD operations, which validate and persist patient records and, on creation, request a billing account and publish an event for analytics. A separate authentication service issues and validates JWTs. The graph also includes billing and analytics service endpoints and the local infrastructure module. Edges follow shown calls and documented service boundaries; some gateway, messaging, and runtime wiring is unsampled and is marked unverified or omitted.

Main entry points: [`patient-service/src/main/java/com/athisii/patientservice/service/impl/PatientServiceImpl.java`](https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/service/impl/PatientServiceImpl.java) (Patient operations), [`api-gateway/src/main/java/com/athisii/apigateway/ApiGatewayApplication.java`](https://github.com/athisii/patient-management/blob/main/api-gateway/src/main/java/com/athisii/apigateway/ApiGatewayApplication.java) (API gateway), [`auth-service/src/main/java/com/athisii/authservice/service/impl/AuthServiceImpl.java`](https://github.com/athisii/patient-management/blob/main/auth-service/src/main/java/com/athisii/authservice/service/impl/AuthServiceImpl.java) (Authentication), [`patient-service/src/main/java/com/athisii/patientservice/controller/PatientController.java`](https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/controller/PatientController.java) (Patient endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["API and authentication"]
  node_gateway["API gateway"]
  node_jwtfilter["JWT gateway filter"]
  node_authcontroller["Auth endpoints"]
  node_authservice["Authentication"]
  node_userservice["User lookup"]
  node_userrepo["User repository"]
  node_userstore[("User database<br/>[User.java]")]
  node_jwt["JWT utility<br/>[JwtUtil.java]"]
end

subgraph group_patients["Patient management"]
  node_patientcontroller["Patient endpoints"]
  node_patientservice["Patient operations"]
  node_patientdto["Patient request DTO"]
  node_patientmapper["Patient mapper<br/>[PatientMapper.java]"]
  node_patientrepo["Patient repository"]
  node_patientstore[("Patient database<br/>[Patient.java]")]
end

subgraph group_billing["Billing integration"]
  node_billingclient["Billing gRPC client"]
  node_billingservice["Billing gRPC service"]
  node_billingaccount["Billing account"]
end

subgraph group_events["Event analytics"]
  node_producer["Kafka producer<br/>[KafkaProducer.java]"]
  node_broker["Kafka broker"]
  node_consumer["Analytics consumer<br/>[KafkaConsumer.java]"]
end

subgraph group_runtime["Local infrastructure"]
  node_localstack["Local stack<br/>[LocalStack.java]"]
end

node_client(("API client"))

node_client -.->|"sends requests"| node_gateway
node_gateway -.->|"applies filter"| node_jwtfilter
node_gateway -.->|"routes requests"| node_patientcontroller
node_gateway -.->|"routes requests"| node_authcontroller
node_authcontroller -->|"delegates to"| node_authservice
node_authservice -->|"looks up user"| node_userservice
node_userservice -->|"queries"| node_userrepo
node_userrepo -.->|"stores users"| node_userstore
node_authservice -->|"generates and validates"| node_jwt
node_jwtfilter -.->|"validates token"| node_authcontroller
node_patientcontroller -->|"delegates to"| node_patientservice
node_patientcontroller -->|"accepts request"| node_patientdto
node_patientservice -->|"maps records"| node_patientmapper
node_patientservice -->|"reads and writes"| node_patientrepo
node_patientrepo -.->|"persists records"| node_patientstore
node_patientservice -->|"requests account"| node_billingclient
node_billingclient -->|"calls gRPC"| node_billingservice
node_billingservice -.->|"uses contract"| node_billingaccount
node_patientservice -->|"publishes event"| node_producer
node_producer -.->|"publishes to"| node_broker
node_broker -.->|"delivers events"| node_consumer

click node_gateway "https://github.com/athisii/patient-management/blob/main/api-gateway/src/main/java/com/athisii/apigateway/ApiGatewayApplication.java"
click node_jwtfilter "https://github.com/athisii/patient-management/blob/main/api-gateway/src/main/java/com/athisii/apigateway/filter/JwtValidationGatewayFilterFactory.java"
click node_authcontroller "https://github.com/athisii/patient-management/blob/main/auth-service/src/main/java/com/athisii/authservice/controller/AuthController.java"
click node_authservice "https://github.com/athisii/patient-management/blob/main/auth-service/src/main/java/com/athisii/authservice/service/impl/AuthServiceImpl.java"
click node_userservice "https://github.com/athisii/patient-management/blob/main/auth-service/src/main/java/com/athisii/authservice/service/impl/UserServiceImpl.java"
click node_userrepo "https://github.com/athisii/patient-management/blob/main/auth-service/src/main/java/com/athisii/authservice/repository/UserRepository.java"
click node_userstore "https://github.com/athisii/patient-management/blob/main/auth-service/src/main/java/com/athisii/authservice/entity/User.java"
click node_jwt "https://github.com/athisii/patient-management/blob/main/auth-service/src/main/java/com/athisii/authservice/util/JwtUtil.java"
click node_patientcontroller "https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/controller/PatientController.java"
click node_patientservice "https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/service/impl/PatientServiceImpl.java"
click node_patientdto "https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/dto/PatientRequestDto.java"
click node_patientmapper "https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/mapper/PatientMapper.java"
click node_patientrepo "https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/repository/PatientRepository.java"
click node_patientstore "https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/entity/Patient.java"
click node_billingclient "https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/grpc/BillingServiceGrpcClient.java"
click node_billingservice "https://github.com/athisii/patient-management/blob/main/billing-service/src/main/java/com/athisii/billingservice/grpc/BillingGrpcService.java"
click node_billingaccount "https://github.com/athisii/patient-management/blob/main/billing-service/src/main/proto/billing_service.proto"
click node_producer "https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/kafka/KafkaProducer.java"
click node_consumer "https://github.com/athisii/patient-management/blob/main/analytics-service/src/main/java/com/athisii/analyticsservice/kafka/KafkaConsumer.java"
click node_localstack "https://github.com/athisii/patient-management/blob/main/infrastructure/src/main/java/com/athisii/stack/LocalStack.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_gateway,node_jwtfilter,node_authcontroller,node_authservice,node_userservice,node_userrepo,node_userstore,node_jwt,node_client toneBlue
class node_patientcontroller,node_patientservice,node_patientdto,node_patientmapper,node_patientrepo,node_patientstore toneAmber
class node_billingclient,node_billingservice,node_billingaccount toneMint
class node_producer,node_broker,node_consumer toneRose
class node_localstack toneIndigo
```

## Components

### API and authentication

- [API gateway](https://github.com/athisii/patient-management/blob/main/api-gateway/src/main/java/com/athisii/apigateway/ApiGatewayApplication.java): `api-gateway/src/main/java/com/athisii/apigateway/ApiGatewayApplication.java`
- [JWT gateway filter](https://github.com/athisii/patient-management/blob/main/api-gateway/src/main/java/com/athisii/apigateway/filter/JwtValidationGatewayFilterFactory.java): `api-gateway/src/main/java/com/athisii/apigateway/filter/JwtValidationGatewayFilterFactory.java`
- [Auth endpoints](https://github.com/athisii/patient-management/blob/main/auth-service/src/main/java/com/athisii/authservice/controller/AuthController.java): `auth-service/src/main/java/com/athisii/authservice/controller/AuthController.java`
- [Authentication](https://github.com/athisii/patient-management/blob/main/auth-service/src/main/java/com/athisii/authservice/service/impl/AuthServiceImpl.java): `auth-service/src/main/java/com/athisii/authservice/service/impl/AuthServiceImpl.java`
- [User lookup](https://github.com/athisii/patient-management/blob/main/auth-service/src/main/java/com/athisii/authservice/service/impl/UserServiceImpl.java): `auth-service/src/main/java/com/athisii/authservice/service/impl/UserServiceImpl.java`
- [User repository](https://github.com/athisii/patient-management/blob/main/auth-service/src/main/java/com/athisii/authservice/repository/UserRepository.java): `auth-service/src/main/java/com/athisii/authservice/repository/UserRepository.java`
- [User database](https://github.com/athisii/patient-management/blob/main/auth-service/src/main/java/com/athisii/authservice/entity/User.java): `auth-service/src/main/java/com/athisii/authservice/entity/User.java`
- [JWT utility](https://github.com/athisii/patient-management/blob/main/auth-service/src/main/java/com/athisii/authservice/util/JwtUtil.java): `auth-service/src/main/java/com/athisii/authservice/util/JwtUtil.java`

### Patient management

- [Patient endpoints](https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/controller/PatientController.java): `patient-service/src/main/java/com/athisii/patientservice/controller/PatientController.java`
- [Patient operations](https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/service/impl/PatientServiceImpl.java): `patient-service/src/main/java/com/athisii/patientservice/service/impl/PatientServiceImpl.java`
- [Patient request DTO](https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/dto/PatientRequestDto.java): `patient-service/src/main/java/com/athisii/patientservice/dto/PatientRequestDto.java`
- [Patient mapper](https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/mapper/PatientMapper.java): `patient-service/src/main/java/com/athisii/patientservice/mapper/PatientMapper.java`
- [Patient repository](https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/repository/PatientRepository.java): `patient-service/src/main/java/com/athisii/patientservice/repository/PatientRepository.java`
- [Patient database](https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/entity/Patient.java): `patient-service/src/main/java/com/athisii/patientservice/entity/Patient.java`

### Billing integration

- [Billing gRPC client](https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/grpc/BillingServiceGrpcClient.java): `patient-service/src/main/java/com/athisii/patientservice/grpc/BillingServiceGrpcClient.java`
- [Billing gRPC service](https://github.com/athisii/patient-management/blob/main/billing-service/src/main/java/com/athisii/billingservice/grpc/BillingGrpcService.java): `billing-service/src/main/java/com/athisii/billingservice/grpc/BillingGrpcService.java`
- [Billing account](https://github.com/athisii/patient-management/blob/main/billing-service/src/main/proto/billing_service.proto): `billing-service/src/main/proto/billing_service.proto`

### Event analytics

- [Kafka producer](https://github.com/athisii/patient-management/blob/main/patient-service/src/main/java/com/athisii/patientservice/kafka/KafkaProducer.java): `patient-service/src/main/java/com/athisii/patientservice/kafka/KafkaProducer.java`
- **Kafka broker**
- [Analytics consumer](https://github.com/athisii/patient-management/blob/main/analytics-service/src/main/java/com/athisii/analyticsservice/kafka/KafkaConsumer.java): `analytics-service/src/main/java/com/athisii/analyticsservice/kafka/KafkaConsumer.java`

### Local infrastructure

- [Local stack](https://github.com/athisii/patient-management/blob/main/infrastructure/src/main/java/com/athisii/stack/LocalStack.java): `infrastructure/src/main/java/com/athisii/stack/LocalStack.java`

### Other components

- **API client**

## Connections

- API client → API gateway: sends requests
- API gateway → JWT gateway filter: applies filter
- API gateway → Patient endpoints: routes requests
- API gateway → Auth endpoints: routes requests
- Auth endpoints → Authentication: delegates to (evidence: `auth-service/src/main/java/com/athisii/authservice/controller/AuthController.java`)
- Authentication → User lookup: looks up user (evidence: `auth-service/src/main/java/com/athisii/authservice/service/impl/AuthServiceImpl.java`)
- User lookup → User repository: queries (evidence: `auth-service/src/main/java/com/athisii/authservice/service/impl/UserServiceImpl.java`)
- User repository → User database: stores users (evidence: `auth-service/src/main/java/com/athisii/authservice/repository/UserRepository.java`)
- Authentication → JWT utility: generates and validates (evidence: `auth-service/src/main/java/com/athisii/authservice/service/impl/AuthServiceImpl.java`)
- JWT gateway filter → Auth endpoints: validates token
- Patient endpoints → Patient operations: delegates to (evidence: `patient-service/src/main/java/com/athisii/patientservice/controller/PatientController.java`)
- Patient endpoints → Patient request DTO: accepts request (evidence: `patient-service/src/main/java/com/athisii/patientservice/controller/PatientController.java`)
- Patient operations → Patient mapper: maps records (evidence: `patient-service/src/main/java/com/athisii/patientservice/service/impl/PatientServiceImpl.java`)
- Patient operations → Patient repository: reads and writes (evidence: `patient-service/src/main/java/com/athisii/patientservice/service/impl/PatientServiceImpl.java`)
- Patient repository → Patient database: persists records (evidence: `patient-service/src/main/java/com/athisii/patientservice/repository/PatientRepository.java`)
- Patient operations → Billing gRPC client: requests account (evidence: `patient-service/src/main/java/com/athisii/patientservice/service/impl/PatientServiceImpl.java`)
- Billing gRPC client → Billing gRPC service: calls gRPC (evidence: `patient-service/src/main/java/com/athisii/patientservice/grpc/BillingServiceGrpcClient.java`)
- Billing gRPC service → Billing account: uses contract
- Patient operations → Kafka producer: publishes event (evidence: `patient-service/src/main/java/com/athisii/patientservice/service/impl/PatientServiceImpl.java`)
- Kafka producer → Kafka broker: publishes to
- Kafka broker → Analytics consumer: delivers events
