# biszdevelopers/basis-auth architecture

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

- Interactive diagram: https://gitdiagram.com/biszdevelopers/basis-auth
- Repository: https://github.com/biszdevelopers/basis-auth

## Overview

basis-auth is a Hono-based identity boundary: applications initiate OIDC authorization, users authenticate through Microsoft and may grant consent, and the service issues tokens for registered resource APIs. The React interface handles login and consent; PostgreSQL stores identity and protocol state. The graph includes the separate internal user API and key/session services. The README documents protocol capabilities not visible in the partial route excerpts; those are represented at the app-to-OAuth boundary rather than as unsupported individual calls.

Main entry points: [`src/app.ts`](https://github.com/biszdevelopers/basis-auth/blob/main/src/app.ts) (HTTP application), [`src/oauth/service.ts`](https://github.com/biszdevelopers/basis-auth/blob/main/src/oauth/service.ts) (OAuth service), [`src/identity.ts`](https://github.com/biszdevelopers/basis-auth/blob/main/src/identity.ts) (Identity service), [`src/index.ts`](https://github.com/biszdevelopers/basis-auth/blob/main/src/index.ts) (Service assembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Service runtime"]
  node_bootstrap["Service assembly<br/>[index.ts]"]
  node_http_app["HTTP application<br/>[app.ts]"]
  node_config["Configuration<br/>[config.ts]"]
  node_internal_app["Internal user API<br/>[app.ts]"]
  node_internal_users["Internal user service<br/>[users.ts]"]
end

subgraph group_oidc["OAuth and OIDC"]
  node_oauth_service["OAuth service<br/>[service.ts]"]
  node_client_cache["Client cache<br/>[clientCache.ts]"]
  node_signing_keys["Signing keys<br/>[keys.ts]"]
  node_oauth_crypto["OAuth crypto<br/>[crypto.ts]"]
end

subgraph group_identity["Identity and sessions"]
  node_identity_service["Identity service<br/>[identity.ts]"]
  node_microsoft_service["Microsoft login<br/>[microsoft.ts]"]
  node_sessions["Session service<br/>[sessions.ts]"]
  node_database_schema["Database schema<br/>[schema.ts]"]
end

subgraph group_interaction["Login interface"]
  node_web_app["Login and consent UI<br/>[App.tsx]"]
  node_login_card["Login card<br/>[LoginCard.tsx]"]
end

node_application(("Client application"))
node_browser(("User browser"))
node_microsoft{{"Microsoft Entra"}}
node_resource_api{{"Resource API"}}
node_postgres[("PostgreSQL")]

node_application -->|"OIDC requests"| node_http_app
node_browser -->|"login and consent"| node_http_app
node_http_app -->|"serves UI"| node_web_app
node_web_app -->|"interaction requests"| node_http_app
node_web_app -->|"renders"| node_login_card
node_login_card -->|"login actions"| node_http_app
node_http_app -->|"protocol operations"| node_oauth_service
node_http_app -->|"login and callback"| node_microsoft_service
node_http_app -->|"session lookups"| node_sessions
node_http_app -->|"identity lookups"| node_identity_service
node_http_app -->|"metadata and keys"| node_signing_keys
node_microsoft_service -->|"authenticates user"| node_microsoft
node_microsoft_service -->|"updates identity"| node_identity_service
node_oauth_service -->|"loads clients"| node_client_cache
node_oauth_service -->|"identity and permissions"| node_identity_service
node_oauth_service -->|"issues tokens"| node_signing_keys
node_oauth_service -->|"hashes and validates"| node_oauth_crypto
node_signing_keys -->|"publishes JWKS for validation"| node_resource_api
node_sessions -->|"hashes session tokens"| node_oauth_crypto
node_bootstrap -->|"loads settings"| node_config
node_bootstrap -->|"assembles and serves"| node_http_app
node_bootstrap -->|"serves separately"| node_internal_app
node_bootstrap -->|"migrates and seeds"| node_postgres
node_internal_app -->|"user operations"| node_internal_users
node_internal_users -->|"reads and patches users"| node_identity_service
node_oauth_service -->|"reads and writes protocol state"| node_postgres
node_client_cache -->|"loads client records"| node_postgres
node_identity_service -->|"reads and writes identities"| node_postgres
node_microsoft_service -->|"stores identity data"| node_postgres
node_sessions -->|"stores sessions"| node_postgres

click node_bootstrap "https://github.com/biszdevelopers/basis-auth/blob/main/src/index.ts"
click node_http_app "https://github.com/biszdevelopers/basis-auth/blob/main/src/app.ts"
click node_config "https://github.com/biszdevelopers/basis-auth/blob/main/src/config.ts"
click node_internal_app "https://github.com/biszdevelopers/basis-auth/blob/main/src/internal/app.ts"
click node_internal_users "https://github.com/biszdevelopers/basis-auth/blob/main/src/internal/users.ts"
click node_oauth_service "https://github.com/biszdevelopers/basis-auth/blob/main/src/oauth/service.ts"
click node_client_cache "https://github.com/biszdevelopers/basis-auth/blob/main/src/oauth/clientCache.ts"
click node_signing_keys "https://github.com/biszdevelopers/basis-auth/blob/main/src/oauth/keys.ts"
click node_oauth_crypto "https://github.com/biszdevelopers/basis-auth/blob/main/src/oauth/crypto.ts"
click node_identity_service "https://github.com/biszdevelopers/basis-auth/blob/main/src/identity.ts"
click node_microsoft_service "https://github.com/biszdevelopers/basis-auth/blob/main/src/microsoft.ts"
click node_sessions "https://github.com/biszdevelopers/basis-auth/blob/main/src/oauth/sessions.ts"
click node_database_schema "https://github.com/biszdevelopers/basis-auth/blob/main/src/database/schema.ts"
click node_web_app "https://github.com/biszdevelopers/basis-auth/blob/main/web/src/App.tsx"
click node_login_card "https://github.com/biszdevelopers/basis-auth/blob/main/web/src/components/LoginCard.tsx"

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_bootstrap,node_http_app,node_config,node_internal_app,node_internal_users,node_application,node_browser toneBlue
class node_oauth_service,node_client_cache,node_signing_keys,node_oauth_crypto,node_postgres toneAmber
class node_identity_service,node_microsoft_service,node_sessions,node_database_schema,node_resource_api toneMint
class node_web_app,node_login_card toneRose
class node_microsoft toneIndigo
```

## Components

### Service runtime

- [Service assembly](https://github.com/biszdevelopers/basis-auth/blob/main/src/index.ts): `src/index.ts`
- [HTTP application](https://github.com/biszdevelopers/basis-auth/blob/main/src/app.ts): `src/app.ts`
- [Configuration](https://github.com/biszdevelopers/basis-auth/blob/main/src/config.ts): `src/config.ts`
- [Internal user API](https://github.com/biszdevelopers/basis-auth/blob/main/src/internal/app.ts): `src/internal/app.ts`
- [Internal user service](https://github.com/biszdevelopers/basis-auth/blob/main/src/internal/users.ts): `src/internal/users.ts`

### OAuth and OIDC

- [OAuth service](https://github.com/biszdevelopers/basis-auth/blob/main/src/oauth/service.ts): `src/oauth/service.ts`
- [Client cache](https://github.com/biszdevelopers/basis-auth/blob/main/src/oauth/clientCache.ts): `src/oauth/clientCache.ts`
- [Signing keys](https://github.com/biszdevelopers/basis-auth/blob/main/src/oauth/keys.ts): `src/oauth/keys.ts`
- [OAuth crypto](https://github.com/biszdevelopers/basis-auth/blob/main/src/oauth/crypto.ts): `src/oauth/crypto.ts`

### Identity and sessions

- [Identity service](https://github.com/biszdevelopers/basis-auth/blob/main/src/identity.ts): `src/identity.ts`
- [Microsoft login](https://github.com/biszdevelopers/basis-auth/blob/main/src/microsoft.ts): `src/microsoft.ts`
- [Session service](https://github.com/biszdevelopers/basis-auth/blob/main/src/oauth/sessions.ts): `src/oauth/sessions.ts`
- [Database schema](https://github.com/biszdevelopers/basis-auth/blob/main/src/database/schema.ts): `src/database/schema.ts`

### Login interface

- [Login and consent UI](https://github.com/biszdevelopers/basis-auth/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Login card](https://github.com/biszdevelopers/basis-auth/blob/main/web/src/components/LoginCard.tsx): `web/src/components/LoginCard.tsx`

### Other components

- **Client application**
- **User browser**
- **Microsoft Entra**
- **Resource API**
- **PostgreSQL**

## Connections

- Client application → HTTP application: OIDC requests
- User browser → HTTP application: login and consent
- HTTP application → Login and consent UI: serves UI
- Login and consent UI → HTTP application: interaction requests
- Login and consent UI → Login card: renders
- Login card → HTTP application: login actions
- HTTP application → OAuth service: protocol operations
- HTTP application → Microsoft login: login and callback
- HTTP application → Session service: session lookups
- HTTP application → Identity service: identity lookups
- HTTP application → Signing keys: metadata and keys
- Microsoft login → Microsoft Entra: authenticates user
- Microsoft login → Identity service: updates identity
- OAuth service → Client cache: loads clients
- OAuth service → Identity service: identity and permissions
- OAuth service → Signing keys: issues tokens
- OAuth service → OAuth crypto: hashes and validates
- Signing keys → Resource API: publishes JWKS for validation
- Session service → OAuth crypto: hashes session tokens
- Service assembly → Configuration: loads settings
- Service assembly → HTTP application: assembles and serves
- Service assembly → Internal user API: serves separately
- Service assembly → PostgreSQL: migrates and seeds
- Internal user API → Internal user service: user operations
- Internal user service → Identity service: reads and patches users
- OAuth service → PostgreSQL: reads and writes protocol state
- Client cache → PostgreSQL: loads client records
- Identity service → PostgreSQL: reads and writes identities
- Microsoft login → PostgreSQL: stores identity data
- Session service → PostgreSQL: stores sessions