feat: Volumen 1. ARQUITECTURA

.gitignore

@@ -6,3 +6,13 @@ fsh-generated/
 template/
 input-cache/
 output/
+
+*.bkp
+
+__pycache__
+
+# draw.io autosave files
+_diagrams/.$*
+
+# the publisher writes this to the root on every build
+Requirements-fromNarrative.json

.markdownlint.jsonc

@@ -7,5 +7,10 @@
     // kramdown attaches `{: .table ...}` to the table above it; a GFM parser
     // reads that line as one more (malformed) row.
     "MD055": false,
-    "MD056": false
+    "MD056": false,
+    // IHE use cases repeat "Descripción del caso de uso" / "Flujo del proceso"
+    // under each case; only siblings must be unique.
+    "MD024": { "siblings_only": true },
+    // Bootstrap tabs (the template ships the plugin) are the only raw HTML.
+    "MD033": { "allowed_elements": ["ul", "li", "a", "div"] }
 }

Makefile

@@ -5,12 +5,13 @@
 # anywhere else.
 
 .DEFAULT_GOAL := help
-.PHONY: help preview site docs all format tools clean
+.PHONY: help preview site docs diagrams all format tools clean
 
 help:
 	@echo "make preview   write, with live reload      http://localhost:4000"
 	@echo "make site      build the site               dist/site/index.html"
 	@echo "make docs      build PDF, DOCX, llms.txt    dist/"
+	@echo "make diagrams  render the PlantUML sources  input/images/"
 	@echo "make all       site + docs"
 	@echo "make format    format the pages             input/pagecontent/"
 	@echo "make tools     download the IG Publisher    .work/tools/"
@@ -25,6 +26,10 @@ site:
 docs:
 	@_scripts/build-docs.sh
 
+# Needs the publisher jar (make tools): PlantUML ships inside it.
+diagrams:
+	@_scripts/build-diagrams.sh
+
 all: site docs
 
 # Fixes blank lines, list markers, heading and emphasis style, trailing spaces;

_diagrams/hix-actores-hospital.plantuml

@@ -0,0 +1,53 @@
+@startuml hix-actores-hospital
+!pragma layout smetana
+hide stereotype
+skinparam shadowing false
+skinparam defaultFontName Verdana
+skinparam defaultFontSize 11
+skinparam nodesep 12
+skinparam ranksep 18
+skinparam rectangle {
+  BorderColor #555555
+  RoundCorner 12
+  FontStyle bold
+}
+skinparam rectangle<<inner>> {
+  BackgroundColor white
+  BorderColor #444444
+  BorderStyle dashed
+  RoundCorner 0
+  FontStyle plain
+  FontSize 10
+}
+skinparam arrow {
+  Color #333333
+  FontSize 9
+}
+left to right direction
+rectangle "Hospital (consumidor)" as HOSP #DAE8FC {
+  rectangle "IUA Authorization Client" <<inner>> as H1
+  rectangle "MHD Document Consumer" <<inner>> as H2
+  rectangle "PIXm / PDQm Consumer" <<inner>> as H3
+}
+rectangle "Authorization Server (STS)" as STS #F5F5F5 {
+  rectangle "IUA Authorization Server" <<inner>> as STS1
+  rectangle "OpenID Provider" <<inner>> as STS2
+  rectangle "PIXm Consumer" <<inner>> as STS3
+}
+rectangle "Record Locator Service (Mediador)" as RLS #D5E8D4 {
+  rectangle "IUA Resource Server" <<inner>> as RLS1
+  rectangle "IUA Authorization Client" <<inner>> as RLS0
+  rectangle "MHD Document Responder" <<inner>> as RLS2
+  rectangle "MHD Document Consumer (delegated)" <<inner>> as RLS3
+  rectangle "PIXm / PDQm Consumer (delegated)" <<inner>> as RLS4
+}
+rectangle "Custodio" as CUST #FFE6CC {
+  rectangle "IUA Resource Server" <<inner>> as CUST1
+  rectangle "MHD Document Responder" <<inner>> as CUST2
+}
+H1 --> STS1 : [ITI-71] Get Access Token\natención: purpose_of_use = TREAT\nemergencia: purpose_of_use = ETREAT
+H3 --> RLS4 : atención: [ITI-83] resuelve su identificador local\nemergencia: [ITI-78] busca por datos demográficos
+H2 --> RLS2 : [ITI-67] Find Document References\n[ITI-68] Retrieve Document
+STS1 <-- RLS0 : [HIX-1] Custodian Token Exchange
+RLS3 --> CUST2 : [ITI-68] Retrieve Document\ntoken derivado, aud = custodio
+@enduml

