> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iru.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Arquitectura de la plataforma

> Cómo está construido Iru Identity: una arquitectura de servicios de dos planos en regiones aisladas, diseñada para la residencia de datos, la fiabilidad y la observabilidad.

Iru Identity es un servicio en la nube creado para ser el centro fiable de tu acceso.
A continuación se explica cómo está construido el servicio y qué implica eso para la fiabilidad y el aislamiento.

## Dos planos, separados por función

La plataforma se divide en dos servicios que se implementan de forma independiente y comparten un
núcleo común organizado en capas. Mantener el aprovisionamiento privilegiado separado del tráfico de
solicitudes de cada tenant reduce el alcance del impacto de cada uno.

```mermaid theme={null}
flowchart TB
  subgraph cp["Plano de control"]
    tprov["Ciclo de vida de tenants<br/>(crear / eliminar)"]
    jwks["Publicación de claves públicas (JWKS)"]
    tmpl["Sincronización de plantillas de aplicaciones"]
  end
  subgraph tp["API de tenants"]
    iam["API de IAM por tenant"]
    work["Procesos de aprovisionamiento en segundo plano"]
  end
  cp -->|"aprovisiona"| tp
  people["Tus administradores y usuarios"] --> tp
  apps["Tus aplicaciones"] --> tp
```

| Plano | Responsabilidad | Por qué está separado |
| - | - | - |
| **Plano de control** | Crear y eliminar tenants, publicar claves de firma y sincronizar el catálogo de plantillas de aplicaciones. | Una superficie pequeña y privilegiada que se mantiene alejada del tráfico de solicitudes de los clientes. Las operaciones de tenants requieren un token que se compara en tiempo constante; la credencial de sincronización de plantillas se obtiene en cada solicitud desde un almacén de secretos gestionado para que las rotaciones surtan efecto de inmediato. |
| **API de tenants** | La API de identidad y acceso orientada al cliente, además de procesos en segundo plano que aprovisionan cuentas en tus aplicaciones. | La superficie de alto tráfico que realmente usan tus usuarios y aplicaciones, con el aprovisionamiento gestionado de forma asíncrona para que una aplicación dependiente lenta nunca bloquee el inicio de sesión. |

## Un núcleo organizado en capas y disciplinado

Ambos servicios están desarrollados en Go sobre una arquitectura en capas con una regla de dependencia
unidireccional. Un nivel de **plataforma** aplicado por separado se sitúa por debajo de las capas
de producto y se encarga del aislamiento de tenants y de las primitivas de identidad. **Foundation** se mantiene
sin dependencias para las utilidades de infraestructura compartidas que no llevan contexto
de tenant.

<Steps>
  <Step title="Plataforma">
    Aislamiento de tenants y columna vertebral de la identidad: acceso a la base de datos, sesiones, resolución de tenant y
    región, actor, registro y gestión de URL públicas. Este nivel se
    revisa y aplica por separado para que el aislamiento quede fuera del código de producto
    habitual.
  </Step>

  <Step title="Base">
    Utilidades de infraestructura compartidas que no dependen de nada por encima de ellas (por
    ejemplo, criptografía y rastreo). Los aspectos limitados al tenant residen en platform, no
    aquí.
  </Step>

  <Step title="Dominio">
    Lógica de negocio por entidad (usuarios, aplicaciones, políticas…). Depende de
    platform y foundation, no de usecase ni de REST.
  </Step>

  <Step title="Caso de uso">
    Coordina varios servicios de dominio para flujos complejos.
  </Step>

  <Step title="REST">
    Controladores HTTP y middleware, la única capa que se comunica a través de la red.
  </Step>
</Steps>

<Note>
  La organización en capas es una convención documentada y **aplicada mediante revisión** (respaldada por linting
  y la estructura de directorios), no un invariante garantizado por el compilador. Lo indicamos
  con honestidad en lugar de exagerar.
</Note>

Las pruebas siguen la misma disciplina: la lógica de negocio pura se prueba con pruebas unitarias sin
mocks, y el comportamiento se valida con **pruebas de integración que se ejecutan contra una base de datos
PostgreSQL real**, de modo que las pruebas ejercitan la misma seguridad a nivel de fila y el mismo comportamiento de auditoría
que se ejecutan en producción, no una aproximación simulada.

## Alojamiento y refuerzo de la seguridad

Iru Identity se ejecuta en **AWS**, con una implementación con seguridad reforzada:

