# bugwz/aimeter architecture

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

- Interactive diagram: https://gitdiagram.com/bugwz/aimeter
- Repository: https://github.com/bugwz/aimeter

## Overview

AIMeter is a self-hosted dashboard for managing AI provider credentials and viewing quota and usage trends. The main workflow runs from a user through the React app and API to provider-specific usage retrieval, then stores snapshots for dashboard and history views. Settings and endpoint/proxy APIs are additional capabilities; bootstrap, authentication, scheduled refresh, audit logging, and multiple database engines support the service. The README documents these capabilities, while sampled source excerpts provide only partial wiring, so uncertain route-to-service links are omitted.

Main entry points: [`src/services/ApiService.ts`](https://github.com/bugwz/aimeter/blob/main/src/services/ApiService.ts) (API client), [`server/app.ts`](https://github.com/bugwz/aimeter/blob/main/server/app.ts) (Express API), [`server/services/ProviderUsageService.ts`](https://github.com/bugwz/aimeter/blob/main/server/services/ProviderUsageService.ts) (Usage service), [`server/services/ProviderRefreshService.ts`](https://github.com/bugwz/aimeter/blob/main/server/services/ProviderRefreshService.ts) (Provider refresh)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard frontend"]
  node_web["React app<br/>[App.tsx]"]
  node_api_client["API client<br/>[ApiService.ts]"]
  node_dashboard["Usage dashboard<br/>[Dashboard.tsx]"]
  node_history["Usage history<br/>[History.tsx]"]
  node_settings["Settings<br/>[Settings.tsx]"]
  node_endpoint_page["Endpoint page<br/>[Endpoint.tsx]"]
end

subgraph group_api["API and jobs"]
  node_server_app["Express API<br/>[app.ts]"]
  node_provider_routes["Provider routes<br/>[providers.ts]"]
  node_history_routes["History routes<br/>[history.ts]"]
  node_endpoint_routes["Endpoint and proxy<br/>[endpoint.ts]"]
  node_auth_routes["Authentication<br/>[auth.ts]"]
  node_job_routes["Scheduled jobs<br/>[jobs.ts]"]
end

subgraph group_provider["Provider integration"]
  node_refresh_service["Provider refresh"]
  node_usage_service["Usage service"]
  node_adapter_registry["Adapter registry<br/>[registry.ts]"]
  node_provider_adapters["Provider adapters<br/>[index.ts]"]
end

subgraph group_persistence["Persistence"]
  node_storage["Storage facade<br/>[storage.ts]"]
  node_database["Database access<br/>[database.ts]"]
  node_sql_engine["SQL engine<br/>[sql-engine.ts]"]
  node_database_engines["Database engines<br/>[engine.ts]"]
end

node_user(("User"))
node_provider_apis(("AI provider APIs"))
node_database_store[("Configured database")]
node_cron(("Cron trigger"))

node_user -->|"uses"| node_web
node_web -->|"requests"| node_api_client
node_api_client -->|"calls API"| node_server_app
node_server_app -->|"routes requests"| node_provider_routes
node_server_app -->|"routes requests"| node_history_routes
node_server_app -->|"routes requests"| node_endpoint_routes
node_server_app -->|"routes requests"| node_auth_routes
node_provider_routes -->|"refreshes usage"| node_refresh_service
node_refresh_service -->|"fetches usage"| node_usage_service
node_usage_service -->|"selects adapter"| node_adapter_registry
node_adapter_registry -->|"resolves adapter"| node_provider_adapters
node_provider_adapters -->|"fetches usage"| node_provider_apis
node_usage_service -->|"records snapshots"| node_storage
node_history_routes -->|"reads history"| node_storage
node_storage -->|"delegates storage"| node_database
node_database -->|"uses engine"| node_sql_engine
node_sql_engine -->|"implements"| node_database_engines
node_database_engines -->|"reads and writes"| node_database_store
node_dashboard -->|"requests data"| node_api_client
node_history -->|"requests history"| node_api_client
node_settings -->|"requests settings"| node_api_client
node_endpoint_page -->|"requests endpoint"| node_api_client
node_cron -->|"triggers refresh"| node_job_routes
node_job_routes -->|"dispatches refresh"| node_refresh_service

click node_web "https://github.com/bugwz/aimeter/blob/main/src/App.tsx"
click node_api_client "https://github.com/bugwz/aimeter/blob/main/src/services/ApiService.ts"
click node_dashboard "https://github.com/bugwz/aimeter/blob/main/src/components/dashboard/Dashboard.tsx"
click node_history "https://github.com/bugwz/aimeter/blob/main/src/components/history/History.tsx"
click node_settings "https://github.com/bugwz/aimeter/blob/main/src/components/settings/Settings.tsx"
click node_endpoint_page "https://github.com/bugwz/aimeter/blob/main/src/components/endpoint/Endpoint.tsx"
click node_server_app "https://github.com/bugwz/aimeter/blob/main/server/app.ts"
click node_provider_routes "https://github.com/bugwz/aimeter/blob/main/server/routes/providers.ts"
click node_history_routes "https://github.com/bugwz/aimeter/blob/main/server/routes/history.ts"
click node_endpoint_routes "https://github.com/bugwz/aimeter/blob/main/server/routes/endpoint.ts"
click node_auth_routes "https://github.com/bugwz/aimeter/blob/main/server/routes/auth.ts"
click node_job_routes "https://github.com/bugwz/aimeter/blob/main/server/routes/jobs.ts"
click node_refresh_service "https://github.com/bugwz/aimeter/blob/main/server/services/ProviderRefreshService.ts"
click node_usage_service "https://github.com/bugwz/aimeter/blob/main/server/services/ProviderUsageService.ts"
click node_adapter_registry "https://github.com/bugwz/aimeter/blob/main/src/adapters/registry.ts"
click node_provider_adapters "https://github.com/bugwz/aimeter/blob/main/src/adapters/index.ts"
click node_storage "https://github.com/bugwz/aimeter/blob/main/server/storage.ts"
click node_database "https://github.com/bugwz/aimeter/blob/main/server/database.ts"
click node_sql_engine "https://github.com/bugwz/aimeter/blob/main/server/db/sql-engine.ts"
click node_database_engines "https://github.com/bugwz/aimeter/blob/main/server/db/engine.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_web,node_api_client,node_dashboard,node_history,node_settings,node_endpoint_page,node_user toneBlue
class node_server_app,node_provider_routes,node_history_routes,node_endpoint_routes,node_auth_routes,node_job_routes,node_database_store toneAmber
class node_refresh_service,node_usage_service,node_adapter_registry,node_provider_adapters,node_provider_apis toneMint
class node_storage,node_database,node_sql_engine,node_database_engines toneRose
class node_cron toneIndigo
```

## Components

### Dashboard frontend

- [React app](https://github.com/bugwz/aimeter/blob/main/src/App.tsx): `src/App.tsx`
- [API client](https://github.com/bugwz/aimeter/blob/main/src/services/ApiService.ts): `src/services/ApiService.ts`
- [Usage dashboard](https://github.com/bugwz/aimeter/blob/main/src/components/dashboard/Dashboard.tsx): `src/components/dashboard/Dashboard.tsx`
- [Usage history](https://github.com/bugwz/aimeter/blob/main/src/components/history/History.tsx): `src/components/history/History.tsx`
- [Settings](https://github.com/bugwz/aimeter/blob/main/src/components/settings/Settings.tsx): `src/components/settings/Settings.tsx`
- [Endpoint page](https://github.com/bugwz/aimeter/blob/main/src/components/endpoint/Endpoint.tsx): `src/components/endpoint/Endpoint.tsx`

### API and jobs

- [Express API](https://github.com/bugwz/aimeter/blob/main/server/app.ts): `server/app.ts`
- [Provider routes](https://github.com/bugwz/aimeter/blob/main/server/routes/providers.ts): `server/routes/providers.ts`
- [History routes](https://github.com/bugwz/aimeter/blob/main/server/routes/history.ts): `server/routes/history.ts`
- [Endpoint and proxy](https://github.com/bugwz/aimeter/blob/main/server/routes/endpoint.ts): `server/routes/endpoint.ts`
- [Authentication](https://github.com/bugwz/aimeter/blob/main/server/routes/auth.ts): `server/routes/auth.ts`
- [Scheduled jobs](https://github.com/bugwz/aimeter/blob/main/server/routes/jobs.ts): `server/routes/jobs.ts`

### Provider integration

- [Provider refresh](https://github.com/bugwz/aimeter/blob/main/server/services/ProviderRefreshService.ts): `server/services/ProviderRefreshService.ts`
- [Usage service](https://github.com/bugwz/aimeter/blob/main/server/services/ProviderUsageService.ts): `server/services/ProviderUsageService.ts`
- [Adapter registry](https://github.com/bugwz/aimeter/blob/main/src/adapters/registry.ts): `src/adapters/registry.ts`
- [Provider adapters](https://github.com/bugwz/aimeter/blob/main/src/adapters/index.ts): `src/adapters/index.ts`

### Persistence

- [Storage facade](https://github.com/bugwz/aimeter/blob/main/server/storage.ts): `server/storage.ts`
- [Database access](https://github.com/bugwz/aimeter/blob/main/server/database.ts): `server/database.ts`
- [SQL engine](https://github.com/bugwz/aimeter/blob/main/server/db/sql-engine.ts): `server/db/sql-engine.ts`
- [Database engines](https://github.com/bugwz/aimeter/blob/main/server/db/engine.ts): `server/db/engine.ts`

### Other components

- **User**
- **AI provider APIs**
- **Configured database**
- **Cron trigger**

## Connections

- User → React app: uses
- React app → API client: requests
- API client → Express API: calls API
- Express API → Provider routes: routes requests
- Express API → History routes: routes requests
- Express API → Endpoint and proxy: routes requests
- Express API → Authentication: routes requests
- Provider routes → Provider refresh: refreshes usage
- Provider refresh → Usage service: fetches usage
- Usage service → Adapter registry: selects adapter
- Adapter registry → Provider adapters: resolves adapter
- Provider adapters → AI provider APIs: fetches usage
- Usage service → Storage facade: records snapshots
- History routes → Storage facade: reads history
- Storage facade → Database access: delegates storage
- Database access → SQL engine: uses engine
- SQL engine → Database engines: implements
- Database engines → Configured database: reads and writes
- Usage dashboard → API client: requests data
- Usage history → API client: requests history
- Settings → API client: requests settings
- Endpoint page → API client: requests endpoint
- Cron trigger → Scheduled jobs: triggers refresh
- Scheduled jobs → Provider refresh: dispatches refresh