_diagrams/hix-actores-laboratorio.plantuml

@@ -0,0 +1,50 @@
+@startuml hix-actores-laboratorio
+!pragma layout smetana
+hide stereotype
+skinparam shadowing false
+skinparam defaultFontName Verdana
+skinparam defaultFontSize 11
+skinparam nodesep 12
+skinparam ranksep 18
+skinparam rectangle {
+  BorderColor #555555
+  RoundCorner 12
+  FontStyle bold
+}
+skinparam rectangle<<inner>> {
+  BackgroundColor white
+  BorderColor #444444
+  BorderStyle dashed
+  RoundCorner 0
+  FontStyle plain
+  FontSize 10
+}
+skinparam arrow {
+  Color #333333
+  FontSize 9
+}
+left to right direction
+rectangle "Laboratorio (custodio)" as LAB #DAE8FC {
+  rectangle "IUA Authorization Client" <<inner>> as L1
+  rectangle "PIXm Patient Identity Source" <<inner>> as L2
+  rectangle "MHD Document Source" <<inner>> as L3
+  rectangle "MHD Document Responder" <<inner>> as L4
+  rectangle "IUA Resource Server" <<inner>> as L5
+}
+rectangle "Authorization Server (STS)" as STS #F5F5F5 {
+  rectangle "IUA Authorization Server" <<inner>> as STS1
+  rectangle "OpenID Provider" <<inner>> as STS2
+  rectangle "PIXm Consumer" <<inner>> as STS3
+}
+rectangle "Record Locator Service (Mediador)" as RLS #D5E8D4 {
+  rectangle "IUA Authorization Client" <<inner>> as RLS0
+  rectangle "IUA Resource Server" <<inner>> as RLS1
+  rectangle "MHD Document Consumer (delegated)" <<inner>> as RLS3
+}
+L1 --> STS1 : [ITI-71] Get Access Token\npurpose_of_use = TREAT
+L2 --> RLS : [ITI-104] Patient Identity Feed\nidentidad local + identificador nacional
+L3 --> RLS : [ITI-65] Provide Document Bundle\npuntero con custodio y securityLabel
+STS1 <-u- RLS0 : [HIX-1] Custodian Token Exchange
+RLS3 --> L4 : [ITI-68] Retrieve Document\ntoken derivado, aud = laboratorio\ncuando otro miembro recupera
+L4 -[hidden]-> RLS1
+@enduml

_diagrams/hix-actores-paciente.plantuml

@@ -0,0 +1,51 @@
+@startuml hix-actores-paciente
+!pragma layout smetana
+hide stereotype
+skinparam shadowing false
+skinparam defaultFontName Verdana
+skinparam defaultFontSize 11
+skinparam nodesep 12
+skinparam ranksep 18
+skinparam rectangle {
+  BorderColor #555555
+  RoundCorner 12
+  FontStyle bold
+}
+skinparam rectangle<<inner>> {
+  BackgroundColor white
+  BorderColor #444444
+  BorderStyle dashed
+  RoundCorner 0
+  FontStyle plain
+  FontSize 10
+}
+skinparam arrow {
+  Color #333333
+  FontSize 9
+}
+left to right direction
+rectangle "Aplicación del paciente" as APP #DAE8FC {
+  rectangle "IUA Authorization Client" <<inner>> as APP1
+  rectangle "MHD Document Consumer" <<inner>> as APP2
+}
+rectangle "Authorization Server (STS)" as STS #F5F5F5 {
+  rectangle "IUA Authorization Server" <<inner>> as STS1
+  rectangle "OpenID Provider" <<inner>> as STS2
+  rectangle "PIXm Consumer" <<inner>> as STS3
+}
+rectangle "Record Locator Service (Mediador)" as RLS #D5E8D4 {
+  rectangle "IUA Resource Server" <<inner>> as RLS1
+  rectangle "IUA Authorization Client" <<inner>> as RLS0
+  rectangle "MHD Document Responder" <<inner>> as RLS2
+  rectangle "MHD Document Consumer (delegated)" <<inner>> as RLS3
+  rectangle "PIXm / PDQm Consumer (delegated)" <<inner>> as RLS4
+}
+rectangle "Custodio" as CUST #FFE6CC {
+  rectangle "IUA Resource Server" <<inner>> as CUST1
+  rectangle "MHD Document Responder" <<inner>> as CUST2
+}
+APP1 --> STS1 : [HIX-2] Patient Application Launch\npurpose_of_use = PATRQT, FAMRQT o PWATRNY\npaciente = identidad maestra
+APP2 --> RLS2 : [ITI-67] Find Document References\n[ITI-68] Retrieve Document\ntoken aud = RLS, confinado al paciente
+STS1 <-- RLS0 : [HIX-1] Custodian Token Exchange
+RLS3 --> CUST2 : [ITI-68] Retrieve Document\ntoken derivado, aud = custodio
+@enduml

