Clínica — Sistema de Gestión Hospitalaria

Microservices system for managing a health clinic — patients, appointments, admissions and billing with JWT auth, automatic migrations and an AI medical assistant.

  • Java 21
  • Spring
  • Microservices
  • PostgreSQL
  • Redis
  • Docker
  • JWT
GitHub ↗ DeepWiki ↗

Problem

Small and mid-sized clinics typically rely on spreadsheets or legacy systems to manage appointments, records and billing. The goal was to build a modern platform that centralized all clinical operations with enterprise-grade security and real scalability.

Solution

Modular microservices system where each domain (patients, appointments, admissions, billing, providers) runs as an independent service. All services register with Eureka for dynamic discovery. Centralized authentication with RSA-256 signed JWT. Integrated medical assistant via Gemini AI for support queries.

Architecture

  • Eureka Service Discovery — services register automatically; no manual IP configuration
  • JWT with RSA-256 — asymmetrically signed token; the auth service issues it, each microservice validates without a database
  • Multi-database — PostgreSQL for critical transactional data, MySQL where the schema justifies it; Flyway for versioned migrations on both
  • Docker Compose — brings up the full stack (services + databases + Eureka dashboard) with a single command
  • Spring AI + Gemini — assistant integrated directly into the medical consultation flow
Cl
Clínica · Sistema de Gestión Hospitalaria
Java 21 · Spring Boot 3.5 · Spring Cloud 2025 · 8 microservicios
▶ Pruébalo — arrastra nodos · click para inspeccionar
externogatewayserviciosIAinfra
HTTPS / JWTverificamédicocoberturafacturaintent →registerClientes ExternosBrowser · Apps · IntegracionesAPI GatewaySpring Cloud Gateway 4.3 · :8080LoggingFilterRateLimitFilter (Redis)AuthFilter JWT RSA-256CircuitBreakerRetryAuth ServiceJWT RSA-256 · :8084 · MySQLPatient ServicePacientes · :8082 · MySQLAdmissions ServiceAtenciones · :8083 · PostgreSQLSuppliers ServiceMédicos · :8085 · MySQLClients ServiceAseguradoras · :8086 · MySQLAI AssistantGemini · Spring AI · :8087 · PGGeminiClientIntent DetectionBilling ServiceFacturación · :8088 · MySQLEureka ServerService Discovery · :8761
cada barra representa un ciclo completo: cliente → gateway → servicio → respuesta
Architecture diagram of Clínica — Sistema de Gestión Hospitalaria

Technical Decisions

RSA-256 was chosen over HMAC-SHA for JWT because in a microservices architecture each service only needs the public key to verify — no shared secrets. Flyway over manual scripts because in a healthcare system schema change traceability is an audit requirement.

DOCUMENTATION

Technical Architecture — Clínica

Version: 1.0
Stack: Java 21 · Spring Boot 3.5 · Spring Cloud 2025.0
Domain: Hospital management — patients, admissions, suppliers, billing, authentication, AI

1. Problem Context

Mid-sized clinics operate across multiple domains that evolve at different rates: patient registration does not change at the same pace as billing or physician scheduling. Consolidating everything into a monolith creates unnecessary coupling and blocks the independent deployment of critical changes.

A healthcare system also has non-negotiable requirements:

  • Complete audit trail — every change to a clinical record must be logged with user, timestamp, and action.
  • Safe deletion — medical data is never physically deleted; records are marked inactive with full traceability.
  • Robust security — credentials in transit, short-lived tokens, account lockout on failed attempts, RBAC per professional role.
  • Availability under partial failures — if the billing service goes down, admissions must keep working.

2. System Overview

                         ┌─────────────────────────────────┐
                         │         External Clients        │
                         │   Browser · Apps · Integrations │
                         └─────────────┬───────────────────┘
                                       │ HTTPS / JWT
                                       ▼
                    ┌──────────────────────────────────────┐
                    │            API Gateway               │
                    │   Spring Cloud Gateway 4.3           │
                    │  ┌──────────┬──────────┬──────────┐  │
                    │  │ Logging  │Rate Limit│ Retry    │  │
                    │  │ Routing  │  Redis   │Circuit   │  │
                    │  └──────────┴──────────┴──────────┘  │
                    └────┬──────┬──────┬──────┬─────────┬──┘
                         │      │      │      │         │
              ┌──────────┘ ┌────┘      │      └────┐    └──────┐
              ▼            ▼           ▼           ▼           ▼
        ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐ ┌─────────┐
        │ Patient  │ │Admissions│ │  Auth  │ │Suppliers │ │ Clients │
        │ Service  │ │ Service  │ │Service │ │ Service  │ │ Service │
        │  MySQL   │ │PostgreSQL│ │ MySQL  │ │  MySQL   │ │  MySQL  │
        └──────────┘ └──────────┘ └────────┘ └──────────┘ └─────────┘
              │                        │
              ▼                        ▼
        ┌──────────┐           ┌───────────────┐
        │AI Assist │           │ Eureka Server │
        │PostgreSQL│           │   Discovery   │
        └──────────┘           └───────────────┘
                                       ▲
                        All services register here

3. Technology Stack

Layer Technology Rationale
Runtime Java 21 LTS support, records, sealed classes, pattern matching
Framework Spring Boot 3.5 + Spring Cloud 2025 Mature microservices ecosystem; auto-configuration, actuator, security
API Gateway Spring Cloud Gateway 4.3 Reactive (WebFlux); rate limiting, logging, and circuit breaker without custom code
Service Discovery Netflix Eureka Dynamic registry; services locate each other by name, not IP
Security Spring Security 6 + JWT RSA-256 Asymmetric tokens: Auth signs with private key, each service validates with public key
Databases MySQL 8 · PostgreSQL 16 MySQL for simple relational domains; PostgreSQL for transactional data
Migrations Flyway Versioned schema history; mandatory in healthcare systems (audit compliance)
ORM Hibernate + MapStruct 1.6 JPA standard; MapStruct generates mapping code at compile time (zero reflection)
Resilience Resilience4j Circuit breaker, retry with exponential backoff, declarative fallback
Cache / Rate Limit Redis 7 Distributed cache + token bucket for gateway rate limiting
AI Spring AI + Gemini API Portable abstraction (Gemini in prod, LM Studio locally)
Containers Docker + Compose Full stack launchable with a single command
Testing JUnit 5 + Mockito Unit tests for services, controllers, and integrations
Build Maven multi-module Single parent POM manages dependency versions for all services

4. Microservices — Responsibilities

4.1 Patient Service (:8082)

Owns the clinical patient domain.

PatientController
    └── PatientService
          ├── PatientRepository          → Table patients (MySQL)
          ├── AllergyRepository          → Table allergies
          ├── ChronicDiseaseRepository   → Table chronic_diseases
          ├── MedicationRepository       → Table current_medications
          ├── FamilyHistoryRepository    → Table family_histories
          └── VaccinationRepository      → Table vaccination_records

Core entities:

Entity Description
Patient Demographics: UUID, ID type/number, DOB, gender, contact, affiliation
MedicalHistory General clinical history of the patient
Allergy Allergies with severity level
ChronicDisease Diagnosed chronic conditions
CurrentMedication Active medications with dosage and frequency
FamilyHistory Relevant family medical background
VaccinationRecord Vaccination history

Soft delete: deleted_at + deleted_by on every table — records are never physically removed.

4.2 Admissions Service (:8083)

Manages the full lifecycle of a medical encounter.

AttentionController
    └── AttentionService
          ├── AttentionRepository        → Table attentions (PostgreSQL)
          ├── AttentionMovementRepository
          ├── AttentionUserHistoryRepository
          └── AuthorizationRepository

Encounter state machine:

[Patient arrives]
      │
      ▼
  CREATED ──────────────────► CANCELLED
      │
      ▼
 IN_PROGRESS
      │
      ├── (billing validated)
      │
      ▼
 DISCHARGED

Triage levels:

Color Priority Description
RED 1 Critical emergency — immediate attention
ORANGE 2 Urgent emergency
YELLOW 3 Moderate urgency
GREEN 4 Non-urgent
BLUE 5 Routine consultation

4.3 Auth Service (:8084)

Centralized authentication. Issues JWT tokens signed with RSA-256.

AuthController
    ├── AuthenticationService  → Login, logout, refresh token
    ├── UserService            → Registration, password change, account lock
    ├── PasswordResetService   → Token-based reset flow
    └── AuditService           → Logs all access events

4.4 Suppliers Service (:8085)

Manages medical staff and their availability.

DoctorController
    └── DoctorService
          ├── DoctorRepository         → Table doctors
          ├── ScheduleRepository       → Table doctor_schedules
          └── UnavailabilityRepository → Table doctor_unavailability

4.5 Clients Service (:8086)

Health providers: insurers, HMOs, clinic networks.

HealthProviderController
    └── HealthProviderService
          ├── HealthProviderRepository → Table health_providers
          ├── ContractRepository       → Table contracts
          └── PortfolioRepository      → Table portfolios

4.6 AI Assistant Service (:8087)

Conversational assistant with session memory and admissions workflow integration.

AIAssistantController
    └── AIAssistantService
          ├── GeminiClient (Spring AI)  → Gemini API calls
          ├── ConversationRepository    → Table conversation_history
          └── MessageRepository         → Table conversation_messages

The assistant detects intent in conversation: if a physician describes a patient's symptoms, it can automatically initiate the creation of an encounter by calling the Admissions Service internally.

4.7 API Gateway (:8080)

Single entry point for all external traffic.

Inbound filters:
  LoggingFilter   → Records each request (method, path, status, time) to PostgreSQL
  RateLimitFilter → Token bucket per user in Redis: max N req/sec
  AuthFilter      → Validates JWT (RSA-256 public key) before routing

Per configured route:
  Resilience4j:
    CircuitBreaker → Opens after X consecutive failures
    Retry          → Exponential backoff, max 3 attempts
    TimeLimiter    → Per-request timeout

5. Service Discovery — Eureka

Microservice startup:
  1. Spring Cloud Eureka Client activates
  2. Service publishes: { serviceId, host, port, status: UP }
  3. Eureka maintains heartbeat every 30s; failure → marks DOWN
  4. API Gateway queries the registry to resolve routes

Without Eureka: every service would need hardcoded IPs
With Eureka: the gateway resolves "PATIENT-SERVICE" → current IP dynamically

Docker Compose benefit: when a container restarts with a new IP, Eureka re-registers it automatically. No configuration changes needed.

6. Database Strategy

Each service is the exclusive owner of its database. No cross-service JOINs.

Service Engine Rationale
Patient MySQL 8 Stable relational schema, good Hibernate integration
Admissions PostgreSQL Native enums for triage and states; better support for audit triggers
Auth MySQL 8 User tables with indexes on email and username
Suppliers MySQL 8 Doctor ↔ specialty relationships
Clients MySQL 8 Provider and contract data
AI Assistant PostgreSQL JSONB for storing messages with flexible metadata
API Gateway PostgreSQL Analytics logs: high write volume, aggregation queries

Flyway: each service has its own db/migration/ folder with V{n}__{description}.sql files. Migrations run automatically on service startup.

7. Resilience Patterns

7.1 Circuit Breaker

CLOSED state (normal):
  Requests pass through to the target service

OPEN state (service down):
  Activates when failure rate > configured threshold
  Requests fail fast → no waiting for timeout
  @Fallback method is called

HALF-OPEN state (recovery):
  Allows a few probe requests
  If they succeed → returns to CLOSED
  If they fail → returns to OPEN

7.2 Retry with Exponential Backoff

Attempt 1 → fails
Wait 500ms
Attempt 2 → fails
Wait 1000ms
Attempt 3 → fails
→ Fallback or error returned to client

7.3 Rate Limiting (Redis)

For each request arriving at the gateway:
  1. Extract userId from JWT
  2. Query Redis: available_tokens[userId]
  3. If tokens > 0 → decrement and allow
  4. If tokens = 0 → 429 Too Many Requests
  5. Redis refills tokens at configurable rate (token bucket)

8. AI Assistant — Integration

Client               AI Service            Admissions Service
   │                     │                        │
   │ POST /chat          │                        │
   │ {"message":"..."}   │                        │
   │─────────────────►   │                        │
   │                     │ Gemini API             │
   │                     │ (Spring AI)            │
   │                     │ ─────────────►         │
   │                     │ ◄─────────────         │
   │                     │                        │
   │                     │ (detects intent)       │
   │                     │ POST /api/v1/attentions│
   │                     │ ───────────────────►   │
   │                     │ ◄───────────────────   │
   │                     │                        │
   │ ◄─────────────────  │                        │
   │ response + action   │                        │

Spring AI acts as an abstraction layer: by changing configuration, the system can point to Gemini (production) or LM Studio (local development at no API cost).

9. Key Design Decisions

9.1 JWT with RSA-256 Instead of HMAC-SHA

Decision: Auth Service signs tokens with an RSA private key. Each microservice holds only the public key to verify.
Why: In a microservices architecture using HMAC, all services would need the same secret key — a shared secret among N services is an attack surface N times larger. With asymmetric RSA, compromising a microservice does not expose the ability to issue tokens.

9.2 Flyway Over Manual Scripts

Decision: All schema migrations are versioned Flyway files.
Why: In a healthcare system, schema changes are auditable by regulation. Flyway guarantees that the production schema version is exactly reproducible and cannot be applied out of order.

