# occupysaas/zeroauthy architecture

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

- Interactive diagram: https://gitdiagram.com/occupysaas/zeroauthy
- Repository: https://github.com/occupysaas/zeroauthy

## Overview

zeroauthy is a self-hostable Auth0-compatible identity server, with a Vue admin console and pluggable storage. The main user flow starts at an SDK or browser, enters the HTTP server, resolves authorization and login, authenticates a database or federated identity, and returns OAuth/OIDC tokens; hosted login, MFA, consent and organization context support that flow. The console separately manages tenant resources through the Management API. The README documents broad capabilities, but several implementations were not sampled, so their internal wiring is not inferred here.

Main entry points: [`internal/storage/open.go`](https://github.com/occupysaas/zeroauthy/blob/main/internal/storage/open.go) (Storage backend), [`internal/server/server.go`](https://github.com/occupysaas/zeroauthy/blob/main/internal/server/server.go) (HTTP server), [`internal/authz/handlers.go`](https://github.com/occupysaas/zeroauthy/blob/main/internal/authz/handlers.go) (Authorization flow), [`console/src/api/client.ts`](https://github.com/occupysaas/zeroauthy/blob/main/console/src/api/client.ts) (Console API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_http["HTTP server<br/>[server.go]"]
  node_app["App wiring<br/>[app.go]"]
  node_storage[("Storage backend<br/>[open.go]")]
  node_keys["Signing keys<br/>[manager.go]"]
end

subgraph group_identity["Identity flows"]
  node_authz["Authorization flow<br/>[handlers.go]"]
  node_hosted["Hosted login<br/>[service.go]"]
  node_database_identity["Database identity<br/>[database.go]"]
  node_federation["Federated login<br/>[service_flow.go]"]
  node_mfa["MFA service<br/>[service.go]"]
  node_oauth["OAuth handlers<br/>[handlers.go]"]
  node_oidc["OIDC endpoints<br/>[handlers.go]"]
end

subgraph group_management["Management"]
  node_mgmt["Management API<br/>[clients.go]"]
end

subgraph group_operations["Tenant operations"]
  node_actions["Actions engine<br/>[engine.go]"]
  node_email["Email service<br/>[service.go]"]
  node_domains["Custom domains<br/>[service.go]"]
  node_eventstreams["Event delivery<br/>[worker.go]"]
  node_logstreams["Log delivery<br/>[worker.go]"]
end

subgraph group_console["Admin console"]
  node_console_app["Console app<br/>[main.ts]"]
  node_console_api["Console API client<br/>[client.ts]"]
  node_console_auth["Console authentication<br/>[auth.ts]"]
  node_console_actions["Actions screens<br/>[Editor.vue]"]
  node_console_logs["Logs screens<br/>[LogsList.vue]"]
  node_console_streams["Stream screens<br/>[StreamEdit.vue]"]
end

node_sdk(("Auth SDK"))
node_browser(("User browser"))

node_sdk -->|"requests auth"| node_http
node_browser -->|"uses login"| node_http
node_http -->|"routes authorization"| node_authz
node_http -->|"routes API"| node_oauth
node_http -->|"routes OIDC"| node_oidc
node_http -.->|"serves login"| node_hosted
node_authz -->|"starts login"| node_hosted
node_authz -.->|"authenticates users"| node_database_identity
node_authz -.->|"dispatches federation"| node_federation
node_authz -.->|"uses MFA"| node_mfa
node_oauth -->|"mints tokens"| node_keys
node_oidc -->|"uses signing keys"| node_keys
node_app -->|"opens store"| node_storage
node_app -.->|"assembles server"| node_http
node_authz -.->|"reads state"| node_storage
node_mgmt -->|"manages resources"| node_storage
node_console_app -->|"creates client"| node_console_api
node_console_app -->|"creates auth"| node_console_auth
node_console_auth -->|"supplies token"| node_console_api
node_console_api -.->|"calls API"| node_mgmt
node_console_actions -.->|"manages actions"| node_console_api
node_console_logs -.->|"queries logs"| node_console_api
node_console_streams -.->|"manages streams"| node_console_api
node_actions -->|"persists executions"| node_storage
node_eventstreams -->|"loads streams"| node_storage
node_logstreams -->|"loads configuration"| node_storage
node_email -->|"reads tenant config"| node_storage
node_domains -->|"loads domain state"| node_storage

click node_http "https://github.com/occupysaas/zeroauthy/blob/main/internal/server/server.go"
click node_app "https://github.com/occupysaas/zeroauthy/blob/main/internal/app/app.go"
click node_storage "https://github.com/occupysaas/zeroauthy/blob/main/internal/storage/open.go"
click node_authz "https://github.com/occupysaas/zeroauthy/blob/main/internal/authz/handlers.go"
click node_hosted "https://github.com/occupysaas/zeroauthy/blob/main/internal/hostedlogin/service.go"
click node_database_identity "https://github.com/occupysaas/zeroauthy/blob/main/internal/identity/database.go"
click node_federation "https://github.com/occupysaas/zeroauthy/blob/main/internal/federation/service_flow.go"
click node_mfa "https://github.com/occupysaas/zeroauthy/blob/main/internal/mfa/service.go"
click node_oauth "https://github.com/occupysaas/zeroauthy/blob/main/internal/oauth/handlers.go"
click node_oidc "https://github.com/occupysaas/zeroauthy/blob/main/internal/oidc/handlers.go"
click node_keys "https://github.com/occupysaas/zeroauthy/blob/main/internal/keys/manager.go"
click node_actions "https://github.com/occupysaas/zeroauthy/blob/main/internal/actions/engine.go"
click node_email "https://github.com/occupysaas/zeroauthy/blob/main/internal/email/service.go"
click node_domains "https://github.com/occupysaas/zeroauthy/blob/main/internal/customdomain/service.go"
click node_eventstreams "https://github.com/occupysaas/zeroauthy/blob/main/internal/eventstream/worker.go"
click node_logstreams "https://github.com/occupysaas/zeroauthy/blob/main/internal/logstream/worker.go"
click node_mgmt "https://github.com/occupysaas/zeroauthy/blob/main/internal/mgmt/clients.go"
click node_console_app "https://github.com/occupysaas/zeroauthy/blob/main/console/src/main.ts"
click node_console_api "https://github.com/occupysaas/zeroauthy/blob/main/console/src/api/client.ts"
click node_console_auth "https://github.com/occupysaas/zeroauthy/blob/main/console/src/auth/auth.ts"
click node_console_actions "https://github.com/occupysaas/zeroauthy/blob/main/console/src/pages/actions/Editor.vue"
click node_console_logs "https://github.com/occupysaas/zeroauthy/blob/main/console/src/pages/logs/LogsList.vue"
click node_console_streams "https://github.com/occupysaas/zeroauthy/blob/main/console/src/pages/event-streams/StreamEdit.vue"

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_http,node_app,node_storage,node_keys,node_browser toneBlue
class node_authz,node_hosted,node_database_identity,node_federation,node_mfa,node_oauth,node_oidc toneAmber
class node_mgmt toneMint
class node_actions,node_email,node_domains,node_eventstreams,node_logstreams toneRose
class node_console_app,node_console_api,node_console_auth,node_console_actions,node_console_logs,node_console_streams,node_sdk toneIndigo
```

## Components

### Server runtime

- [HTTP server](https://github.com/occupysaas/zeroauthy/blob/main/internal/server/server.go): `internal/server/server.go`
- [App wiring](https://github.com/occupysaas/zeroauthy/blob/main/internal/app/app.go): `internal/app/app.go`
- [Storage backend](https://github.com/occupysaas/zeroauthy/blob/main/internal/storage/open.go): `internal/storage/open.go`
- [Signing keys](https://github.com/occupysaas/zeroauthy/blob/main/internal/keys/manager.go): `internal/keys/manager.go`

### Identity flows

- [Authorization flow](https://github.com/occupysaas/zeroauthy/blob/main/internal/authz/handlers.go): `internal/authz/handlers.go`
- [Hosted login](https://github.com/occupysaas/zeroauthy/blob/main/internal/hostedlogin/service.go): `internal/hostedlogin/service.go`
- [Database identity](https://github.com/occupysaas/zeroauthy/blob/main/internal/identity/database.go): `internal/identity/database.go`
- [Federated login](https://github.com/occupysaas/zeroauthy/blob/main/internal/federation/service_flow.go): `internal/federation/service_flow.go`
- [MFA service](https://github.com/occupysaas/zeroauthy/blob/main/internal/mfa/service.go): `internal/mfa/service.go`
- [OAuth handlers](https://github.com/occupysaas/zeroauthy/blob/main/internal/oauth/handlers.go): `internal/oauth/handlers.go`
- [OIDC endpoints](https://github.com/occupysaas/zeroauthy/blob/main/internal/oidc/handlers.go): `internal/oidc/handlers.go`

### Management

- [Management API](https://github.com/occupysaas/zeroauthy/blob/main/internal/mgmt/clients.go): `internal/mgmt/clients.go`

### Tenant operations

- [Actions engine](https://github.com/occupysaas/zeroauthy/blob/main/internal/actions/engine.go): `internal/actions/engine.go`
- [Email service](https://github.com/occupysaas/zeroauthy/blob/main/internal/email/service.go): `internal/email/service.go`
- [Custom domains](https://github.com/occupysaas/zeroauthy/blob/main/internal/customdomain/service.go): `internal/customdomain/service.go`
- [Event delivery](https://github.com/occupysaas/zeroauthy/blob/main/internal/eventstream/worker.go): `internal/eventstream/worker.go`
- [Log delivery](https://github.com/occupysaas/zeroauthy/blob/main/internal/logstream/worker.go): `internal/logstream/worker.go`

### Admin console

- [Console app](https://github.com/occupysaas/zeroauthy/blob/main/console/src/main.ts): `console/src/main.ts`
- [Console API client](https://github.com/occupysaas/zeroauthy/blob/main/console/src/api/client.ts): `console/src/api/client.ts`
- [Console authentication](https://github.com/occupysaas/zeroauthy/blob/main/console/src/auth/auth.ts): `console/src/auth/auth.ts`
- [Actions screens](https://github.com/occupysaas/zeroauthy/blob/main/console/src/pages/actions/Editor.vue): `console/src/pages/actions/Editor.vue`
- [Logs screens](https://github.com/occupysaas/zeroauthy/blob/main/console/src/pages/logs/LogsList.vue): `console/src/pages/logs/LogsList.vue`
- [Stream screens](https://github.com/occupysaas/zeroauthy/blob/main/console/src/pages/event-streams/StreamEdit.vue): `console/src/pages/event-streams/StreamEdit.vue`

### Other components

- **Auth SDK**
- **User browser**

## Connections

- Auth SDK → HTTP server: requests auth (evidence: `README.md`)
- User browser → HTTP server: uses login (evidence: `README.md`)
- HTTP server → Authorization flow: routes authorization (evidence: `internal/server/server.go`)
- HTTP server → OAuth handlers: routes API (evidence: `internal/server/server.go`)
- HTTP server → OIDC endpoints: routes OIDC (evidence: `internal/server/server.go`)
- HTTP server → Hosted login: serves login
- Authorization flow → Hosted login: starts login (evidence: `internal/authz/handlers.go`)
- Authorization flow → Database identity: authenticates users
- Authorization flow → Federated login: dispatches federation
- Authorization flow → MFA service: uses MFA
- OAuth handlers → Signing keys: mints tokens
- OIDC endpoints → Signing keys: uses signing keys (evidence: `internal/oidc/handlers.go`)
- App wiring → Storage backend: opens store (evidence: `internal/app/app.go`)
- App wiring → HTTP server: assembles server
- Authorization flow → Storage backend: reads state
- Management API → Storage backend: manages resources (evidence: `internal/mgmt/clients.go`)
- Console app → Console API client: creates client (evidence: `console/src/main.ts`)
- Console app → Console authentication: creates auth (evidence: `console/src/main.ts`)
- Console authentication → Console API client: supplies token (evidence: `console/src/main.ts`)
- Console API client → Management API: calls API
- Actions screens → Console API client: manages actions
- Logs screens → Console API client: queries logs
- Stream screens → Console API client: manages streams
- Actions engine → Storage backend: persists executions (evidence: `internal/actions/engine.go`)
- Event delivery → Storage backend: loads streams (evidence: `internal/eventstream/worker.go`)
- Log delivery → Storage backend: loads configuration (evidence: `internal/logstream/worker.go`)
- Email service → Storage backend: reads tenant config (evidence: `internal/email/service.go`)
- Custom domains → Storage backend: loads domain state (evidence: `internal/customdomain/service.go`)