CodeMed AI API

AI Agent SaaS para Codificación Clínica Automatizada (ICD-10 / CPT)

---

Concepto

La codificación médica es el proceso de traducir notas clínicas en texto libre a códigos estándar de facturación (ICD-10-CM para diagnósticos, CPT para procedimientos). Es un proceso manual, lento y costoso — uno de los mayores centros de coste en Revenue Cycle Management (RCM).

CodeMed AI automatiza este proceso con un agente de IA que:

1. Ingesta notas clínicas no estructuradas vía API segura
2. Sugiere códigos ICD-10 y CPT con puntuación de confianza
3. Proporciona el fragmento de texto exacto que justifica cada código (explainability)
4. Expone un Dashboard REST para que codificadores humanos revisen, aprueben o corrijan antes del envío a billing

---

Arquitectura

┌──────────────┐  POST /documents   ┌────────────────┐   @Async VirtualThread
│  API Client  │ ─────────────────▶ │CodingController│ ──────────────────────▶ ┌──────────────────┐
│  (EHR/RCM)   │                    └────────────────┘                          │CodingWorkerService│
└──────────────┘                             │ JWT Auth                          │  (pipeline IA)    │
                                             ▼                                   └──────────────────┘
┌──────────────┐  GET /documents/{id}┌────────────────┐                                   │
│  Dashboard   │ ─────────────────▶ │  CodingService │                          ┌─────────▼────────┐
│   (Coders)   │                    └────────────────┘                          │  AIModelClient   │
│              │  PUT .../validate   ┌──────────────────┐                       │ (OpenAI/Mock)    │
│              │ ─────────────────▶ │DashboardController│                       └──────────────────┘
└──────────────┘                    └──────────────────┘
                                             │
                                    ┌────────▼────────┐
                                    │  H2 / PostgreSQL │
                                    │  (JPA/Hibernate) │
                                    └─────────────────┘

Capas:

• controller/ — REST endpoints, validación de entrada
• service/ — Lógica de negocio, orquestación
• client/ — Integración con LLM externo (OpenAI-compatible)
• model/ — Entidades JPA + enums del dominio
• repository/ — Spring Data JPA
• config/ — Security, Async, Properties, Exception handling
• dto/ — Records inmutables para request/response

Procesamiento asíncrono: %%INLINE7%% + %%INLINE8%% (Java 25). Cada documento se procesa en su propio Virtual Thread sin bloquear el thread del request HTTP.

---

Endpoints

Autenticación (públicos)

Método	Path	Body	Respuesta
%%INLINE9%%	%%INLINE10%%	%%INLINE11%%	%%INLINE12%%
%%INLINE13%%	%%INLINE14%%	%%INLINE15%%	%%INLINE16%%

Codificación (requieren Authorization: Bearer <token>)

Método	Path	Body	Respuesta
%%INLINE18%%	%%INLINE19%%	%%INLINE20%%	%%INLINE21%% (202)
%%INLINE22%%	%%INLINE23%%	—	DocumentStatusResponse (200)

Dashboard (requieren JWT; %%INLINE25%% requiere rol %%INLINE26%% o ADMIN)

Método	Path	Params/Body	Respuesta
%%INLINE28%%	%%INLINE29%%	%%INLINE30%% (opcional)	%%INLINE31%%
%%INLINE32%%	%%INLINE33%%	—	DocumentStatusResponse
%%INLINE35%%	%%INLINE36%%	%%INLINE37%%	%%INLINE38%%

Health

Método	Path	Respuesta
%%INLINE39%%	%%INLINE40%%	{status, service, timestamp}

DocumentStatusResponse — estructura

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "COMPLETED",
  "submittedAt": "2026-05-07T10:30:00",
  "processedAt": "2026-05-07T10:30:02",
  "submittedBy": "coder",
  "suggestionCount": 3,
  "suggestions": [
    {
      "id": "...",
      "codeType": "ICD10",
      "code": "E11.9",
      "description": "Type 2 diabetes mellitus without complications",
      "confidence": 0.93,
      "evidenceSnippet": "Patient has a history of type 2 diabetes managed with metformin",
      "approved": false,
      "reviewerNotes": null
    },
    {
      "codeType": "CPT",
      "code": "99213",
      "description": "Office/outpatient visit, established patient, low to moderate complexity",
      "confidence": 0.85,
      "evidenceSnippet": "Follow-up visit for established patient..."
    }
  ]
}

