Skip to content

SergioLM7/klinico-api

BranchesTags

Repository files navigation

Klinico Logo

Klinico API — REST API de Gestión Clínica Hospitalaria

Backend Spring Boot que alimenta la app móvil multiplataforma Klinico para el pase de planta hospitalario diario.

Spring Boot Java PostgreSQL Docker License

Tabla de contenidos

Descripción

Klinico API es el backend REST de la plataforma de gestión clínica hospitalaria Klinico. Expone los endpoints que consume la aplicación móvil Flutter klinico_front, proporcionando la lógica de negocio para gestionar pacientes, admisiones y episodios clínicos diarios.

La API está diseñada bajo Arquitectura Hexagonal (Ports & Adapters) con principios de Domain-Driven Design (DDD), de forma que el núcleo de dominio permanece completamente desacoplado de la capa de infraestructura. Esto permite que el mismo núcleo funcional pueda ser consumido tanto por la app móvil actual como por cualquier otro cliente futuro (web, escritorio).

La autenticación se basa en JWT (Bearer Token) y el control de acceso se gestiona mediante roles (MEDICO, JEFESERVICIO, ADMINISTRATIVO, SYSADMIN). La trazabilidad de cambios en las entidades críticas se garantiza mediante Hibernate Envers.

(volver arriba)

Funcionalidades principales

  • Gestión de pacientes: Registro, seguimiento de estados (Alta, Ingresado, Exitus), edición.
  • Ciclo de Admisiones: Creación, edición, control de ingresos por servicio, flujo de asignación de habitación, flujo para dar de alta al paciente.
  • Episodios Clínicos: Evolución diaria documentada con escalas médicas (Braden, CHADS2, CAM) y con seguridad para evitar modificación de datos por cualquier otro usuario que no haya creado el episodio clínico.
  • Seguridad y auditoría: Autenticación basada en JWT, seguridad por roles (Médico, Jefe de Servicio, Administrativo, Sys Admin) y auditoría automática de campos (createdBy, createdAt. modifiedBy, modifiedAt) junto a Hibernate Envers para dejar constancia de las diferentes modificaciones de las entidades de máxima relevancia.

(volver arriba)

Arquitectura

El proyecto implementa una Arquitectura Hexagonal (Ports & Adapters) con las siguientes capas:

flowchart TB


 subgraph Comm["COMUNICACIÓN"]
        JSON["<b>REST API</b><br>JSON + JWT Header"]
  end

 subgraph Backend["SERVIDOR (Spring Boot)"]
    direction TB
        SEC["<b>Security Filters</b><br>(JWT Filter + SecurityConfig)"]
        BC["<b>Controladores</b><br>(@PreAuthorize + @Validated)"]
        DTOBack["<b>DTOs + Mappers</b><br>(Request/Response + MapStruct)"]
        EH["<b>Exception Handler</b><br>(@RestControllerAdvice)"]
        BS["<b>Aplicación</b><br>(Servicios + Casos de Uso)"]
        BD["<b>Dominio</b><br>(Modelos Ricos + Puertos + Excepciones)"]
        BA["<b>Adaptadores</b><br>(Persistence Adapters)"]
        AUD["<b>Auditoría</b><br>(Spring Auditing + Envers)"]
        BI["<b>Repositorios JPA</b><br>(Spring Data + Entities)"]
        DB[("<b>PostgreSQL</b><br>(Tablas Envers _aud)")]
  end


    JSON == Request ==> BC
    EH -. ErrorResponse .-> JSON
    BC -. Response JSON .-> JSON
    
    SEC --> BC
    BC --> DTOBack
    BC -. Errores .-> EH
    DTOBack --> BS
    BS --> BD
    BD -. Puertos .-> BA
    BA --> BI
    BI -. Persistencia .-> DB
    DB -.-> BI
    AUD -. Transversal .-> BI

  
   style SEC fill:#ffe0e0
    style BC fill:#fff
    style DTOBack fill:#e8f5e9
    style EH fill:#fce4ec
    style AUD fill:#f3e5f5
    style Backend fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style Comm fill:#f5f5f5,stroke:#333,stroke-dasharray: 5 5
    style DB fill:#e3f2fd
Loading

Responsabilidades por capa:

  • Dominio: Modelos de dominio ricos (reglas de negocio encapsuladas en las propias entidades) e interfaces de repositorio (puertos de salida). No depende de ninguna tecnología externa.
  • Aplicación: Servicios y casos de uso que orquestan la lógica de negocio coordinando modelos de dominio y puertos.
  • Infraestructura — REST: Controladores @RestController que reciben las peticiones HTTP, aplican validación de entrada y delegan en los servicios de aplicación.
  • Infraestructura — Persistencia: Adaptadores JPA que implementan los puertos de repositorio del dominio. Usan entidades @Entity mapeadas con MapStruct hacia/desde los modelos de dominio.
  • Infraestructura — Seguridad: Filtro JWT que intercepta cada petición, valida el token y establece el contexto de seguridad de Spring.

(volver arriba)

Estructura del proyecto