<CardGroup cols={2}>
  <Card title="Contenedores reforzados" icon="cubes">
    Los servicios se ejecutan en AWS Fargate sin privilegios de root, con un **sistema de archivos raíz de solo lectura**,
    **no-new-privileges** y todas las capacidades de Linux eliminadas.
  </Card>

  <Card title="Sin contraseñas de base de datos permanentes" icon="key">
    La aplicación se conecta a **PostgreSQL gestionado (Amazon RDS)** mediante
    **tokens de autenticación de IAM** de corta duración. No hay ninguna contraseña de base de datos estática que
    pueda filtrarse.
  </Card>

  <Card title="Los secretos se mantienen fuera del código" icon="vault">
    Las credenciales y las claves de firma se inyectan desde un almacén de secretos gestionado en
    tiempo de ejecución, nunca se confirman en el repositorio ni se almacenan en la base de datos en texto
    sin cifrar.
  </Card>

  <Card title="Cadena de suministro analizada" icon="magnifying-glass">
    Las imágenes de contenedor se analizan en busca de vulnerabilidades en el pipeline de CI antes de que
    puedan publicarse.
  </Card>
</CardGroup>

Los recursos estáticos se sirven a través de una CDN (Fastly), y los entornos de vista previa de corta duración
para pruebas se ejecutan en Google Cloud Run.

## Dos regiones, residencia de datos real

Iru Identity opera en **dos regiones aisladas (Estados Unidos `us-east-2` y
Unión Europea `eu-central-1`)**, y la residencia se aplica en el código, no por
convención.

```mermaid theme={null}
flowchart LR
  req["Solicitud"] --> mw["Resolver el tenant<br/>a partir del subdominio"]
  mw --> reg{"¿Región del<br/>tenant?"}
  reg -->|"EE. UU."| usdb[("Base de datos de EE. UU.")]
  reg -->|"UE"| eudb[("Base de datos de la UE")]
  reg -->|"desconocida"| rej["Rechazada"]
```

* Cada tenant está **fijado a una región**, que se almacena en el registro del tenant.
* La capa de base de datos mantiene **pools de conexiones independientes por región** y enruta
  cada transacción según la región del tenant. Una solicitud cuya región no se puede
  resolver se **rechaza**. Nunca recurre silenciosamente a otra región.
* Las operaciones de datos específicas de una región (como los datos iniciales) están controladas para que no puedan ejecutarse
  en la región equivocada.

El resultado: los datos de un tenant de la UE solo se leen y escriben en infraestructura
de la UE. Consulta [Aislamiento multitenant](/es/identity/security/multi-tenant-isolation)
para ver cómo continúa el aislamiento *dentro* de cada base de datos regional.

## Diseñado para mantenerse disponible y ser observable

<AccordionGroup>
  <Accordion title="Comprobaciones de estado y apagado ordenado" icon="heart-pulse">
    Un endpoint de actividad sin dependencias permite al orquestador realizar sondeos sin
    tocar la base de datos ni la autenticación. Al apagarse, los servicios dejan de aceptar tráfico
    y vacían en orden el rastreo, los informes de errores y las conexiones de base de datos.
  </Accordion>

  <Accordion title="Acceso a datos resiliente" icon="database">
    Los pools de conexiones están ajustados y limitados, hacen ping a su base de datos al iniciarse y
    **fallan rápidamente** si no está accesible, en lugar de atender solicitudes defectuosas.
  </Accordion>

  <Accordion title="Aprovisionamiento con consistencia eventual" icon="arrows-rotate">
    El aprovisionamiento de cuentas en tus aplicaciones se ejecuta mediante un bucle de **outbox y conciliación**
    en procesos en segundo plano que tienen en cuenta las cancelaciones, de modo que los cambios dependientes se
    reintentan hasta que se completan correctamente en lugar de perderse.
  </Accordion>

  <Accordion title="Rastreo de extremo a extremo" icon="diagram-project">
    Las solicitudes se rastrean con **OpenTelemetry** desde HTTP, pasando por el código de la aplicación,
    hasta la consulta SQL, y los registros estructurados se correlacionan por tenant e ID de
    rastreo. Los errores se capturan de forma centralizada con muestreo para equilibrar la fidelidad y el coste.
  </Accordion>

  <Accordion title="Migraciones y auditoría verificables" icon="file-shield">
    Los cambios de esquema están integrados, ordenados por versión y **verificados mediante sumas de comprobación** (una
    migración ya aplicada que se modifica es un fallo grave). Un comprobador permanente
    verifica que el diario de auditoría de cada tabla se mantiene sincronizado con su esquema activo.
  </Accordion>
</AccordionGroup>

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Aislamiento multitenant" icon="database" href="/es/identity/security/multi-tenant-isolation">
    Cómo la seguridad a nivel de fila y la auditoría de solo anexión mantienen los datos de cada tenant
    separados y con constancia de cualquier manipulación.
  </Card>

  <Card title="Arquitectura de autenticación" icon="signature" href="/es/identity/security/authentication-architecture">
    Inicio de sesión resistente al phishing, solicitudes firmadas y cómo se establece la confianza de SSO.
  </Card>

  <Card title="Seguridad y privacidad" icon="lock" href="/es/identity/security/security-and-privacy">
    Las garantías que suman estos mecanismos.
  </Card>

  <Card title="Arquitectura del sistema" icon="sitemap" href="/es/identity/getting-started/system-architecture">
    La visión orientada al cliente de cómo fluyen las identidades y el inicio de sesión.
  </Card>
</CardGroup>