---

Análisis de Negocio

Problema

• Codificadores médicos procesan 50-100 documentos/día manualmente
• Error rate del 10-30% → denegaciones de reclamos → pérdida de ingresos
• Costo promedio: $15-25 USD por documento codificado manualmente

Solución

• Automatización parcial (Human-in-the-loop) → 80%+ precisión con revisión humana
• Reducción del tiempo de codificación: de 8-15 min a 2-3 min por documento
• ROI directo: hospitales ahorran $200K-2M USD anuales

Modelo de Monetización (B2B SaaS)

Tier	Documentos/mes	Precio
Starter	500	$299/mes
Growth	5,000	$1,999/mes
Enterprise	Ilimitado	Custom

Mercado

• TAM (Total Addressable Market): $22B (US Medical Billing & Coding Market 2025)
• SAM: $4B (Segmento SaaS/automatización)
• SOM (Year 1): $2M ARR con 5-10 clientes enterprise medianos

---

Cómo Ejecutar

Requisitos

• Java 25+
• Maven 3.9+

Dev (H2 in-memory, sin configuración)

cd solutions/2026-05-07-codemed-ai-api
mvn spring-boot:run

La app arranca en http://localhost:8080. H2 se auto-configura en memoria. Usuarios demo creados automáticamente.

Con OpenAI (LLM real)

mvn spring-boot:run -Dspring-boot.run.arguments=\
  --app.ai.api-key=sk-... \
  --app.ai.model=gpt-4o

O vía variables de entorno:

export APP_AI_API_KEY=sk-...
export APP_AI_MODEL=gpt-4o
mvn spring-boot:run

Con PostgreSQL (producción)

mvn spring-boot:run \
  -Dspring.datasource.url=jdbc:postgresql://localhost:5432/codemeddb \
  -Dspring.datasource.username=codemed \
  -Dspring.datasource.password=secret \
  -Dspring.jpa.hibernate.ddl-auto=update

Flujo de prueba rápida

# 1. Login
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"coder","password":"coder123"}' | jq -r .token)

# 2. Enviar nota clínica
DOC_ID=$(curl -s -X POST http://localhost:8080/api/v1/documents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"clinicalNotes":"Patient is a 58-year-old male with type 2 diabetes and hypertension. Follow-up visit for established patient. HbA1c ordered."}' | jq -r .id)

# 3. Consultar resultado (esperar ~1s para procesamiento async)
curl -s http://localhost:8080/api/v1/documents/$DOC_ID \
  -H "Authorization: Bearer $TOKEN" | jq .

# 4. Ver dashboard
curl -s "http://localhost:8080/api/v1/dashboard/documents?status=COMPLETED" \
  -H "Authorization: Bearer $TOKEN" | jq .

# 5. Validar sugerencias (obtener suggestionId del paso 3)
curl -s -X PUT http://localhost:8080/api/v1/dashboard/documents/$DOC_ID/validate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"validatedCodes":[{"suggestionId":"<UUID>","approved":true}],"reviewerNotes":"Verified by senior coder"}'

---

Cumplimiento HIPAA

• Cifrado en tránsito: Terminar TLS en load-balancer (NGINX/ALB) en producción
• Autenticación: JWT HS256, tokens expiran en 24h
• Autorización: RBAC con roles ADMIN/CODER/APIUSER + %%INLINE44%%
• PHI en reposo: PostgreSQL con cifrado at-rest (AWS RDS Encrypted, etc.)
• Audit trail: Logs estructurados con usuario + documento ID en cada operación
• Supervisión humana: Ningún código llega a billing sin aprobación explícita del codificador

---

Referencias

• AI Agent SaaS Ideas for Fintech & Healthtech
• ICD-10-CM Official Guidelines
• CPT Code Set — AMA
• HIPAA Security Rule — HHS
• Spring Boot 4.0 Reference
• jjwt 0.12.x Migration Guide