src/
└── main/
    ├── java/com/sergio/klinico/
    │   ├── KlinicoApiApplication.java
    │   ├── domain/
    │   │   ├── models/               # Modelos de dominio ricos (Patient, Admission, Episode, User, Service)
    │   │   │                         #   + enums PatientStatus, UserRole
    │   │   ├── repositories/         # Interfaces de puerto — contratos de persistencia
    │   │   └── exceptions/           # AuthException, BusinessException, CustomException
    │   ├── application/
    │   │   └── services/             # Casos de uso y servicios de aplicación
    │   │                             #   AdmissionService, PatientService, EpisodeService,
    │   │                             #   UserService, KpiService, AuditService,
    │   │                             #   LoginUseCase, FindUserByIdUseCase, ...
    │   └── infrastructure/
    │       ├── config/               # SecurityConfig, JwtAuthenticationEntryPoint
    │       ├── mappers/              # Mappers MapStruct (dominio ↔ entidad JPA / DTO)
    │       ├── persistence/          # Entidades @Entity, adaptadores JPA, JpaRepositories,
    │       │                         #   proyecciones, JpaConfig, AuditableEntity
    │       ├── rest/                 # Controladores @RestController, DTOs (Request/Response),
    │       │                         #   validaciones personalizadas, GlobalExceptionHandler
    │       └── security/             # JwtService (JJWT), JwtAuthenticationFilter
    └── resources/
        └── application.yaml         # Configuración de datasource, JPA, Hibernate Envers, logging

(volver arriba)

Stack tecnológico

Categoría Tecnología
Framework Spring Boot 4.0.3
Lenguaje Java 25
Build tool Gradle (Gradle Wrapper incluido)
Seguridad Spring Security + JJWT 0.12.6
Persistencia Spring Data JPA / Hibernate
Auditoría Hibernate Envers
Base de datos PostgreSQL 17
Mapeo de objetos MapStruct 1.6.3
Utilidades Lombok
Validación Spring Validation (Bean Validation)
Contenedores Docker + Docker Compose
Testing Spring Boot Test (JUnit 6)
Documentación API springdoc-openapi 3.0.3 (Swagger UI + OpenAPI 3)

(volver arriba)

Primeros pasos

Prerrequisitos

  • JDK 25 o superior.
  • Docker y Docker Compose (para levantar PostgreSQL o PostgreSQL + API con un solo comando).
  • Gradle no es necesario instalarlo globalmente; el proyecto incluye el Gradle Wrapper (./gradlew).

Variables de entorno

Crea un archivo .env en la raíz del proyecto (puedes partir del .env.example incluido) con las siguientes variables:

Variable Descripción Ejemplo
DB_USER Usuario de PostgreSQL admin
DB_PASSWORD Contraseña de PostgreSQL password
DB_NAME Nombre de la base de datos klinico
JWT_SECRET Clave secreta para firmar los tokens JWT (HS256) miClaveSecretaMuyLarga
JWT_EXPIRATION Tiempo de expiración del token en milisegundos 84000

La URL de conexión se resuelve como jdbc:postgresql://${DB_HOST:localhost}:${DB_PORT:5434}/${DB_NAME}. En local usa los valores por defecto; con Docker Compose se inyectan DB_HOST=db y DB_PORT=5432 automáticamente.

Instalación y ejecución

# 1. Clona el repositorio
git clone https://github.com/SergioLM7/klinico-api
cd klinico-api

# 2. Configura las variables de entorno
cp .env.example .env
# Edita .env y añade JWT_SECRET y JWT_EXPIRATION

# 3. Opción A — Stack completo con Docker (recomendado)
docker compose up --build        # Construye la imagen y arranca BD + API
docker compose up --build api    # Solo reconstruye la API tras cambios
docker compose down              # Para y elimina los contenedores

# 3. Opción B — Desarrollo local (BD en Docker, API con Gradle)
docker-compose up -d #Levanta la base de datos con Docker
./gradlew bootRun #Ejecuta la aplicación con el Gradle Wrapper

# Para generar el JAR ejecutable
./gradlew clean build
java -jar build/libs/klinico-api-0.0.1-SNAPSHOT.jar

(volver arriba)

Documentación API

El proyecto ofrece dos niveles de documentación para la API:

Swagger UI / OpenAPI 3 (endpoints REST)

Disponible en tiempo de ejecución. Arranca la aplicación y accede a:

Recurso URL
Interfaz interactiva (Swagger UI) http://localhost:8080/swagger-ui/index.html
Especificación JSON (OpenAPI 3) http://localhost:8080/v3/api-docs

La UI permite explorar todos los endpoints agrupados por dominio, ver sus parámetros y respuestas, y ejecutar peticiones directamente desde el navegador. Para los endpoints protegidos haz clic en Authorize e introduce el token JWT con el formato Bearer <token>.

Javadoc (código fuente)

Cubre los servicios de aplicación, casos de uso, adaptadores de persistencia y controladores REST.

# Genera la documentación Javadoc
./gradlew javadoc

# Abre la página principal en tu navegador
open build/docs/javadoc/index.html   # macOS
xdg-open build/docs/javadoc/index.html  # Linux
start build/docs/javadoc/index.html  # Windows

El HTML generado queda en build/docs/javadoc/.

(volver arriba)

Repositorio del frontend

La aplicación móvil Flutter que consume esta API está disponible en:

https://github.com/SergioLM7/klinico-front

(volver arriba)

Contacto

Sergio Lillo, Full Stack Software Developer LinkedIn - sergiolillom@gmail.com

(volver arriba)

CONDITIONAL MIT LICENSE (NON-COMMERCIAL USE ONLY)

Copyright (©) 2026, Sergio Lillo

This project is licensed under a Conditional MIT License. It is open for academic and research purposes, but commercial use is strictly prohibited. See the LICENSE file for full details.

(back to top)

About

Klinico App backend to manage ward rounds in a hospital

Resources

Readme

License

View license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages