# rynfar/meridian architecture

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

## Overview

Meridian is a local API bridge that lets supported coding clients use Claude and Antigravity subscriptions, with web-based provider management and usage monitoring plus an optional Mac desktop app. The main workflow is client request handling, client-format translation, provider/account selection, and generation through the corresponding provider runtime; telemetry records activity for dashboard views. The README documents the broader Antigravity tool, media, and conversation-continuity capabilities, reflected here at the subsystem level. Source excerpts were limited, so uncertain internal call links are omitted.

Main entry points: [`src/proxy/server.ts`](https://github.com/rynfar/meridian/blob/main/src/proxy/server.ts) (API server), [`apps/desktop/src/main.ts`](https://github.com/rynfar/meridian/blob/main/apps/desktop/src/main.ts) (Desktop shell), [`apps/desktop/src/manager.ts`](https://github.com/rynfar/meridian/blob/main/apps/desktop/src/manager.ts) (Service manager), [`src/telemetry/routes.ts`](https://github.com/rynfar/meridian/blob/main/src/telemetry/routes.ts) (Telemetry API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request Bridge"]
  node_proxy["API server<br/>[server.ts]"]
  node_adapters["Client adapters"]
  node_transforms["Request transforms<br/>[registry.ts]"]
  node_routing["Profile routing<br/>[routing.ts]"]
  node_sessions[("Session continuity<br/>[sessionStore.ts]")]
end

subgraph group_providers["Provider Runtimes"]
  node_claude["Claude runtime<br/>[query.ts]"]
  node_antigravity["Antigravity runtime"]
end

subgraph group_management["Provider Management"]
  node_profiles[("Account profiles<br/>[profiles.ts]")]
  node_provider_setup["Provider setup<br/>[providerSetup.ts]"]
  node_plugin_loader["Plugin loading<br/>[loader.ts]"]
end

subgraph group_observability["Usage and Diagnostics"]
  node_telemetry[("Telemetry stores<br/>[index.ts]")]
  node_telemetry_routes["Telemetry API<br/>[routes.ts]"]
  node_dashboard["Usage dashboard<br/>[dashboard.ts]"]
end

subgraph group_desktop["Desktop App"]
  node_desktop_main["Desktop shell<br/>[main.ts]"]
  node_desktop_manager["Service manager<br/>[manager.ts]"]
  node_desktop_ui["Desktop interface<br/>[renderer.ts]"]
  node_desktop_setup["Client setup<br/>[clientSetup.ts]"]
end

node_clients(("Coding clients"))
node_agy["Official agy CLI"]
node_anthropic["Anthropic Agent SDK"]

node_clients -->|"send requests"| node_proxy
node_proxy -->|"dispatch formats"| node_adapters
node_adapters -->|"translate requests"| node_transforms
node_proxy -->|"select profiles"| node_routing
node_proxy -->|"resume sessions"| node_sessions
node_proxy -->|"invoke Claude"| node_claude
node_claude -->|"generate"| node_anthropic
node_proxy -->|"invoke Antigravity"| node_antigravity
node_antigravity -->|"run CLI"| node_agy
node_routing -->|"read profiles"| node_profiles
node_proxy -->|"record activity"| node_telemetry
node_telemetry_routes -->|"read metrics"| node_telemetry
node_telemetry_routes -->|"serve dashboard"| node_dashboard
node_desktop_main -->|"dispatch actions"| node_desktop_manager
node_desktop_ui -->|"invoke actions"| node_desktop_main
node_desktop_manager -->|"query service"| node_proxy
node_desktop_manager -->|"fetch provider status"| node_telemetry_routes
node_desktop_setup -->|"build setup command"| node_provider_setup
node_desktop_main -->|"copy client setup"| node_desktop_setup
node_proxy -.->|"load plugins"| node_plugin_loader

click node_proxy "https://github.com/rynfar/meridian/blob/main/src/proxy/server.ts"
click node_adapters "https://github.com/rynfar/meridian/tree/main/src/proxy/adapters"
click node_transforms "https://github.com/rynfar/meridian/blob/main/src/proxy/transforms/registry.ts"
click node_routing "https://github.com/rynfar/meridian/blob/main/src/proxy/routing.ts"
click node_sessions "https://github.com/rynfar/meridian/blob/main/src/proxy/sessionStore.ts"
click node_claude "https://github.com/rynfar/meridian/blob/main/src/proxy/query.ts"
click node_antigravity "https://github.com/rynfar/meridian/blob/main/src/proxy/backends/antigravityRuntime.ts"
click node_profiles "https://github.com/rynfar/meridian/blob/main/src/proxy/profiles.ts"
click node_provider_setup "https://github.com/rynfar/meridian/blob/main/src/telemetry/providerSetup.ts"
click node_plugin_loader "https://github.com/rynfar/meridian/blob/main/src/proxy/plugins/loader.ts"
click node_telemetry "https://github.com/rynfar/meridian/blob/main/src/telemetry/index.ts"
click node_telemetry_routes "https://github.com/rynfar/meridian/blob/main/src/telemetry/routes.ts"
click node_dashboard "https://github.com/rynfar/meridian/blob/main/src/telemetry/dashboard.ts"
click node_desktop_main "https://github.com/rynfar/meridian/blob/main/apps/desktop/src/main.ts"
click node_desktop_manager "https://github.com/rynfar/meridian/blob/main/apps/desktop/src/manager.ts"
click node_desktop_ui "https://github.com/rynfar/meridian/blob/main/apps/desktop/src/renderer.ts"
click node_desktop_setup "https://github.com/rynfar/meridian/blob/main/apps/desktop/src/clientSetup.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_proxy,node_adapters,node_transforms,node_routing,node_sessions,node_clients toneBlue
class node_claude,node_antigravity toneAmber
class node_profiles,node_provider_setup,node_plugin_loader toneMint
class node_telemetry,node_telemetry_routes,node_dashboard toneRose
class node_desktop_main,node_desktop_manager,node_desktop_ui,node_desktop_setup,node_agy,node_anthropic toneIndigo
```

## Components

### Request Bridge

- [API server](https://github.com/rynfar/meridian/blob/main/src/proxy/server.ts): `src/proxy/server.ts`
- [Client adapters](https://github.com/rynfar/meridian/tree/main/src/proxy/adapters): `src/proxy/adapters`
- [Request transforms](https://github.com/rynfar/meridian/blob/main/src/proxy/transforms/registry.ts): `src/proxy/transforms/registry.ts`
- [Profile routing](https://github.com/rynfar/meridian/blob/main/src/proxy/routing.ts): `src/proxy/routing.ts`
- [Session continuity](https://github.com/rynfar/meridian/blob/main/src/proxy/sessionStore.ts): `src/proxy/sessionStore.ts`

### Provider Runtimes

- [Claude runtime](https://github.com/rynfar/meridian/blob/main/src/proxy/query.ts): `src/proxy/query.ts`
- [Antigravity runtime](https://github.com/rynfar/meridian/blob/main/src/proxy/backends/antigravityRuntime.ts): `src/proxy/backends/antigravityRuntime.ts`

### Provider Management

- [Account profiles](https://github.com/rynfar/meridian/blob/main/src/proxy/profiles.ts): `src/proxy/profiles.ts`
- [Provider setup](https://github.com/rynfar/meridian/blob/main/src/telemetry/providerSetup.ts): `src/telemetry/providerSetup.ts`
- [Plugin loading](https://github.com/rynfar/meridian/blob/main/src/proxy/plugins/loader.ts): `src/proxy/plugins/loader.ts`

### Usage and Diagnostics

- [Telemetry stores](https://github.com/rynfar/meridian/blob/main/src/telemetry/index.ts): `src/telemetry/index.ts`
- [Telemetry API](https://github.com/rynfar/meridian/blob/main/src/telemetry/routes.ts): `src/telemetry/routes.ts`
- [Usage dashboard](https://github.com/rynfar/meridian/blob/main/src/telemetry/dashboard.ts): `src/telemetry/dashboard.ts`

### Desktop App

- [Desktop shell](https://github.com/rynfar/meridian/blob/main/apps/desktop/src/main.ts): `apps/desktop/src/main.ts`
- [Service manager](https://github.com/rynfar/meridian/blob/main/apps/desktop/src/manager.ts): `apps/desktop/src/manager.ts`
- [Desktop interface](https://github.com/rynfar/meridian/blob/main/apps/desktop/src/renderer.ts): `apps/desktop/src/renderer.ts`
- [Client setup](https://github.com/rynfar/meridian/blob/main/apps/desktop/src/clientSetup.ts): `apps/desktop/src/clientSetup.ts`

### Other components

- **Coding clients**
- **Official agy CLI**
- **Anthropic Agent SDK**

## Connections

- Coding clients → API server: send requests
- API server → Client adapters: dispatch formats
- Client adapters → Request transforms: translate requests
- API server → Profile routing: select profiles
- API server → Session continuity: resume sessions
- API server → Claude runtime: invoke Claude
- Claude runtime → Anthropic Agent SDK: generate
- API server → Antigravity runtime: invoke Antigravity
- Antigravity runtime → Official agy CLI: run CLI
- Profile routing → Account profiles: read profiles
- API server → Telemetry stores: record activity
- Telemetry API → Telemetry stores: read metrics
- Telemetry API → Usage dashboard: serve dashboard
- Desktop shell → Service manager: dispatch actions
- Desktop interface → Desktop shell: invoke actions
- Service manager → API server: query service
- Service manager → Telemetry API: fetch provider status
- Client setup → Provider setup: build setup command
- Desktop shell → Client setup: copy client setup
- API server → Plugin loading: load plugins