_diagrams/hix-delegacion.plantuml

@@ -0,0 +1,48 @@
+@startuml hix-delegacion
+!pragma layout smetana
+skinparam shadowing false
+skinparam defaultFontName Verdana
+skinparam defaultFontSize 11
+skinparam rectangle {
+  BackgroundColor white
+  BorderColor #555555
+  RoundCorner 8
+}
+skinparam arrow {
+  Color #333333
+  FontSize 9
+}
+skinparam note {
+  BackgroundColor #FFFDF0
+  BorderColor #999999
+  FontSize 9
+}
+left to right direction
+
+rectangle "Miembros" as MIEMBROS #F4F4F4 {
+  rectangle "Miembro\nsolicitante" as M
+}
+
+rectangle "Infraestructura central" as CENTRO #EEF5EE {
+  rectangle "Authorization\nServer" as AS
+  rectangle "Record Locator\nService (PEP)" as RLS
+  rectangle "Document\nRegistry" as REG
+}
+
+rectangle "Custodios" as CUSTODIOS #F4F4F4 {
+  rectangle "Custodio A" as A
+  rectangle "Custodio B" as B
+}
+
+M --> RLS : token del miembro\naud = RLS
+RLS --> AS : intercambio [HIX-1]\nresource = custodio X
+AS --> RLS : token derivado\naud = custodio X\nsub = miembro\nact = RLS
+RLS --> REG : token\naud = Document Registry
+RLS --> A : token\naud = Custodio A
+RLS --> B : token\naud = Custodio B
+note bottom of B
+  Cada destino valida el token por sí mismo,
+  con las claves públicas del Authorization Server,
+  sin llamar a nadie.
+end note
+@enduml

_diagrams/hix-flujo-identidad.plantuml

@@ -0,0 +1,39 @@
+@startuml hix-flujo-identidad
+skinparam shadowing false
+skinparam defaultFontName Verdana
+skinparam defaultFontSize 11
+skinparam sequenceMessageAlign center
+skinparam ParticipantPadding 10
+skinparam sequence {
+  ArrowColor #333333
+  LifeLineBorderColor #999999
+  ParticipantBorderColor #555555
+  ParticipantBackgroundColor white
+  GroupBorderColor #999999
+}
+
+participant "Fuente autoritativa\n(p. ej. EDUS)" as SRC
+participant "Registro de\nidentidad maestra" as PMIR
+participant "Record Locator\nService" as RLS
+participant "Custodio" as K
+participant "Consumidor" as C
+
+== Identidad maestra ==
+SRC -> PMIR : [ITI-93] Mobile Patient Identity Feed\n(identidad verificada)
+PMIR -> PMIR : crea o actualiza\nla identidad maestra
+PMIR --> SRC : 200
+
+== Identidad local de un miembro ==
+K -> RLS : [ITI-104] Patient Identity Feed\n(Patient local + identificador comunitario)
+RLS -> RLS : dominio = organización del token
+RLS -> PMIR : [ITI-104] (delegado)
+PMIR -> PMIR : vincula la identidad local\ncon la identidad maestra
+PMIR --> RLS : 200, o 422 si la persona\nno existe en la comunidad
+RLS --> K : resultado
+
+== Resolución ==
+C -> RLS : [ITI-83] Cross-reference Query\n(identificador local o comunitario)
+RLS -> PMIR : [ITI-83] (delegado)
+PMIR --> RLS : identificadores de la persona
+RLS --> C : identificadores permitidos\npor la política
+@enduml

_diagrams/hix-flujo-localizacion.plantuml

