# jdx/mise-versions architecture

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

- Interactive diagram: https://gitdiagram.com/jdx/mise-versions
- Repository: https://github.com/jdx/mise-versions

## Overview

mise-versions publishes version catalogs for mise clients, while its Astro/Worker application provides a tool directory, analytics, and GitHub repository proxying. Scheduled Worker jobs dispatch updates and monitor GitHub-token health; analytics records and summarizes downloads and version activity. The graph includes documented static-data outputs and sampled runtime wiring. Several web routes and data integrations are represented at subsystem level because their implementations were not sampled; unsupported call paths are omitted.

Main entry points: [`src/token-observability.ts`](https://github.com/jdx/mise-versions/blob/main/src/token-observability.ts) (Token observability), [`src/analytics/index.ts`](https://github.com/jdx/mise-versions/blob/main/src/analytics/index.ts) (Analytics composition), [`src/worker.ts`](https://github.com/jdx/mise-versions/blob/main/src/worker.ts) (Worker runtime), [`web/src/pages/api`](https://github.com/jdx/mise-versions/tree/main/web/src/pages/api) (Web API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_versions["Version data"]
  node_tool_versions["Tool version files<br/>[generate-toml.js]"]
  node_versions_index["Versions index"]
  node_github_version_files["GitHub version files"]
end

subgraph group_web["Web application"]
  node_tool_directory["Tool directory<br/>[ToolSearch.tsx]"]
  node_web_api["Web API routes"]
  node_auth["Authentication"]
  node_favorites["Favorites<br/>[favorites.ts]"]
end

subgraph group_analytics["Usage analytics"]
  node_analytics_setup["Analytics composition<br/>[index.ts]"]
  node_download_tracking["Download tracking<br/>[tracking.ts]"]
  node_analytics_rollups["Analytics rollups<br/>[rollups.ts]"]
  node_analytics_queries["Analytics queries<br/>[trends.ts]"]
  node_analytics_schema["Analytics schema<br/>[schema.ts]"]
  node_analytics_engine["Analytics Engine"]
end

subgraph group_github["GitHub proxy"]
  node_github_proxy["GitHub proxy<br/>[mirror.ts]"]
  node_github_cache["Edge cache snippet"]
end

subgraph group_worker["Worker operations"]
  node_worker_runtime["Worker runtime<br/>[worker.ts]"]
  node_token_observability["Token observability"]
  node_token_budget["Token budget rules<br/>[token-budget.ts]"]
  node_worker_migrations["Worker migrations<br/>[migrations.ts]"]
  node_dead_token_cleanup["Dead-token cleanup"]
  node_workflow_dispatch["Update dispatch"]
end

node_mise_clients(("mise clients"))
node_d1[("Cloudflare D1")]
node_analytics_dataset[("Analytics Engine dataset")]
node_github["GitHub"]
node_resend["Resend"]

node_mise_clients -->|"fetch versions"| node_tool_versions
node_mise_clients -->|"fetch index"| node_versions_index
node_mise_clients -->|"fetch baked lists"| node_github_version_files
node_tool_directory -.-> node_web_api
node_web_api -.->|"routes auth"| node_auth
node_web_api -.->|"serves favorites"| node_favorites
node_github_cache -->|"falls back"| node_github_proxy
node_github_proxy -.->|"proxies requests"| node_github
node_analytics_setup -->|"composes"| node_download_tracking
node_analytics_setup -->|"composes"| node_analytics_rollups
node_analytics_setup -->|"composes"| node_analytics_queries
node_analytics_setup -->|"accepts database"| node_d1
node_download_tracking -->|"writes events"| node_analytics_engine
node_analytics_rollups -->|"queries events"| node_analytics_engine
node_analytics_rollups -->|"updates rollups"| node_analytics_schema
node_worker_runtime -->|"runs migrations"| node_worker_migrations
node_worker_runtime -->|"runs cleanup"| node_dead_token_cleanup
node_worker_runtime -->|"runs monitoring"| node_token_observability
node_worker_runtime -->|"dispatches updates"| node_workflow_dispatch
node_token_observability -->|"checks budget"| node_token_budget
node_token_observability -.->|"stores observations"| node_d1
node_token_observability -.->|"checks token quotas"| node_github
node_token_observability -.->|"sends alerts"| node_resend
node_analytics_schema -.->|"defines tables"| node_d1
node_analytics_engine -->|"queries or writes"| node_analytics_dataset

click node_tool_versions "https://github.com/jdx/mise-versions/blob/main/scripts/generate-toml.js"
click node_versions_index "https://github.com/jdx/mise-versions/blob/main/scripts/build-versions-index.js"
click node_github_version_files "https://github.com/jdx/mise-versions/blob/main/scripts/bake-github-versions.js"
click node_tool_directory "https://github.com/jdx/mise-versions/blob/main/web/src/components/ToolSearch.tsx"
click node_web_api "https://github.com/jdx/mise-versions/tree/main/web/src/pages/api"
click node_auth "https://github.com/jdx/mise-versions/tree/main/web/src/pages/api/auth"
click node_favorites "https://github.com/jdx/mise-versions/blob/main/src/favorites.ts"
click node_github_proxy "https://github.com/jdx/mise-versions/blob/main/web/src/lib/github/mirror.ts"
click node_github_cache "https://github.com/jdx/mise-versions/blob/main/snippets/github-mirror-cache.js"
click node_analytics_setup "https://github.com/jdx/mise-versions/blob/main/src/analytics/index.ts"
click node_download_tracking "https://github.com/jdx/mise-versions/blob/main/src/analytics/tracking.ts"
click node_analytics_rollups "https://github.com/jdx/mise-versions/blob/main/src/analytics/rollups.ts"
click node_analytics_queries "https://github.com/jdx/mise-versions/blob/main/src/analytics/trends.ts"
click node_analytics_schema "https://github.com/jdx/mise-versions/blob/main/src/analytics/schema.ts"
click node_analytics_engine "https://github.com/jdx/mise-versions/blob/main/src/analytics/analytics-engine.ts"
click node_worker_runtime "https://github.com/jdx/mise-versions/blob/main/src/worker.ts"
click node_token_observability "https://github.com/jdx/mise-versions/blob/main/src/token-observability.ts"
click node_token_budget "https://github.com/jdx/mise-versions/blob/main/src/token-budget.ts"
click node_worker_migrations "https://github.com/jdx/mise-versions/blob/main/src/migrations.ts"
click node_dead_token_cleanup "https://github.com/jdx/mise-versions/blob/main/src/dead-token-cleanup.ts"
click node_workflow_dispatch "https://github.com/jdx/mise-versions/blob/main/src/workflow-dispatch.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_tool_versions,node_versions_index,node_github_version_files,node_mise_clients toneBlue
class node_tool_directory,node_web_api,node_auth,node_favorites,node_d1,node_analytics_dataset toneAmber
class node_analytics_setup,node_download_tracking,node_analytics_rollups,node_analytics_queries,node_analytics_schema,node_analytics_engine toneMint
class node_github_proxy,node_github_cache toneRose
class node_worker_runtime,node_token_observability,node_token_budget,node_worker_migrations,node_dead_token_cleanup,node_workflow_dispatch,node_github,node_resend toneIndigo
```

## Components

### Version data

- [Tool version files](https://github.com/jdx/mise-versions/blob/main/scripts/generate-toml.js): `scripts/generate-toml.js`
- [Versions index](https://github.com/jdx/mise-versions/blob/main/scripts/build-versions-index.js): `scripts/build-versions-index.js`
- [GitHub version files](https://github.com/jdx/mise-versions/blob/main/scripts/bake-github-versions.js): `scripts/bake-github-versions.js`

### Web application

- [Tool directory](https://github.com/jdx/mise-versions/blob/main/web/src/components/ToolSearch.tsx): `web/src/components/ToolSearch.tsx`
- [Web API routes](https://github.com/jdx/mise-versions/tree/main/web/src/pages/api): `web/src/pages/api`
- [Authentication](https://github.com/jdx/mise-versions/tree/main/web/src/pages/api/auth): `web/src/pages/api/auth`
- [Favorites](https://github.com/jdx/mise-versions/blob/main/src/favorites.ts): `src/favorites.ts`

### Usage analytics

- [Analytics composition](https://github.com/jdx/mise-versions/blob/main/src/analytics/index.ts): `src/analytics/index.ts`
- [Download tracking](https://github.com/jdx/mise-versions/blob/main/src/analytics/tracking.ts): `src/analytics/tracking.ts`
- [Analytics rollups](https://github.com/jdx/mise-versions/blob/main/src/analytics/rollups.ts): `src/analytics/rollups.ts`
- [Analytics queries](https://github.com/jdx/mise-versions/blob/main/src/analytics/trends.ts): `src/analytics/trends.ts`
- [Analytics schema](https://github.com/jdx/mise-versions/blob/main/src/analytics/schema.ts): `src/analytics/schema.ts`
- [Analytics Engine](https://github.com/jdx/mise-versions/blob/main/src/analytics/analytics-engine.ts): `src/analytics/analytics-engine.ts`

### GitHub proxy

- [GitHub proxy](https://github.com/jdx/mise-versions/blob/main/web/src/lib/github/mirror.ts): `web/src/lib/github/mirror.ts`
- [Edge cache snippet](https://github.com/jdx/mise-versions/blob/main/snippets/github-mirror-cache.js): `snippets/github-mirror-cache.js`

### Worker operations

- [Worker runtime](https://github.com/jdx/mise-versions/blob/main/src/worker.ts): `src/worker.ts`
- [Token observability](https://github.com/jdx/mise-versions/blob/main/src/token-observability.ts): `src/token-observability.ts`
- [Token budget rules](https://github.com/jdx/mise-versions/blob/main/src/token-budget.ts): `src/token-budget.ts`
- [Worker migrations](https://github.com/jdx/mise-versions/blob/main/src/migrations.ts): `src/migrations.ts`
- [Dead-token cleanup](https://github.com/jdx/mise-versions/blob/main/src/dead-token-cleanup.ts): `src/dead-token-cleanup.ts`
- [Update dispatch](https://github.com/jdx/mise-versions/blob/main/src/workflow-dispatch.ts): `src/workflow-dispatch.ts`

### Other components

- **mise clients**
- **Cloudflare D1**
- **Analytics Engine dataset**
- **GitHub**
- **Resend**

## Connections

- mise clients → Tool version files: fetch versions (evidence: `README.md`)
- mise clients → Versions index: fetch index (evidence: `README.md`)
- mise clients → GitHub version files: fetch baked lists (evidence: `README.md`)
- Tool directory → Web API routes
- Web API routes → Authentication: routes auth
- Web API routes → Favorites: serves favorites
- Edge cache snippet → GitHub proxy: falls back (evidence: `snippets/github-mirror-cache.js`)
- GitHub proxy → GitHub: proxies requests
- Analytics composition → Download tracking: composes (evidence: `src/analytics/index.ts`)
- Analytics composition → Analytics rollups: composes (evidence: `src/analytics/index.ts`)
- Analytics composition → Analytics queries: composes (evidence: `src/analytics/index.ts`)
- Analytics composition → Cloudflare D1: accepts database (evidence: `src/analytics/index.ts`)
- Download tracking → Analytics Engine: writes events (evidence: `src/analytics/tracking.ts`)
- Analytics rollups → Analytics Engine: queries events (evidence: `src/analytics/rollups.ts`)
- Analytics rollups → Analytics schema: updates rollups (evidence: `src/analytics/rollups.ts`)
- Worker runtime → Worker migrations: runs migrations (evidence: `src/worker.ts`)
- Worker runtime → Dead-token cleanup: runs cleanup (evidence: `src/worker.ts`)
- Worker runtime → Token observability: runs monitoring (evidence: `src/worker.ts`)
- Worker runtime → Update dispatch: dispatches updates (evidence: `src/worker.ts`)
- Token observability → Token budget rules: checks budget (evidence: `src/token-observability.ts`)
- Token observability → Cloudflare D1: stores observations
- Token observability → GitHub: checks token quotas
- Token observability → Resend: sends alerts (evidence: `README.md`)
- Analytics schema → Cloudflare D1: defines tables
- Analytics Engine → Analytics Engine dataset: queries or writes (evidence: `src/analytics/analytics-engine.ts`)