# authgear/authgear-server architecture

> Architecture diagram of the GitHub repository authgear/authgear-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/authgear/authgear-server
- Repository: https://github.com/authgear/authgear-server

## Overview

Authgear is an authentication and authorization service with end-user flows, an administration API, and a management portal. The principal user journey is an end user entering an AuthUI flow, which reaches server routes and OAuth authorization handling; account-management services support authenticated self-service, including authenticator changes. The README also describes MFA, social and enterprise SSO, hooks, audit logs, and RBAC. Those broader capabilities are shown at subsystem level; the sampled source does not establish all their internal wiring.

Main entry points: [`authui/src/authflowv2.ts`](https://github.com/authgear/authgear-server/blob/main/authui/src/authflowv2.ts) (AuthUI flows), [`pkg/auth/routes.go`](https://github.com/authgear/authgear-server/blob/main/pkg/auth/routes.go) (Auth routes), [`portal/src/graphql/adminapi/query/dynamicClientsQuery.graphql`](https://github.com/authgear/authgear-server/blob/main/portal/src/graphql/adminapi/query/dynamicClientsQuery.graphql) (Authgear Portal), [`pkg/admin/transport/handler_graphql.go`](https://github.com/authgear/authgear-server/blob/main/pkg/admin/transport/handler_graphql.go) (GraphQL transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_enduser["End-user authentication"]
  node_authui["AuthUI flows<br/>[authflowv2.ts]"]
end

subgraph group_server["Authgear server"]
  node_auth_routes["Auth routes<br/>[routes.go]"]
  node_oauth["OAuth authorization<br/>[handler_authz.go]"]
  node_account["Authenticator service"]
  node_protocols["OIDC / SAML SSO<br/>[routes.go]"]
  node_hooks["Hooks and events<br/>[event.go]"]
  node_templates["Localized templates<br/>[engine.go]"]
end

subgraph group_management["Administration"]
  node_admin_user["User administration<br/>[user_mutation.go]"]
  node_admin_access["Roles and access"]
  node_admin_audit["Audit logs<br/>[audit_log.go]"]
  node_admin_transport["GraphQL transport<br/>[handler_graphql.go]"]
end

subgraph group_portal["Management portal"]
  node_portal["Authgear Portal"]
  node_oauth_form["OAuth client form"]
  node_session_storage["Portal session state"]
end

subgraph group_state["Security state"]
  node_redis_lockout[("Lockout state<br/>[storage_redis.go]")]
  node_redis_rate[("Rate-limit state<br/>[storage_redis.go]")]
end

node_user(("End user"))
node_redis[("Redis")]
node_cloud_storage[("Image cloud storage<br/>[cloudstorage.go]")]
node_external_api(("Admin API client"))

node_user -->|"uses flows"| node_authui
node_authui -->|"requests routes"| node_auth_routes
node_auth_routes -->|"dispatches authorization"| node_oauth
node_auth_routes -->|"dispatches SSO"| node_protocols
node_authui -->|"requests settings"| node_account
node_account -.->|"checks lockout"| node_redis_lockout
node_redis_lockout -->|"stores attempts"| node_redis
node_redis_rate -->|"stores rate state"| node_redis
node_admin_transport -->|"dispatches GraphQL"| node_admin_user
node_admin_transport -->|"dispatches GraphQL"| node_admin_access
node_admin_transport -->|"dispatches GraphQL"| node_admin_audit
node_portal -->|"queries clients"| node_external_api
node_portal -->|"edits client config"| node_oauth_form
node_portal -->|"persists UI state"| node_session_storage
node_user -->|"administers project"| node_portal
node_account -.->|"supports account events"| node_hooks
node_auth_routes -.->|"renders localized flows"| node_templates
node_authui -.->|"uploads images"| node_cloud_storage

click node_authui "https://github.com/authgear/authgear-server/blob/main/authui/src/authflowv2.ts"
click node_auth_routes "https://github.com/authgear/authgear-server/blob/main/pkg/auth/routes.go"
click node_oauth "https://github.com/authgear/authgear-server/blob/main/pkg/lib/oauth/handler/handler_authz.go"
click node_account "https://github.com/authgear/authgear-server/blob/main/pkg/lib/accountmanagement/service_authenticator.go"
click node_protocols "https://github.com/authgear/authgear-server/blob/main/pkg/auth/routes.go"
click node_hooks "https://github.com/authgear/authgear-server/blob/main/pkg/api/event/event.go"
click node_templates "https://github.com/authgear/authgear-server/blob/main/pkg/util/template/engine.go"
click node_admin_user "https://github.com/authgear/authgear-server/blob/main/pkg/admin/graphql/user_mutation.go"
click node_admin_access "https://github.com/authgear/authgear-server/blob/main/pkg/admin/graphql/authorization_mutation.go"
click node_admin_audit "https://github.com/authgear/authgear-server/blob/main/pkg/admin/graphql/audit_log.go"
click node_admin_transport "https://github.com/authgear/authgear-server/blob/main/pkg/admin/transport/handler_graphql.go"
click node_portal "https://github.com/authgear/authgear-server/blob/main/portal/src/graphql/adminapi/query/dynamicClientsQuery.graphql"
click node_oauth_form "https://github.com/authgear/authgear-server/blob/main/portal/src/hook/useOAuthClientForm.ts"
click node_session_storage "https://github.com/authgear/authgear-server/blob/main/portal/src/hook/useSessionStorage.ts"
click node_redis_lockout "https://github.com/authgear/authgear-server/blob/main/pkg/lib/lockout/storage_redis.go"
click node_redis_rate "https://github.com/authgear/authgear-server/blob/main/pkg/lib/ratelimit/storage_redis.go"
click node_cloud_storage "https://github.com/authgear/authgear-server/blob/main/pkg/lib/cloudstorage/cloudstorage.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_authui,node_user,node_external_api toneBlue
class node_auth_routes,node_oauth,node_account,node_protocols,node_hooks,node_templates,node_redis,node_cloud_storage toneAmber
class node_admin_user,node_admin_access,node_admin_audit,node_admin_transport toneMint
class node_portal,node_oauth_form,node_session_storage toneRose
class node_redis_lockout,node_redis_rate toneIndigo
```

## Components

### End-user authentication

- [AuthUI flows](https://github.com/authgear/authgear-server/blob/main/authui/src/authflowv2.ts): `authui/src/authflowv2.ts`

### Authgear server

- [Auth routes](https://github.com/authgear/authgear-server/blob/main/pkg/auth/routes.go): `pkg/auth/routes.go`
- [OAuth authorization](https://github.com/authgear/authgear-server/blob/main/pkg/lib/oauth/handler/handler_authz.go): `pkg/lib/oauth/handler/handler_authz.go`
- [Authenticator service](https://github.com/authgear/authgear-server/blob/main/pkg/lib/accountmanagement/service_authenticator.go): `pkg/lib/accountmanagement/service_authenticator.go`
- [OIDC / SAML SSO](https://github.com/authgear/authgear-server/blob/main/pkg/auth/routes.go): `pkg/auth/routes.go`
- [Hooks and events](https://github.com/authgear/authgear-server/blob/main/pkg/api/event/event.go): `pkg/api/event/event.go`
- [Localized templates](https://github.com/authgear/authgear-server/blob/main/pkg/util/template/engine.go): `pkg/util/template/engine.go`

### Administration

- [User administration](https://github.com/authgear/authgear-server/blob/main/pkg/admin/graphql/user_mutation.go): `pkg/admin/graphql/user_mutation.go`
- [Roles and access](https://github.com/authgear/authgear-server/blob/main/pkg/admin/graphql/authorization_mutation.go): `pkg/admin/graphql/authorization_mutation.go`
- [Audit logs](https://github.com/authgear/authgear-server/blob/main/pkg/admin/graphql/audit_log.go): `pkg/admin/graphql/audit_log.go`
- [GraphQL transport](https://github.com/authgear/authgear-server/blob/main/pkg/admin/transport/handler_graphql.go): `pkg/admin/transport/handler_graphql.go`

### Management portal

- [Authgear Portal](https://github.com/authgear/authgear-server/blob/main/portal/src/graphql/adminapi/query/dynamicClientsQuery.graphql): `portal/src/graphql/adminapi/query/dynamicClientsQuery.graphql`
- [OAuth client form](https://github.com/authgear/authgear-server/blob/main/portal/src/hook/useOAuthClientForm.ts): `portal/src/hook/useOAuthClientForm.ts`
- [Portal session state](https://github.com/authgear/authgear-server/blob/main/portal/src/hook/useSessionStorage.ts): `portal/src/hook/useSessionStorage.ts`

### Security state

- [Lockout state](https://github.com/authgear/authgear-server/blob/main/pkg/lib/lockout/storage_redis.go): `pkg/lib/lockout/storage_redis.go`
- [Rate-limit state](https://github.com/authgear/authgear-server/blob/main/pkg/lib/ratelimit/storage_redis.go): `pkg/lib/ratelimit/storage_redis.go`

### Other components

- **End user**
- **Redis**
- [Image cloud storage](https://github.com/authgear/authgear-server/blob/main/pkg/lib/cloudstorage/cloudstorage.go): `pkg/lib/cloudstorage/cloudstorage.go`
- **Admin API client**

## Connections

- End user → AuthUI flows: uses flows
- AuthUI flows → Auth routes: requests routes
- Auth routes → OAuth authorization: dispatches authorization
- Auth routes → OIDC / SAML SSO: dispatches SSO
- AuthUI flows → Authenticator service: requests settings
- Authenticator service → Lockout state: checks lockout
- Lockout state → Redis: stores attempts
- Rate-limit state → Redis: stores rate state
- GraphQL transport → User administration: dispatches GraphQL
- GraphQL transport → Roles and access: dispatches GraphQL
- GraphQL transport → Audit logs: dispatches GraphQL
- Authgear Portal → Admin API client: queries clients
- Authgear Portal → OAuth client form: edits client config
- Authgear Portal → Portal session state: persists UI state
- End user → Authgear Portal: administers project
- Authenticator service → Hooks and events: supports account events
- Auth routes → Localized templates: renders localized flows
- AuthUI flows → Image cloud storage: uploads images