> ## 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.

# Platform architecture

> How Iru Identity is built - a two-plane service architecture across isolated regions, engineered for data residency, reliability, and observability.

Iru Identity is a cloud service built to be the trustworthy center of your access.
This page opens the hood on how it's engineered and why that makes it robust.

## Two planes, separated by job

The platform is split into two independently deployed services that share a
common, layered core. Keeping privileged provisioning apart from per-tenant
request traffic shrinks the blast radius of each.

```mermaid theme={null}
flowchart TB
  subgraph cp["Control plane"]
    tprov["Tenant lifecycle<br/>(create / delete)"]
    jwks["Public key publication (JWKS)"]
    tmpl["App-template sync"]
  end
  subgraph tp["Tenant API"]
    iam["Per-tenant IAM API"]
    work["Background provisioning workers"]
  end
  cp -->|"provisions"| tp
  people["Your admins & people"] --> tp
  apps["Your apps"] --> tp
```

| Plane             | Responsibility                                                                                             | Why it's separate                                                                                                                                                                                                                                       |
| ----------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Control plane** | Creating and deleting tenants, publishing signing keys, syncing the application-template catalog.          | A small, privileged surface kept away from customer request traffic. Tenant operations require a token compared in constant time; the template-sync credential is fetched per request from a managed secret store so rotations take effect immediately. |
| **Tenant API**    | The customer-facing identity and access API, plus background workers that provision accounts to your apps. | The high-traffic surface your people and apps actually use, with provisioning handled out-of-band so a slow downstream app never blocks sign-in.                                                                                                        |

## A disciplined, layered core

Both services are built in Go on a four-layer architecture with a one-directional
dependency rule:

<Steps>
  <Step title="Foundation" icon="cube">
    Infrastructure utilities (database, crypto, sessions, tracing). Depends on
    nothing above it.
  </Step>

  <Step title="Domain" icon="boxes-stacked">
    Business logic per entity (users, applications, policies…). Depends only on
    foundation.
  </Step>

  <Step title="Usecase" icon="diagram-project">
    Orchestrates multiple domain services for complex flows.
  </Step>

  <Step title="REST" icon="globe">
    HTTP handlers and middleware - the only layer that speaks the wire.
  </Step>
</Steps>

<Note>
  The layering is a documented, **review-enforced** convention (backed by linting
  and directory structure), not a compiler-guaranteed invariant. We call that out
  honestly rather than overclaiming.
</Note>

Testing follows the same discipline: pure business logic is unit-tested without
mocks, and behavior is validated by **integration tests that run against a real
PostgreSQL database** - so tests exercise the same row-level security and audit
behavior that runs in production, not a stubbed approximation.

## Hosting and hardening

Iru Identity runs on **AWS**, with a security-hardened deployment:

<CardGroup cols={2}>
  <Card title="Hardened containers" icon="cubes">
    Services run on AWS Fargate as non-root with a **read-only root filesystem**,
    **no-new-privileges**, and all Linux capabilities dropped.
  </Card>

  <Card title="No standing database passwords" icon="key">
    The application connects to managed **PostgreSQL (Amazon RDS)** using
    short-lived **IAM authentication tokens** - there is no static DB password to
    leak.
  </Card>

  <Card title="Secrets stay out of code" icon="vault">
    Credentials and signing keys are injected from a managed secret store at
    runtime, never committed to the repository or stored in the database in plain
    text.
  </Card>

  <Card title="Scanned supply chain" icon="magnifying-glass">
    Container images are scanned for vulnerabilities in the CI pipeline before they
    can ship.
  </Card>
</CardGroup>

Static assets are served through a CDN (Fastly), and short-lived preview
environments for testing run on Google Cloud Run.

## Two regions, real data residency

Iru Identity operates in **two isolated regions - United States (`us-east-2`) and
European Union (`eu-central-1`)** - and residency is enforced in code, not by
convention.

```mermaid theme={null}
flowchart LR
  req["Request"] --> mw["Resolve tenant<br/>from subdomain"]
  mw --> reg{"Tenant's<br/>region?"}
  reg -->|"US"| usdb[("US database")]
  reg -->|"EU"| eudb[("EU database")]
  reg -->|"unknown"| rej["Rejected"]
```

* Every tenant is **pinned to a region**, stored on the tenant record.
* The database layer holds **separate connection pools per region** and routes
  every transaction by the tenant's region. A request whose region can't be
  resolved is **rejected** - it never silently falls back to another region.
* Region-specific data operations (such as seed data) are gated so they can't run
  against the wrong region.

The result: an EU tenant's data is read and written only against EU
infrastructure. See [Multi-tenant isolation](/en/identity/security/multi-tenant-isolation)
for how isolation continues *inside* each regional database.

## Built to stay up - and to be observable

<AccordionGroup>
  <Accordion title="Health checks & graceful shutdown" icon="heart-pulse">
    A dependency-free liveness endpoint lets the orchestrator probe without
    touching the database or auth. On shutdown, services stop accepting traffic
    and flush tracing, error reporting, and database connections in order.
  </Accordion>

  <Accordion title="Resilient data access" icon="database">
    Connection pools are tuned and bounded, ping their database at startup, and
    **fail fast** if it's unreachable rather than serving broken requests.
  </Accordion>

  <Accordion title="Eventually-consistent provisioning" icon="arrows-rotate">
    Account provisioning to your apps runs through an **outbox and reconciliation**
    loop in cancellation-aware background workers, so downstream changes are
    retried until they succeed instead of being lost.
  </Accordion>

  <Accordion title="End-to-end tracing" icon="diagram-project">
    Requests are traced with **OpenTelemetry** from HTTP through application code
    down to the SQL query, and structured logs are correlated by tenant and trace
    ID. Errors are captured centrally with sampling to balance fidelity and cost.
  </Accordion>

  <Accordion title="Verifiable migrations & audit" icon="file-shield">
    Schema changes are embedded, version-ordered, and **checksum-verified** (a
    changed, already-applied migration is a hard failure). A standing checker
    proves every table's audit journal stays in sync with its live schema.
  </Accordion>
</AccordionGroup>

## Where to go next

<CardGroup cols={2}>
  <Card title="Multi-tenant isolation" icon="database" href="/en/identity/security/multi-tenant-isolation">
    How row-level security and append-only auditing keep every tenant's data
    separate and tamper-evident.
  </Card>

  <Card title="Authentication architecture" icon="signature" href="/en/identity/security/authentication-architecture">
    Phishing-resistant sign-in, signed requests, and how SSO trust is established.
  </Card>

  <Card title="Security & privacy" icon="lock" href="/en/identity/security/security-and-privacy">
    The guarantees these mechanisms add up to.
  </Card>

  <Card title="System architecture" icon="sitemap" href="/en/identity/getting-started/system-architecture">
    The customer-facing view of how identities and sign-in flow.
  </Card>
</CardGroup>