9.3 Soft Deletes Across All Domains

Decision: No entity in the system is removed with a SQL DELETE.
Why: Medical records have legal value. The ability to restore a "deleted" record is a compliance requirement. The deleted_at field enables logical filtering without losing the data.

9.4 MapStruct Over ModelMapper or Manual Mapping

Decision: MapStruct generates entity-to-DTO mapping code at compile time.
Why: ModelMapper uses runtime reflection (slow, hard to debug). Manual mapping is verbose and error-prone when adding fields. MapStruct: zero reflection, compile error if a field mapping is missing, as fast as handwritten code.

9.5 One Database Per Service

Decision: No shared tables between microservices. Cross-service references are done by ID.
Why: Schema-level coupling is the most dangerous form of coupling in microservices — changing a column in the patients table breaks every service that JOINs directly. With independent databases, each service evolves its schema autonomously.

10. Project Structure

Clinica/
├── BackEnd-Clinica/
│   ├── pom.xml                         # Parent POM — dependency management
│   ├── docker-compose.yml              # Full stack
│   ├── .env                            # Environment variables
│   ├── eureka-service/                 # Service registry
│   ├── api-gateway/                    # Gateway + rate limiting + analytics
│   ├── auth-service/                   # JWT, users, roles
│   │   └── src/main/java/.../
│   │       ├── module/entity/          # User, Role, RefreshToken, AuditLog
│   │       ├── module/service/         # Auth, User, PasswordReset
│   │       └── module/controller/      # AuthController
│   ├── patient-service/                # Patients and medical records
│   ├── admissions-service/             # Encounters, triage, authorizations
│   ├── suppliers-service/              # Doctors, specialties, schedules
│   ├── clients-service/                # Insurers, contracts
│   ├── ai-assistant-service/           # Chat with Gemini / LM Studio
│   └── billing-service/                # Billing (in development)
├── FrontEnd-Clinica/                   # Astro 6 (in development)
└── docs/                               # This document and API reference

Document maintained alongside the code — if the architecture changes, update this description.

REST API Reference — Clínica

Version: 1.0
Base URL: http://localhost:8080 (API Gateway)
Authentication: Bearer JWT (RSA-256) in Authorization header

Conventions

  • All endpoints require Authorization: Bearer <token> except authentication endpoints.
  • Successful responses return 2xx; errors follow the standard Spring error format.
  • UUIDs are expressed as strings in xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx format.
  • Timestamps use ISO 8601: 2025-05-19T14:30:00.
  • Soft delete: deleted records have a non-null deletedAt and do not appear in normal listings.

1. Auth Service — /api/v1/auth

POST /login

Authenticates a user and returns an access token + refresh token.

Request:

{
  "username": "dr.martinez",
  "password": "SecurePass123!"
}

Response 200 OK:

{
  "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
  "refreshToken": "d4f8a2b1-...",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "user": {
    "id": "a1b2c3d4-...",
    "username": "dr.martinez",
    "email": "martinez@clinica.com",
    "roles": ["ROLE_DOCTOR"]
  }
}

Errors:

Code Cause
401 Invalid credentials
423 Account locked due to failed login attempts

POST /refresh

Renews the access token using the refresh token.

Request:

{
  "refreshToken": "d4f8a2b1-..."
}

Response 200 OK:

{
  "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
  "expiresIn": 900
}

POST /logout

Invalidates the current refresh token.

Request:

{
  "refreshToken": "d4f8a2b1-..."
}

Response 204 No Content

POST /password-reset/request

Initiates the password reset flow.

Request:

{
  "email": "martinez@clinica.com"
}

Response 200 OK:

{
  "message": "If the email exists, you will receive reset instructions."
}

POST /password-reset/confirm

Sets the new password using the received reset token.

Request:

{
  "token": "abc123-reset-token",
  "newPassword": "NewPassword456!"
}

Response 200 OK:

{
  "message": "Password updated successfully."
}

2. Patient Service — /api/v1/patients

GET /

Lists all active patients with pagination.

Query params:

Param Type Default Description
page integer 0 Page number
size integer 20 Elements per page
sort string lastName,asc Field and direction

Response 200 OK:

{
  "content": [
    {
      "id": "p1a2b3c4-...",
      "identificationNumber": "1234567890",
      "identificationType": "CC",
      "firstName": "Carlos",
      "lastName": "Rodriguez",
      "dateOfBirth": "1985-03-15",
      "gender": "MALE",
      "phone": "+57 310 555 0101",
      "email": "c.rodriguez@email.com",
      "insuranceAffiliation": "EPS Sura",
      "createdAt": "2025-01-10T09:00:00"
    }
  ],
  "totalElements": 142,
  "totalPages": 8,
  "size": 20,
  "number": 0
}

