# mibnekhalid/mbkauthe architecture

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

- Interactive diagram: https://gitdiagram.com/mibnekhalid/mbkauthe
- Repository: https://github.com/mibnekhalid/mbkauthe

## Overview

MBKAuthe is a TypeScript authentication and authorization framework mounted in an Express application. A typical user request enters its router, proceeds through an authentication flow (including optional second factor), and establishes a persisted session; protected application routes then validate that session and evaluate roles or permissions. Separate flows support OAuth/OIDC, passkeys, API tokens, and CLI device login. The graph reflects README-documented capabilities and sampled call relationships; some subsystem wiring is inferred only at the documented feature level, so uncertain links are omitted.

Main entry points: [`src/http/routes/auth.routes.ts`](https://github.com/mibnekhalid/mbkauthe/blob/main/src/http/routes/auth.routes.ts) (Auth routes), [`src/oauth/OAuthFlowService.ts`](https://github.com/mibnekhalid/mbkauthe/blob/main/src/oauth/OAuthFlowService.ts) (OAuth flow service), [`src/services/AuthService.ts`](https://github.com/mibnekhalid/mbkauthe/blob/main/src/services/AuthService.ts) (Authentication service), [`src/db/repositories/AuthRepository.ts`](https://github.com/mibnekhalid/mbkauthe/blob/main/src/db/repositories/AuthRepository.ts) (Auth repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["Express entry"]
  node_entry["Auth package entry<br/>[index.ts]"]
  node_authroutes["Auth routes<br/>[auth.routes.ts]"]
  node_oauthrouter["OAuth router<br/>[oauth.router.ts]"]
  node_authflow["Login completion<br/>[authFlow.ts]"]
  node_middleware["Session middleware<br/>[authMiddleware.ts]"]
end

subgraph group_auth["Authentication flows"]
  node_authservice["Authentication service<br/>[AuthService.ts]"]
  node_passkey["Passkey service<br/>[PasskeyService.ts]"]
  node_cliservice["CLI device service<br/>[CliAuthService.ts]"]
  node_apitoken["API token service<br/>[ApiTokenService.ts]"]
  node_oauthflow["OAuth flow service"]
  node_providers["OAuth providers<br/>[loader.ts]"]
end

subgraph group_domain["Core domain"]
  node_tokenengine["Token engine<br/>[TokenEngine.ts]"]
  node_authcontext["Auth context<br/>[AuthContext.ts]"]
  node_authorization["Authorization service"]
  node_permissions["Permission manifest<br/>[manifest.ts]"]
end

subgraph group_persistence["Persistence"]
  node_repository["Auth repository<br/>[AuthRepository.ts]"]
  node_repos["Domain repositories<br/>[index.ts]"]
  node_database[("Postgres / SQLite")]
  node_oauthaccounts["OAuth account repository"]
end

subgraph group_ops["Events and diagnostics"]
  node_events["Auth event emitter<br/>[index.ts]"]
  node_health["Health reporting<br/>[health.ts]"]
end

node_app(("Application user"))
node_provider(("OAuth provider"))
node_databaseengine[("Database engine")]

node_app -->|"mounts router"| node_entry
node_entry -->|"dispatches requests"| node_authroutes
node_entry -->|"mounts routes"| node_oauthrouter
node_authroutes -->|"authenticates"| node_authservice
node_authroutes -->|"handles ceremonies"| node_passkey
node_authroutes -->|"completes login"| node_authflow
node_authflow -->|"persists session"| node_repository
node_authflow -->|"creates context"| node_authcontext
node_authservice -->|"loads auth data"| node_repository
node_authservice -->|"builds context"| node_authcontext
node_middleware -->|"validates session"| node_repository
node_middleware -->|"checks access"| node_authorization
node_authorization -->|"evaluates principal"| node_authcontext
node_authorization -->|"matches permissions"| node_permissions
node_oauthrouter -->|"starts callbacks"| node_oauthflow
node_oauthflow -->|"loads providers"| node_providers
node_oauthflow -.->|"exchanges tokens"| node_provider
node_oauthflow -.->|"links accounts"| node_oauthaccounts
node_authroutes -->|"handles device login"| node_cliservice
node_cliservice -->|"issues tokens"| node_apitoken
node_apitoken -->|"generates tokens"| node_tokenengine
node_cliservice -->|"reads device state"| node_repos
node_passkey -->|"stores credentials"| node_repos
node_repository -->|"delegates queries"| node_repos
node_repos -->|"executes queries"| node_database
node_database -->|"reads and writes"| node_databaseengine
node_authservice -->|"emits auth events"| node_events
node_oauthflow -->|"emits OAuth events"| node_events
node_health -->|"checks database"| node_database

click node_entry "https://github.com/mibnekhalid/mbkauthe/blob/main/src/index.ts"
click node_authroutes "https://github.com/mibnekhalid/mbkauthe/blob/main/src/http/routes/auth.routes.ts"
click node_oauthrouter "https://github.com/mibnekhalid/mbkauthe/blob/main/src/express/oauth.router.ts"
click node_authflow "https://github.com/mibnekhalid/mbkauthe/blob/main/src/http/session/authFlow.ts"
click node_middleware "https://github.com/mibnekhalid/mbkauthe/blob/main/src/http/middleware/authMiddleware.ts"
click node_authservice "https://github.com/mibnekhalid/mbkauthe/blob/main/src/services/AuthService.ts"
click node_passkey "https://github.com/mibnekhalid/mbkauthe/blob/main/src/services/PasskeyService.ts"
click node_cliservice "https://github.com/mibnekhalid/mbkauthe/blob/main/src/services/CliAuthService.ts"
click node_apitoken "https://github.com/mibnekhalid/mbkauthe/blob/main/src/services/ApiTokenService.ts"
click node_oauthflow "https://github.com/mibnekhalid/mbkauthe/blob/main/src/oauth/OAuthFlowService.ts"
click node_providers "https://github.com/mibnekhalid/mbkauthe/blob/main/src/oauth/providers/loader.ts"
click node_tokenengine "https://github.com/mibnekhalid/mbkauthe/blob/main/src/core/tokens/TokenEngine.ts"
click node_authcontext "https://github.com/mibnekhalid/mbkauthe/blob/main/src/core/context/AuthContext.ts"
click node_authorization "https://github.com/mibnekhalid/mbkauthe/blob/main/src/core/permissions/AuthorizationService.ts"
click node_permissions "https://github.com/mibnekhalid/mbkauthe/blob/main/src/core/permissions/manifest.ts"
click node_repository "https://github.com/mibnekhalid/mbkauthe/blob/main/src/db/repositories/AuthRepository.ts"
click node_repos "https://github.com/mibnekhalid/mbkauthe/blob/main/src/db/repositories/index.ts"
click node_database "https://github.com/mibnekhalid/mbkauthe/blob/main/src/db/adapters/IDatabaseAdapter.ts"
click node_oauthaccounts "https://github.com/mibnekhalid/mbkauthe/blob/main/src/db/repositories/OAuthAccountRepository.ts"
click node_events "https://github.com/mibnekhalid/mbkauthe/blob/main/src/core/events/index.ts"
click node_health "https://github.com/mibnekhalid/mbkauthe/blob/main/src/diagnostics/health.ts"

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_entry,node_authroutes,node_oauthrouter,node_authflow,node_middleware,node_app toneBlue
class node_authservice,node_passkey,node_cliservice,node_apitoken,node_oauthflow,node_providers,node_databaseengine toneAmber
class node_tokenengine,node_authcontext,node_authorization,node_permissions toneMint
class node_repository,node_repos,node_database,node_oauthaccounts toneRose
class node_events,node_health,node_provider toneIndigo
```

## Components

### Express entry

- [Auth package entry](https://github.com/mibnekhalid/mbkauthe/blob/main/src/index.ts): `src/index.ts`
- [Auth routes](https://github.com/mibnekhalid/mbkauthe/blob/main/src/http/routes/auth.routes.ts): `src/http/routes/auth.routes.ts`
- [OAuth router](https://github.com/mibnekhalid/mbkauthe/blob/main/src/express/oauth.router.ts): `src/express/oauth.router.ts`
- [Login completion](https://github.com/mibnekhalid/mbkauthe/blob/main/src/http/session/authFlow.ts): `src/http/session/authFlow.ts`
- [Session middleware](https://github.com/mibnekhalid/mbkauthe/blob/main/src/http/middleware/authMiddleware.ts): `src/http/middleware/authMiddleware.ts`

### Authentication flows

- [Authentication service](https://github.com/mibnekhalid/mbkauthe/blob/main/src/services/AuthService.ts): `src/services/AuthService.ts`
- [Passkey service](https://github.com/mibnekhalid/mbkauthe/blob/main/src/services/PasskeyService.ts): `src/services/PasskeyService.ts`
- [CLI device service](https://github.com/mibnekhalid/mbkauthe/blob/main/src/services/CliAuthService.ts): `src/services/CliAuthService.ts`
- [API token service](https://github.com/mibnekhalid/mbkauthe/blob/main/src/services/ApiTokenService.ts): `src/services/ApiTokenService.ts`
- [OAuth flow service](https://github.com/mibnekhalid/mbkauthe/blob/main/src/oauth/OAuthFlowService.ts): `src/oauth/OAuthFlowService.ts`
- [OAuth providers](https://github.com/mibnekhalid/mbkauthe/blob/main/src/oauth/providers/loader.ts): `src/oauth/providers/loader.ts`

### Core domain

- [Token engine](https://github.com/mibnekhalid/mbkauthe/blob/main/src/core/tokens/TokenEngine.ts): `src/core/tokens/TokenEngine.ts`
- [Auth context](https://github.com/mibnekhalid/mbkauthe/blob/main/src/core/context/AuthContext.ts): `src/core/context/AuthContext.ts`
- [Authorization service](https://github.com/mibnekhalid/mbkauthe/blob/main/src/core/permissions/AuthorizationService.ts): `src/core/permissions/AuthorizationService.ts`
- [Permission manifest](https://github.com/mibnekhalid/mbkauthe/blob/main/src/core/permissions/manifest.ts): `src/core/permissions/manifest.ts`

### Persistence

- [Auth repository](https://github.com/mibnekhalid/mbkauthe/blob/main/src/db/repositories/AuthRepository.ts): `src/db/repositories/AuthRepository.ts`
- [Domain repositories](https://github.com/mibnekhalid/mbkauthe/blob/main/src/db/repositories/index.ts): `src/db/repositories/index.ts`
- [Postgres / SQLite](https://github.com/mibnekhalid/mbkauthe/blob/main/src/db/adapters/IDatabaseAdapter.ts): `src/db/adapters/IDatabaseAdapter.ts`
- [OAuth account repository](https://github.com/mibnekhalid/mbkauthe/blob/main/src/db/repositories/OAuthAccountRepository.ts): `src/db/repositories/OAuthAccountRepository.ts`

### Events and diagnostics

- [Auth event emitter](https://github.com/mibnekhalid/mbkauthe/blob/main/src/core/events/index.ts): `src/core/events/index.ts`
- [Health reporting](https://github.com/mibnekhalid/mbkauthe/blob/main/src/diagnostics/health.ts): `src/diagnostics/health.ts`

### Other components

- **Application user**
- **OAuth provider**
- **Database engine**

## Connections

- Application user → Auth package entry: mounts router
- Auth package entry → Auth routes: dispatches requests
- Auth package entry → OAuth router: mounts routes
- Auth routes → Authentication service: authenticates
- Auth routes → Passkey service: handles ceremonies
- Auth routes → Login completion: completes login
- Login completion → Auth repository: persists session
- Login completion → Auth context: creates context
- Authentication service → Auth repository: loads auth data
- Authentication service → Auth context: builds context
- Session middleware → Auth repository: validates session
- Session middleware → Authorization service: checks access
- Authorization service → Auth context: evaluates principal
- Authorization service → Permission manifest: matches permissions
- OAuth router → OAuth flow service: starts callbacks
- OAuth flow service → OAuth providers: loads providers
- OAuth flow service → OAuth provider: exchanges tokens
- OAuth flow service → OAuth account repository: links accounts
- Auth routes → CLI device service: handles device login
- CLI device service → API token service: issues tokens
- API token service → Token engine: generates tokens
- CLI device service → Domain repositories: reads device state
- Passkey service → Domain repositories: stores credentials
- Auth repository → Domain repositories: delegates queries
- Domain repositories → Postgres / SQLite: executes queries
- Postgres / SQLite → Database engine: reads and writes
- Authentication service → Auth event emitter: emits auth events
- OAuth flow service → Auth event emitter: emits OAuth events
- Health reporting → Postgres / SQLite: checks database