# astaxie/tokenhub architecture

> Architecture diagram of the GitHub repository astaxie/tokenhub, 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/astaxie/tokenhub
- Repository: https://github.com/astaxie/tokenhub

## Overview

TokenHub is enterprise AI token-governance infrastructure. A caller uses a project-scoped key to submit a model request; the gateway applies access and routing controls, calls a configured provider, and records attributable usage for budgets, analytics, and reconciliation. Administrators configure these controls through the console. The graph also includes documented retrieval, image, and plugin capabilities. README documents those product branches, but their complete implementation wiring was not sampled; links are included only where the tree and excerpts support them.

Main entry points: [`backend/internal/server/gateway_http.go`](https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/gateway_http.go) (Model API), [`backend/internal/server/routes.go`](https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/routes.go) (Admin API), [`backend/internal/server/store.go`](https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/store.go) (Operational store), [`frontend/app/(console)/layout.tsx`](https://github.com/astaxie/tokenhub/blob/main/frontend/app/(console)/layout.tsx) (Admin console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and Console"]
  node_console["Admin console<br/>[layout.tsx]"]
  node_adminapi["Admin API<br/>[routes.go]"]
  node_keys["Keys and projects"]
end

subgraph group_gateway["Model Gateway"]
  node_gatewayapi["Model API<br/>[gateway_http.go]"]
  node_admission["Admission controls"]
  node_routing["Model routing"]
  node_providers["Provider adapters<br/>[providers.go]"]
  node_guardrails["Guardrails<br/>[engine.go]"]
end

subgraph group_operations["Usage and Finance"]
  node_store[("Operational store<br/>[store.go]")]
  node_metering["Usage metering"]
  node_analytics["Usage analytics<br/>[analytics_http.go]"]
  node_reconciliation["Bill reconciliation<br/>[engine.go]"]
end

subgraph group_extensions["Extended Capabilities"]
  node_retrieval["Embeddings and rerank"]
  node_images["Image generation"]
  node_plugins["Plugin runtime<br/>[runtime.go]"]
  node_marketplace["Plugin marketplace<br/>[marketplace.go]"]
end

node_caller(("API caller"))
node_admin(("Administrator"))
node_upstreams["Model providers"]

node_admin -->|"configures"| node_console
node_console -->|"calls"| node_adminapi
node_adminapi -->|"manages"| node_keys
node_adminapi -->|"reads and writes"| node_store
node_caller -->|"submits request"| node_gatewayapi
node_gatewayapi -->|"checks access"| node_admission
node_admission -->|"checks policy"| node_store
node_gatewayapi -->|"evaluates policy"| node_guardrails
node_gatewayapi -->|"routes request"| node_routing
node_routing -->|"selects adapter"| node_providers
node_providers -->|"calls model"| node_upstreams
node_gatewayapi -->|"captures usage"| node_metering
node_metering -->|"persists usage"| node_store
node_analytics -->|"reads usage"| node_store
node_reconciliation -->|"compares usage"| node_store
node_gatewayapi -->|"serves retrieval"| node_retrieval
node_gatewayapi -->|"serves image requests"| node_images
node_adminapi -->|"manages plugins"| node_plugins
node_adminapi -->|"manages marketplace"| node_marketplace

click node_console "https://github.com/astaxie/tokenhub/blob/main/frontend/app/(console)/layout.tsx"
click node_adminapi "https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/routes.go"
click node_keys "https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/admin_projects_http.go"
click node_gatewayapi "https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/gateway_http.go"
click node_admission "https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/admission_settlement.go"
click node_routing "https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/gateway_routed_execution.go"
click node_providers "https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/providers.go"
click node_guardrails "https://github.com/astaxie/tokenhub/blob/main/backend/internal/guardrails/engine.go"
click node_store "https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/store.go"
click node_metering "https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/metering_capture.go"
click node_analytics "https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/analytics_http.go"
click node_reconciliation "https://github.com/astaxie/tokenhub/blob/main/backend/internal/reconciliation/engine.go"
click node_retrieval "https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/retrieval_runtime_routes.go"
click node_images "https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/image_generation.go"
click node_plugins "https://github.com/astaxie/tokenhub/blob/main/backend/internal/plugin/runtime.go"
click node_marketplace "https://github.com/astaxie/tokenhub/blob/main/backend/internal/plugin/marketplace.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_console,node_adminapi,node_keys toneBlue
class node_gatewayapi,node_admission,node_routing,node_providers,node_guardrails toneAmber
class node_store,node_metering,node_analytics,node_reconciliation,node_caller toneMint
class node_retrieval,node_images,node_plugins,node_marketplace toneRose
class node_admin,node_upstreams toneIndigo
```

## Components

### Access and Console

- [Admin console](https://github.com/astaxie/tokenhub/blob/main/frontend/app/(console)/layout.tsx): `frontend/app/(console)/layout.tsx`
- [Admin API](https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/routes.go): `backend/internal/server/routes.go`
- [Keys and projects](https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/admin_projects_http.go): `backend/internal/server/admin_projects_http.go`

### Model Gateway

- [Model API](https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/gateway_http.go): `backend/internal/server/gateway_http.go`
- [Admission controls](https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/admission_settlement.go): `backend/internal/server/admission_settlement.go`
- [Model routing](https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/gateway_routed_execution.go): `backend/internal/server/gateway_routed_execution.go`
- [Provider adapters](https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/providers.go): `backend/internal/server/providers.go`
- [Guardrails](https://github.com/astaxie/tokenhub/blob/main/backend/internal/guardrails/engine.go): `backend/internal/guardrails/engine.go`

### Usage and Finance

- [Operational store](https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/store.go): `backend/internal/server/store.go`
- [Usage metering](https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/metering_capture.go): `backend/internal/server/metering_capture.go`
- [Usage analytics](https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/analytics_http.go): `backend/internal/server/analytics_http.go`
- [Bill reconciliation](https://github.com/astaxie/tokenhub/blob/main/backend/internal/reconciliation/engine.go): `backend/internal/reconciliation/engine.go`

### Extended Capabilities

- [Embeddings and rerank](https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/retrieval_runtime_routes.go): `backend/internal/server/retrieval_runtime_routes.go`
- [Image generation](https://github.com/astaxie/tokenhub/blob/main/backend/internal/server/image_generation.go): `backend/internal/server/image_generation.go`
- [Plugin runtime](https://github.com/astaxie/tokenhub/blob/main/backend/internal/plugin/runtime.go): `backend/internal/plugin/runtime.go`
- [Plugin marketplace](https://github.com/astaxie/tokenhub/blob/main/backend/internal/plugin/marketplace.go): `backend/internal/plugin/marketplace.go`

### Other components

- **API caller**
- **Administrator**
- **Model providers**

## Connections

- Administrator → Admin console: configures
- Admin console → Admin API: calls
- Admin API → Keys and projects: manages
- Admin API → Operational store: reads and writes
- API caller → Model API: submits request
- Model API → Admission controls: checks access
- Admission controls → Operational store: checks policy
- Model API → Guardrails: evaluates policy
- Model API → Model routing: routes request
- Model routing → Provider adapters: selects adapter
- Provider adapters → Model providers: calls model
- Model API → Usage metering: captures usage
- Usage metering → Operational store: persists usage
- Usage analytics → Operational store: reads usage
- Bill reconciliation → Operational store: compares usage
- Model API → Embeddings and rerank: serves retrieval
- Model API → Image generation: serves image requests
- Admin API → Plugin runtime: manages plugins
- Admin API → Plugin marketplace: manages marketplace