POST /

Registers a new patient.

Request:

{
  "identificationNumber": "9876543210",
  "identificationType": "CC",
  "firstName": "Maria",
  "lastName": "Gonzalez",
  "dateOfBirth": "1990-07-22",
  "gender": "FEMALE",
  "phone": "+57 311 555 0202",
  "email": "m.gonzalez@email.com",
  "address": "Calle 45 # 12-34, Bogotá",
  "insuranceAffiliation": "EPS Sanitas"
}

Response 201 Created:

{
  "id": "p9z8y7x6-...",
  "identificationNumber": "9876543210",
  "firstName": "Maria",
  "lastName": "Gonzalez",
  "createdAt": "2025-05-19T10:15:00"
}

GET /{id}

Returns the full profile of a patient including their complete medical history.

Response 200 OK:

{
  "id": "p1a2b3c4-...",
  "firstName": "Carlos",
  "lastName": "Rodriguez",
  "dateOfBirth": "1985-03-15",
  "gender": "MALE",
  "medicalHistory": {
    "bloodType": "O+",
    "notes": "Patient with history of seasonal allergies."
  },
  "allergies": [
    {
      "id": "al001",
      "substance": "Penicillin",
      "severity": "HIGH",
      "reaction": "Anaphylaxis"
    }
  ],
  "chronicDiseases": [
    {
      "id": "cd001",
      "name": "Arterial hypertension",
      "diagnosedAt": "2018-06-01"
    }
  ],
  "currentMedications": [
    {
      "id": "med001",
      "name": "Losartan",
      "dosage": "50mg",
      "frequency": "Once daily"
    }
  ],
  "vaccinationRecords": [
    {
      "id": "vac001",
      "vaccine": "COVID-19 — Pfizer",
      "appliedAt": "2021-04-15",
      "nextDoseAt": "2021-05-06"
    }
  ]
}

PUT /{id}

Updates demographic data for a patient.

Request: (fields to modify)

{
  "phone": "+57 310 555 9999",
  "address": "Carrera 7 # 80-15, Bogotá"
}

Response 200 OK: updated patient

DELETE /{id}

Soft delete of the patient (sets deletedAt).

Response 204 No Content

POST /{id}/allergies

Adds an allergy to the patient's history.

Request:

{
  "substance": "Ibuprofen",
  "severity": "MEDIUM",
  "reaction": "Hives"
}

Response 201 Created

POST /{id}/vaccinations

Records a vaccination.

Request:

{
  "vaccine": "Seasonal influenza",
  "appliedAt": "2025-03-10",
  "nextDoseAt": "2026-03-10",
  "appliedBy": "Dr. Perez"
}

Response 201 Created

3. Admissions Service — /api/v1/attentions

GET /

Lists encounters with optional filters.

Query params:

Param Type Description
status string CREATED, IN_PROGRESS, DISCHARGED, CANCELLED
triage string RED, ORANGE, YELLOW, GREEN, BLUE
date string Date in YYYY-MM-DD format
doctorId UUID Filter by assigned doctor

Response 200 OK:

{
  "content": [
    {
      "id": "att001-...",
      "patientId": "p1a2b3c4-...",
      "patientName": "Carlos Rodriguez",
      "triageLevel": "YELLOW",
      "status": "IN_PROGRESS",
      "assignedDoctorId": "doc001-...",
      "createdAt": "2025-05-19T08:30:00"
    }
  ],
  "totalElements": 18
}

POST /

Creates a new medical encounter.

Request:

{
  "patientId": "p1a2b3c4-...",
  "triageLevel": "ORANGE",
  "reason": "Acute chest pain radiating to the left arm",
  "assignedDoctorId": "doc001-...",
  "authorizationCode": "EPS-2025-001234"
}

Response 201 Created:

{
  "id": "att999-...",
  "status": "CREATED",
  "triageLevel": "ORANGE",
  "createdAt": "2025-05-19T14:22:00"
}

GET /{id}

Returns the full details of an encounter.

Response 200 OK:

