Architecture

Authrim separates protocol handling, administration, database placement, and extension execution into cooperating services. Setup generates the bindings and resources that connect them.

System overview

flowchart TB
    Client["Applications and browsers"] --> Router["ar-router"]
    Router --> Protocol["Authentication and protocol Workers"]
    Router --> Management["ar-management"]
    Protocol --> State["Durable Objects"]
    Protocol --> Lookup["Lookup and verified account routes"]
    Lookup --> Data["Core and PII databases"]
    Management --> Control["ar-control"]
    Control --> Registry["Signed runtime registry"]
    Registry --> Lookup
    Protocol --> Plugins["ar-plugin-runner"]

Worker / area	Responsibility
ar-router	Public request routing and shared request handling through Service Bindings
ar-discovery	OIDC Discovery and JWKS
ar-auth	Authorization, login, consent, and authentication flow handling
ar-token, ar-userinfo	Token issuance/operations and UserInfo
ar-async	Device Authorization and CIBA protocol handling; not the owner of every background job
ar-saml, ar-bridge	SAML IdP/SP and external identity-provider federation
ar-management	Management APIs and operational handlers
ar-policy, ar-vc	Policy evaluation and credential issuer/verifier routes
ar-control	Placement, capacity, and signed registry publication
ar-plugin-runner	Scoped plugin execution, notification delivery, and hook processing
ar-admin-ui, ar-login-ui	Administrative and user-facing interfaces

Lookup routing is implemented in shared services; account-directory coordination uses named RPC entrypoints in ar-management. It is not a separate ar-lookup Worker.

ar-lib-core contains shared types, repositories, routing, and protocol-state services. Libraries do not replace the separately deployed Workers that own operational responsibilities.

Storage architecture

Core, PII, Admin, Control, Lookup, and Plugin Runner are separate schema families. Tenant metadata and account data can resolve to different stores, and a deployment may have many account shards.

D1 placement belongs to the Control Plane. The runtime registry identifies stores by role, shard, binding, residency partition, and generation. Account lookup uses blind indexes and resolves both Core and PII destinations. Runtime code validates signed routing information and revalidates destination metadata; an invalid route is not an instruction to fall back to shared data.

Current runtime profiles are audit and residency profiles. The old shared-d1, tenant-d1, and external-durable profile model is no longer the account-storage contract. The current tenant database resolver accepts D1; external SQL adapters used elsewhere do not imply interchangeable account routing.

See PII Separation for canonical tables, sensitive-value reads, and deletion behavior.

Durable Object state and sharding

Durable Objects coordinate sessions, authorization codes, refresh-token rotation, challenges, rate limits, PAR, replay detection, and other protocol state. D1 persistence or mirrors are specific to the service; these stores are not one generic cache tier.

Setup exposes authCodeShards, refreshTokenShards, sessionShards, and challengeShards, each with a default of 4. These settings concern their respective state services, not the number of D1 account databases. Changing shard topology requires the corresponding routing and lifecycle handling.

Placement and capacity

Control tracks capacity and placement for managed databases. Shared pools and tenant-exclusive placement are distinct policies. Runtime routes carry the exact target and generation, so changing capacity is more than changing a binding name.

Worker placement, Durable Object placement, database residency, and storage isolation are separate choices. A location hint is not a guarantee that an entire login flow executes in one region.

Caches and asynchronous work

KV holds configuration, caches, and signed runtime documents. Consumers validate the relevant identity and generation before trusting routing data. Process-local caches are optimizations, not durable authority.

Queues, scheduled handlers, durable operations, and outboxes serve different workloads. Plugin Runner, for example, handles asynchronous hooks with retry state; management and Control also have their own scheduled work. Do not treat ar-async as a universal job worker.

Installation and upgrades

Setup manages generated deployment files and release migration plans. Baselines initialize empty databases; upgrades use the applicable release plan. Do not rebuild topology by manually applying the obsolete root-level migration list. See Installation.

For related concepts, see Multi-Tenancy, Edge Computing, and Plugins.