@@ -0,0 +1,55 @@
+@startuml hix-flujo-localizacion
+skinparam shadowing false
+skinparam defaultFontName Verdana
+skinparam defaultFontSize 11
+skinparam sequenceMessageAlign center
+skinparam ParticipantPadding 8
+skinparam sequence {
+  ArrowColor #333333
+  LifeLineBorderColor #999999
+  ParticipantBorderColor #555555
+  ParticipantBackgroundColor white
+  GroupBorderColor #999999
+}
+
+participant "Consumidor" as C
+participant "Authorization\nServer" as AS
+participant "Record Locator\nService" as RLS
+participant "Registro de\nidentidad maestra" as PMIR
+participant "Document\nRegistry" as REG
+participant "Directorio" as DIR
+participant "Custodio" as K
+
+== Localización ==
+C -> AS : [ITI-71] Get Access Token
+AS --> C : token (audiencia: RLS)
+C -> RLS : [ITI-67] Find Document References\n(patient) [ITI-72]
+RLS -> AS : [ITI-102] Introspect Token
+AS --> RLS : activo, organización, propósito
+RLS -> PMIR : [ITI-83] identidad maestra
+PMIR --> RLS : identidad maestra
+RLS -> AS : [HIX-1] intercambio\n(resource = Document Registry)
+AS --> RLS : JWT (aud = registro, sub = consumidor,\nact = RLS, vida ≤ 120 s)
+RLS -> REG : [ITI-67] [ITI-72]
+REG --> RLS : punteros
+RLS -> RLS : decisión de divulgación por puntero\nURL de contenido → RLS
+RLS --> C : Bundle de punteros divulgados
+
+== Recuperación ==
+C -> RLS : [ITI-68] Retrieve Document\n(URL del RLS) [ITI-72]
+RLS -> AS : [ITI-102] Introspect Token
+RLS -> RLS : relee el puntero\nrecomprueba la divulgación
+RLS -> DIR : [ITI-90] custodio → endpoint
+DIR --> RLS : endpoint activo del custodio
+RLS -> AS : [HIX-1] Custodian Token Exchange\n(resource = custodio)
+AS --> RLS : JWT (aud = custodio, sub = consumidor,\nact = RLS, vida ≤ 120 s)
+RLS -> K : [ITI-68] Retrieve Document [ITI-72]
+K -> K : validación local del JWT
+alt el custodio responde
+  K --> RLS : documento
+  RLS --> C : documento
+else el custodio no responde
+  RLS --> C : OperationOutcome (transitorio)
+end
+note over C, K : Cada llamada del RLS a un servicio central o a un custodio va precedida de un intercambio [HIX-1] a nombre del solicitante; se muestra solo donde importa.\nCada actor registra sus eventos [ITI-20] bajo el identificador de correlación de la operación.
+@enduml

_diagrams/hix-flujo-paciente.plantuml

@@ -0,0 +1,44 @@
+@startuml hix-flujo-paciente
+skinparam shadowing false
+skinparam defaultFontName Verdana
+skinparam defaultFontSize 11
+skinparam sequenceMessageAlign center
+skinparam ParticipantPadding 10
+skinparam sequence {
+  ArrowColor #333333
+  LifeLineBorderColor #999999
+  ParticipantBorderColor #555555
+  ParticipantBackgroundColor white
+  ActorBorderColor #555555
+  ActorBackgroundColor white
+  GroupBorderColor #999999
+}
+
+actor "Persona" as P
+participant "Aplicación\ndel paciente" as APP
+participant "Authorization\nServer" as AS
+participant "Fuente autoritativa\n(p. ej. EDUS)" as SRC
+participant "Registro de\nidentidad maestra" as PMIR
+participant "Record Locator\nService" as RLS
+
+== Enrolamiento (una vez) ==
+P -> AS : crea su cuenta
+AS -> SRC : verificación de identidad
+SRC --> AS : identidad verificada
+AS --> P : cuenta enlazada a la\nidentidad verificada
+
+== Lanzamiento [HIX-2] ==
+APP -> AS : authorization code + PKCE,\ncontexto de lanzamiento de paciente
+AS -> P : autenticación y consentimiento
+P --> AS : autoriza
+AS -> PMIR : [ITI-83] identidad verificada → identidad maestra
+PMIR --> AS : identidad maestra
+AS --> APP : token (audiencia: RLS,\ncontexto de paciente = identidad maestra)
+
+== Acceso ==
+APP -> RLS : [ITI-67] / [ITI-68] [ITI-72]
+RLS -> AS : [ITI-102] Introspect Token
+AS --> RLS : activo, contexto de paciente
+RLS -> RLS : confina la operación\nal paciente del contexto
+RLS --> APP : punteros o documento
+@enduml