{
  "id": "att001-...",
  "patientId": "p1a2b3c4-...",
  "triageLevel": "YELLOW",
  "status": "IN_PROGRESS",
  "reason": "High fever and dry cough",
  "assignedDoctorId": "doc001-...",
  "movements": [
    {
      "id": "mov001",
      "fromStatus": "CREATED",
      "toStatus": "IN_PROGRESS",
      "performedBy": "dr.martinez",
      "timestamp": "2025-05-19T09:05:00"
    }
  ],
  "authorization": {
    "code": "EPS-2025-001234",
    "status": "APPROVED",
    "provider": "EPS Sura"
  }
}

PATCH /{id}/status

Changes the status of an encounter.

Request:

{
  "newStatus": "DISCHARGED",
  "notes": "Patient stabilized, discharged with prescription."
}

Response 200 OK

Valid transitions:

Current status Valid target states
CREATED IN_PROGRESS, CANCELLED
IN_PROGRESS DISCHARGED, CANCELLED
DISCHARGED (final state)
CANCELLED (final state)

4. Suppliers Service — /api/v1/doctors

GET /

Lists active doctors with their specialty.

Response 200 OK:

{
  "content": [
    {
      "id": "doc001-...",
      "firstName": "Ana",
      "lastName": "Martinez",
      "specialty": "Cardiology",
      "licenseNumber": "RM-12345",
      "email": "a.martinez@clinica.com",
      "status": "ACTIVE"
    }
  ]
}

GET /{id}/schedule

Returns the doctor's weekly schedule.

Response 200 OK:

{
  "doctorId": "doc001-...",
  "schedule": [
    {
      "dayOfWeek": "MONDAY",
      "startTime": "08:00",
      "endTime": "14:00"
    },
    {
      "dayOfWeek": "WEDNESDAY",
      "startTime": "14:00",
      "endTime": "20:00"
    }
  ]
}

POST /{id}/unavailability

Records an unavailability period (vacation, medical leave, etc.).

Request:

{
  "reason": "Vacation",
  "startDate": "2025-07-01",
  "endDate": "2025-07-15"
}

Response 201 Created

5. Clients Service — /api/v1/health-providers

GET /

Lists all health providers (insurers, HMOs).

Response 200 OK:

{
  "content": [
    {
      "id": "hp001-...",
      "name": "EPS Sura",
      "nit": "890903790-1",
      "type": "EPS",
      "contactEmail": "contracts@sura.com.co",
      "status": "ACTIVE"
    }
  ]
}

GET /{id}/contracts

Returns active contracts with a provider.

Response 200 OK:

{
  "providerId": "hp001-...",
  "contracts": [
    {
      "id": "con001-...",
      "number": "CLN-2025-001",
      "startDate": "2025-01-01",
      "endDate": "2025-12-31",
      "coverageType": "FULL",
      "status": "ACTIVE"
    }
  ]
}

6. AI Assistant Service — /api/v1/ai

POST /chat

Sends a message to the assistant and receives a response with any actions performed.

Request:

{
  "sessionId": "session-abc123",
  "message": "Patient Carlos Rodriguez, ID 1234567890, arrives with severe chest pain, I need to register an urgent RED triage encounter"
}

Response 200 OK:

{
  "sessionId": "session-abc123",
  "reply": "I have registered the emergency encounter for Carlos Rodriguez (ID 1234567890) with triage RED. Encounter ID: att999-...",
  "actionsPerformed": [
    {
      "type": "CREATE_ATTENTION",
      "attentionId": "att999-...",
      "triageLevel": "RED",
      "patientId": "p1a2b3c4-..."
    }
  ],
  "timestamp": "2025-05-19T14:22:05"
}

GET /conversations/{sessionId}

Returns the conversation history for a session.

Response 200 OK:

{
  "sessionId": "session-abc123",
  "messages": [
    {
      "role": "USER",
      "content": "Patient Carlos Rodriguez...",
      "timestamp": "2025-05-19T14:22:00"
    },
    {
      "role": "ASSISTANT",
      "content": "I have registered the emergency encounter...",
      "timestamp": "2025-05-19T14:22:05"
    }
  ]
}

7. Common Error Codes

Code Meaning
400 Malformed request or invalid validation data
401 Missing, expired, or invalid token signature
403 User role does not have permission for this resource
404 Resource not found
409 State conflict (e.g. invalid state transition)
422 Unprocessable entity (business rule violation)
429 Rate limit exceeded — too many requests
500 Internal server error
503 Service unavailable (circuit breaker open)

Standard error format:

{
  "timestamp": "2025-05-19T14:30:00",
  "status": 422,
  "error": "Unprocessable Entity",
  "message": "Cannot discharge a CANCELLED encounter.",
  "path": "/api/v1/attentions/att001-..."
}

Documentation maintained alongside the code — examples reflect current API behavior.

Security — Clínica

Version: 1.0
Stack: Spring Security 6 · JWT RSA-256 · Redis · Resilience4j

1. Security Model

The system implements multiple independent security layers. The failure of one layer does not compromise the others.

Client
  │
  ▼
[1] TLS / HTTPS ────────── encryption in transit
  │
  ▼
[2] Rate Limiting ─────── protection against brute force / DoS
  │
  ▼
[3] JWT Validation ─────── identity and roles verified
  │
  ▼
[4] RBAC ──────────────── role-based authorization
  │
  ▼
Microservice
  │
  ▼
[5] Audit Log ──────────── complete traceability

2. Authentication — JWT RSA-256

2.1 Asymmetric Architecture

Auth Service                    Microservices
     │                               │
     │  Holds:                       │  Hold:
     │  ┌─────────────────┐          │  ┌─────────────────┐
     │  │  Private key    │          │  │   Public key    │
     │  │  (signs tokens) │          │  │ (verifies sign) │
     │  └─────────────────┘          │  └─────────────────┘
     │                               │
     │  Signed JWT                   │
     │ ──────────────────────────►   │
     │                               │  Valid signature? → allow

Security advantage: if a microservice is compromised, the attacker only obtains the public key — they cannot issue new tokens. Only the Auth Service can sign.

2.2 Token Structure

Header:
{
  "alg": "RS256",
  "typ": "JWT"
}

Payload:
{
  "sub": "a1b2c3d4-...",          // userId (UUID)
  "username": "dr.martinez",
  "roles": ["ROLE_DOCTOR"],
  "iat": 1716134400,              // issued at
  "exp": 1716135300               // expires at (15 min)
}

Signature:
  RSA-SHA256(base64(header) + "." + base64(payload), privateKey)

2.3 Token Lifetimes

Token Duration Renewable
Access token 15 min Yes, with refresh token
Refresh token 7 days No — requires new login on expiry

Short-lived access tokens limit the exposure window if a token is intercepted.

2.4 Authentication Flow

[1] Client → POST /api/v1/auth/login
      {username, password}

[2] Auth Service:
      · Looks up user by username
      · Verifies BCrypt(password, stored_hash)
      · If OK: generates access token (RSA-256) + UUID refresh token
      · Stores refresh token in database (hashed)
      · Records event in AuditLog

[3] Response:
      {accessToken, refreshToken, expiresIn: 900}

[4] Client stores tokens securely (not in localStorage)

[5] Subsequent requests:
      Authorization: Bearer <accessToken>

[6] On expiry (401):
      POST /api/v1/auth/refresh
      {refreshToken} → new accessToken

2.5 Logout and Revocation

POST /api/v1/auth/logout
  {refreshToken}

Auth Service:
  · Marks refresh token as REVOKED in database
  · Access token remains technically valid until expiry
    (short duration = maximum 15-min exposure window)
  · Records logout event in AuditLog

3. Account Lockout

The system tracks failed login attempts and automatically locks accounts to prevent brute force attacks.

Failed login attempt:
  1. Increments failed_attempts in users table
  2. If failed_attempts >= MAX_ATTEMPTS (configurable):
     · Sets account_locked_until = NOW() + LOCKOUT_DURATION
     · Records ACCOUNT_LOCKED event in AuditLog

Login with locked account:
  → HTTP 423 Locked
  → Message: "Account locked. Try again after HH:MM."

Unlock:
  · Automatic: when account_locked_until < NOW()
  · Manual: administrator can reset failed_attempts

4. RBAC — Role-Based Access Control

4.1 System Roles

Role Description
ROLE_ADMIN Full access — user and configuration management
ROLE_DOCTOR Encounter management, access to medical records
ROLE_NURSE Triage, encounter status updates
ROLE_RECEPTIONIST Patient registration, encounter creation
ROLE_BILLING Access to billing module

4.2 Permission Matrix

Resource ADMIN DOCTOR NURSE RECEPTIONIST BILLING
Create patient ✓ ✓ ✗ ✓ ✗
View medical record ✓ ✓ ✓ ✗ ✗
Modify medical record ✓ ✓ ✗ ✗ ✗
Create encounter ✓ ✓ ✓ ✓ ✗
Change encounter status ✓ ✓ ✓ ✗ ✗
Access billing ✓ ✗ ✗ ✗ ✓
Manage doctors ✓ ✗ ✗ ✗ ✗
Manage users ✓ ✗ ✗ ✗ ✗
AI chat ✓ ✓ ✓ ✓ ✗

4.3 Implementation

Roles travel inside the JWT. Each microservice extracts roles from the roles claim and applies @PreAuthorize on controllers:

@PreAuthorize("hasAnyRole('DOCTOR', 'ADMIN')")
@GetMapping("/{id}")
public ResponseEntity<PatientResponse> getPatient(@PathVariable UUID id) { ... }

@PreAuthorize("hasRole('ADMIN')")
@DeleteMapping("/{id}")
public ResponseEntity<Void> deletePatient(@PathVariable UUID id) { ... }

No calls are made to the Auth Service at request time — roles are in the token, validation is local.

5. Rate Limiting

The API Gateway implements a per-user token bucket using Redis.

5.1 Token Bucket Algorithm

Initial state: available_tokens[userId] = CAPACITY (e.g. 100)

For each request:
  IF available_tokens[userId] > 0:
    DECREMENT available_tokens[userId]
    ALLOW request
  ELSE:
    RETURN 429 Too Many Requests

Refill (every second):
  available_tokens[userId] = MIN(CAPACITY, tokens + REFILL_RATE)

5.2 Response Headers

The gateway includes rate limiting information in responses:

X-RateLimit-Remaining: 47
X-RateLimit-Limit: 100
X-RateLimit-Reset: 1716134460

5.3 Protection Scenarios

Scenario Protection
Login brute force Rate limit + account lockout after N failures
Patient data scraping Per-userId rate limit prevents bulk extraction
DoS from a user Fast 429, no load on microservice
DoS from anonymous IP Rate limit applied before JWT validation

6. Audit Trail

Every security event is logged to the audit_logs table in the Auth Service.

6.1 Logged Events

Event Saved fields
LOGIN_SUCCESS userId, username, IP, timestamp
LOGIN_FAILED username, IP, timestamp, attempt number N
ACCOUNT_LOCKED userId, IP, timestamp
LOGOUT userId, IP, timestamp
TOKEN_REFRESHED userId, timestamp
PASSWORD_CHANGED userId, IP, timestamp
PASSWORD_RESET userId, email, IP, timestamp

6.2 Soft Delete and Data Audit

All clinical entities carry traceability fields:

deleted_at   DATETIME    NULL   -- null = active
deleted_by   VARCHAR(50) NULL   -- username that deleted
created_at   DATETIME    NOT NULL DEFAULT NOW()
updated_at   DATETIME    NOT NULL DEFAULT NOW() ON UPDATE NOW()
created_by   VARCHAR(50) NOT NULL
updated_by   VARCHAR(50) NOT NULL

This guarantees:

  • Who created a record? → created_by
  • Who last modified it? → updated_by
  • Who "deleted" it and when? → deleted_by, deleted_at
  • Complete reproducibility of any record's state at any point in time

7. Security in Transit

External → Gateway:       HTTPS (TLS 1.2/1.3) — mandatory in production
Gateway → Microservice:   Internal HTTP on Docker network (private, not publicly exposed)
Microservice → Database:  Authenticated connection via database user/password

Database credentials and RSA keys are injected via environment variables (.env), never hardcoded in source code.

8. Design Decisions

8.1 RSA-256 Instead of HMAC-SHA256

Problem: with HMAC, all microservices need the same secret key to verify tokens. A shared secret among N services multiplies the attack surface by N.

Solution: RSA private key only in Auth Service (signing). Public key in each microservice (verification). Compromising a microservice does not expose the ability to issue tokens.

8.2 Hashed Refresh Tokens in Database

Problem: if the Auth database is compromised, exposed refresh tokens would allow impersonating users indefinitely.

Solution: the refresh token stored in the database is the SHA-256 hash of the real value. The client holds the original value; the database holds the hash. A database dump does not reveal usable tokens.

8.3 No Per-Request Role Verification in Auth Service

Problem: centralizing authorization in Auth Service creates a single point of failure. If it goes down, no microservice can verify permissions.

Solution: roles travel in the JWT. Each microservice validates the token signature (with public key, no network call) and applies RBAC locally. Auth Service is not in the hot path of every request.

8.4 Rate Limiting at Gateway, Not Microservices

Problem: if rate limiting is applied at each microservice, an attacker can bypass it by calling internal ports directly.

Solution: rate limiting is enforced at the API Gateway, the only exposed entry point. Microservice ports are not accessible from outside the Docker network.

Document maintained alongside the code — specific configurations (thresholds, durations) are defined in each service's application.yml.
Architecture diagram of Clínica — Sistema de Gestión Hospitalaria
IMAGES