# stonith404/pocket-id architecture

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

- Interactive diagram: https://gitdiagram.com/stonith404/pocket-id
- Repository: https://github.com/stonith404/pocket-id

## Overview

Pocket ID is a self-hosted OpenID Connect and OAuth 2.0 provider whose user sign-in is passkey-only. Users authenticate and manage their accounts in the web app; relying applications use the OIDC endpoints to request authorization and receive tokens and user claims. Administrators configure clients, users, groups, and application settings. The tree also shows user provisioning integrations and file storage. The sampled code supports the client-management and authorization links; broader subsystem links reflect documented product purpose and module boundaries, not inspected internal call paths.

Main entry points: [`backend/internal/storage/database.go`](https://github.com/stonith404/pocket-id/blob/main/backend/internal/storage/database.go) (Application database), [`backend/internal/oidc/provider.go`](https://github.com/stonith404/pocket-id/blob/main/backend/internal/oidc/provider.go) (OIDC provider), [`backend/internal/controller/user_controller.go`](https://github.com/stonith404/pocket-id/blob/main/backend/internal/controller/user_controller.go) (User API), [`backend/internal/service/user_service.go`](https://github.com/stonith404/pocket-id/blob/main/backend/internal/service/user_service.go) (User management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_frontend["Pocket ID web app"]
  node_client_card["Authorized app card"]
  node_client_preview["Client preview"]
end

subgraph group_identity["Identity and OIDC"]
  node_oidc_provider["OIDC provider<br/>[provider.go]"]
  node_authorization["Authorization flow"]
  node_webauthn["Passkey authentication<br/>[service.go]"]
  node_email_verification["Email verification<br/>[service.go]"]
end

subgraph group_admin["Administration"]
  node_oidc_controller["OIDC API<br/>[oidc_controller.go]"]
  node_user_controller["User API<br/>[user_controller.go]"]
  node_oidc_service["OIDC management<br/>[oidc_service.go]"]
  node_user_service["User management<br/>[user_service.go]"]
  node_scim["SCIM provisioning<br/>[service.go]"]
  node_ldap["LDAP synchronization<br/>[service.go]"]
end

subgraph group_platform["Platform services"]
  node_http["HTTP API<br/>[handler.go]"]
  node_router["Route setup"]
  node_database[("Application database<br/>[database.go]")]
  node_file_storage["File storage<br/>[storage.go]"]
end

node_user(("User"))
node_relying_app(("Relying application"))
node_external_jwks["Client JWKS"]

node_user -->|"uses"| node_frontend
node_frontend -->|"sends API requests"| node_http
node_http -->|"dispatches routes"| node_router
node_router -->|"routes OIDC API"| node_oidc_controller
node_router -->|"routes user API"| node_user_controller
node_oidc_controller -->|"calls"| node_oidc_service
node_user_controller -->|"calls"| node_user_service
node_oidc_service -->|"reads and writes"| node_database
node_user_service -->|"reads and writes"| node_database
node_user_controller -->|"manages credentials"| node_webauthn
node_oidc_provider -->|"authorizes requests"| node_authorization
node_relying_app -->|"requests authorization"| node_oidc_provider
node_oidc_provider -->|"issues tokens"| node_relying_app
node_authorization -->|"persists authorization"| node_database
node_client_preview -->|"requests preview"| node_oidc_controller
node_client_preview -->|"loads users"| node_user_controller
node_user -->|"views authorized apps"| node_client_card
node_scim -.->|"synchronizes identities"| node_database
node_ldap -.->|"synchronizes identities"| node_database
node_email_verification -.->|"stores verification state"| node_database
node_oidc_provider -.->|"fetches signing keys"| node_external_jwks
node_user_service -.->|"stores profile images"| node_file_storage

click node_frontend "https://github.com/stonith404/pocket-id/tree/main/frontend/src"
click node_client_card "https://github.com/stonith404/pocket-id/blob/main/frontend/src/routes/settings/apps/authorized-oidc-client-card.svelte"
click node_client_preview "https://github.com/stonith404/pocket-id/blob/main/frontend/src/routes/settings/admin/oidc-clients/oidc-client-preview-modal.svelte"
click node_http "https://github.com/stonith404/pocket-id/blob/main/backend/internal/httpserver/handler.go"
click node_router "https://github.com/stonith404/pocket-id/blob/main/backend/internal/bootstrap/router_bootstrap.go"
click node_oidc_controller "https://github.com/stonith404/pocket-id/blob/main/backend/internal/controller/oidc_controller.go"
click node_user_controller "https://github.com/stonith404/pocket-id/blob/main/backend/internal/controller/user_controller.go"
click node_oidc_service "https://github.com/stonith404/pocket-id/blob/main/backend/internal/service/oidc_service.go"
click node_user_service "https://github.com/stonith404/pocket-id/blob/main/backend/internal/service/user_service.go"
click node_oidc_provider "https://github.com/stonith404/pocket-id/blob/main/backend/internal/oidc/provider.go"
click node_authorization "https://github.com/stonith404/pocket-id/blob/main/backend/internal/oidc/authorization_service.go"
click node_webauthn "https://github.com/stonith404/pocket-id/blob/main/backend/internal/webauthn/service.go"
click node_email_verification "https://github.com/stonith404/pocket-id/blob/main/backend/internal/emailverification/service.go"
click node_scim "https://github.com/stonith404/pocket-id/blob/main/backend/internal/scimsync/service.go"
click node_ldap "https://github.com/stonith404/pocket-id/blob/main/backend/internal/ldapsync/service.go"
click node_database "https://github.com/stonith404/pocket-id/blob/main/backend/internal/storage/database.go"
click node_file_storage "https://github.com/stonith404/pocket-id/blob/main/backend/internal/storage/storage.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_frontend,node_client_card,node_client_preview,node_user,node_external_jwks toneBlue
class node_oidc_provider,node_authorization,node_webauthn,node_email_verification toneAmber
class node_oidc_controller,node_user_controller,node_oidc_service,node_user_service,node_scim,node_ldap toneMint
class node_http,node_router,node_database,node_file_storage toneRose
class node_relying_app toneIndigo
```

## Components

### Web experience

- [Pocket ID web app](https://github.com/stonith404/pocket-id/tree/main/frontend/src): `frontend/src`
- [Authorized app card](https://github.com/stonith404/pocket-id/blob/main/frontend/src/routes/settings/apps/authorized-oidc-client-card.svelte): `frontend/src/routes/settings/apps/authorized-oidc-client-card.svelte`
- [Client preview](https://github.com/stonith404/pocket-id/blob/main/frontend/src/routes/settings/admin/oidc-clients/oidc-client-preview-modal.svelte): `frontend/src/routes/settings/admin/oidc-clients/oidc-client-preview-modal.svelte`

### Identity and OIDC

- [OIDC provider](https://github.com/stonith404/pocket-id/blob/main/backend/internal/oidc/provider.go): `backend/internal/oidc/provider.go`
- [Authorization flow](https://github.com/stonith404/pocket-id/blob/main/backend/internal/oidc/authorization_service.go): `backend/internal/oidc/authorization_service.go`
- [Passkey authentication](https://github.com/stonith404/pocket-id/blob/main/backend/internal/webauthn/service.go): `backend/internal/webauthn/service.go`
- [Email verification](https://github.com/stonith404/pocket-id/blob/main/backend/internal/emailverification/service.go): `backend/internal/emailverification/service.go`

### Administration

- [OIDC API](https://github.com/stonith404/pocket-id/blob/main/backend/internal/controller/oidc_controller.go): `backend/internal/controller/oidc_controller.go`
- [User API](https://github.com/stonith404/pocket-id/blob/main/backend/internal/controller/user_controller.go): `backend/internal/controller/user_controller.go`
- [OIDC management](https://github.com/stonith404/pocket-id/blob/main/backend/internal/service/oidc_service.go): `backend/internal/service/oidc_service.go`
- [User management](https://github.com/stonith404/pocket-id/blob/main/backend/internal/service/user_service.go): `backend/internal/service/user_service.go`
- [SCIM provisioning](https://github.com/stonith404/pocket-id/blob/main/backend/internal/scimsync/service.go): `backend/internal/scimsync/service.go`
- [LDAP synchronization](https://github.com/stonith404/pocket-id/blob/main/backend/internal/ldapsync/service.go): `backend/internal/ldapsync/service.go`

### Platform services

- [HTTP API](https://github.com/stonith404/pocket-id/blob/main/backend/internal/httpserver/handler.go): `backend/internal/httpserver/handler.go`
- [Route setup](https://github.com/stonith404/pocket-id/blob/main/backend/internal/bootstrap/router_bootstrap.go): `backend/internal/bootstrap/router_bootstrap.go`
- [Application database](https://github.com/stonith404/pocket-id/blob/main/backend/internal/storage/database.go): `backend/internal/storage/database.go`
- [File storage](https://github.com/stonith404/pocket-id/blob/main/backend/internal/storage/storage.go): `backend/internal/storage/storage.go`

### Other components

- **User**
- **Relying application**
- **Client JWKS**

## Connections

- User → Pocket ID web app: uses
- Pocket ID web app → HTTP API: sends API requests
- HTTP API → Route setup: dispatches routes
- Route setup → OIDC API: routes OIDC API
- Route setup → User API: routes user API
- OIDC API → OIDC management: calls
- User API → User management: calls
- OIDC management → Application database: reads and writes
- User management → Application database: reads and writes
- User API → Passkey authentication: manages credentials
- OIDC provider → Authorization flow: authorizes requests
- Relying application → OIDC provider: requests authorization
- OIDC provider → Relying application: issues tokens
- Authorization flow → Application database: persists authorization
- Client preview → OIDC API: requests preview
- Client preview → User API: loads users
- User → Authorized app card: views authorized apps
- SCIM provisioning → Application database: synchronizes identities
- LDAP synchronization → Application database: synchronizes identities
- Email verification → Application database: stores verification state
- OIDC provider → Client JWKS: fetches signing keys
- User management → File storage: stores profile images