# agentregistry-dev/agentregistry architecture

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

- Interactive diagram: https://gitdiagram.com/agentregistry-dev/agentregistry
- Repository: https://github.com/agentregistry-dev/agentregistry

## Overview

AgentRegistry is a catalog and delivery platform for MCP servers, agents, skills, and prompts. A developer authors or selects an artifact, registers it through arctl or the web UI, and consumes it by running locally or deploying to a shared environment; IDE configuration is another documented consumption path. The graph includes the CLI, web/API surfaces, persistence, and reconciliation as distinct layers. Several runtime connections are documented in the README; sampled source confirms selected API, store, and controller responsibilities, but not every route or UI request.

Main entry points: [`pkg/registry/v1alpha1store/store.go`](https://github.com/agentregistry-dev/agentregistry/blob/main/pkg/registry/v1alpha1store/store.go) (Versioned resource store), [`internal/cli/commands`](https://github.com/agentregistry-dev/agentregistry/tree/main/internal/cli/commands) (CLI workflows), [`internal/registry/api/server.go`](https://github.com/agentregistry-dev/agentregistry/blob/main/internal/registry/api/server.go) (HTTP server), [`internal/registry/api/router/router.go`](https://github.com/agentregistry-dev/agentregistry/blob/main/internal/registry/api/router/router.go) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_author["Build and author"]
  node_artifacts["Artifact definitions"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["arctl CLI<br/>[root.go]"]
  node_cli_commands["CLI workflows"]
  node_ide_config["IDE configuration<br/>[configure.go]"]
  node_web_ui["Admin web UI<br/>[page.tsx]"]
  node_ui_api["UI API client<br/>[client.gen.ts]"]
end

subgraph group_registry["Registry services"]
  node_http_server["HTTP server<br/>[server.go]"]
  node_router["API routes<br/>[router.go]"]
  node_resource_api["Resource handlers<br/>[handler.go]"]
  node_compat_api["MCP compatibility API<br/>[handlers.go]"]
  node_mcp_bridge["MCP catalog bridge<br/>[server.go]"]
  node_auth["Access control<br/>[auth.go]"]
  node_store[("Versioned resource store<br/>[store.go]")]
  node_database[("Database<br/>[database.go]")]
end

subgraph group_runtime["Delivery and runtime"]
  node_deploy_controller["Deployment reconciliation<br/>[controller.go]"]
  node_plugin_controller["Plugin reconciliation"]
  node_skill_controller["Skill reconciliation"]
  node_local_run["Local execution<br/>[runtime.go]"]
end

node_developer(("Developer"))
node_kubernetes{{"Kubernetes environment"}}
node_ai_client(("AI client"))
node_gateway{{"agentgateway"}}
node_package_sources{{"Artifact sources"}}

node_developer -->|"uses"| node_cli
node_developer -->|"uses"| node_web_ui
node_developer -->|"defines"| node_artifacts
node_cli -->|"dispatches"| node_cli_commands
node_cli_commands -->|"registers"| node_artifacts
node_cli_commands -->|"runs locally"| node_local_run
node_cli_commands -->|"configures clients"| node_ide_config
node_web_ui -.->|"requests data"| node_ui_api
node_ui_api -.->|"sends HTTP"| node_http_server
node_http_server -->|"registers routes"| node_router
node_router -->|"registers handlers"| node_resource_api
node_router -->|"registers routes"| node_compat_api
node_resource_api -->|"reads and writes"| node_store
node_compat_api -->|"reads resources"| node_store
node_mcp_bridge -->|"reads resources"| node_store
node_http_server -.->|"configures access"| node_auth
node_store -.->|"persists records"| node_database
node_deploy_controller -->|"reconciles deployments"| node_store
node_skill_controller -->|"resolves skill records"| node_store
node_plugin_controller -->|"reconciles plugins"| node_store
node_package_sources -->|"supplies packages"| node_artifacts
node_kubernetes -.->|"hosts deployments"| node_deploy_controller
node_local_run -.->|"serves locally"| node_ai_client
node_gateway -.->|"provides access"| node_ai_client
node_mcp_bridge -.->|"serves MCP tools"| node_ai_client

click node_artifacts "https://github.com/agentregistry-dev/agentregistry/tree/main/pkg/api/v1alpha1"
click node_cli "https://github.com/agentregistry-dev/agentregistry/blob/main/pkg/cli/root.go"
click node_cli_commands "https://github.com/agentregistry-dev/agentregistry/tree/main/internal/cli/commands"
click node_ide_config "https://github.com/agentregistry-dev/agentregistry/blob/main/internal/cli/configure/configure.go"
click node_web_ui "https://github.com/agentregistry-dev/agentregistry/blob/main/ui/app/page.tsx"
click node_ui_api "https://github.com/agentregistry-dev/agentregistry/blob/main/ui/lib/api/client/client.gen.ts"
click node_http_server "https://github.com/agentregistry-dev/agentregistry/blob/main/internal/registry/api/server.go"
click node_router "https://github.com/agentregistry-dev/agentregistry/blob/main/internal/registry/api/router/router.go"
click node_resource_api "https://github.com/agentregistry-dev/agentregistry/blob/main/pkg/registry/resource/handler.go"
click node_compat_api "https://github.com/agentregistry-dev/agentregistry/blob/main/internal/registry/api/handlers/mcpregistry/handlers.go"
click node_mcp_bridge "https://github.com/agentregistry-dev/agentregistry/blob/main/internal/mcp/registryserver/server.go"
click node_auth "https://github.com/agentregistry-dev/agentregistry/blob/main/pkg/registry/auth/auth.go"
click node_store "https://github.com/agentregistry-dev/agentregistry/blob/main/pkg/registry/v1alpha1store/store.go"
click node_database "https://github.com/agentregistry-dev/agentregistry/blob/main/pkg/registry/database/database.go"
click node_deploy_controller "https://github.com/agentregistry-dev/agentregistry/blob/main/internal/registry/controller/controller.go"
click node_plugin_controller "https://github.com/agentregistry-dev/agentregistry/blob/main/internal/registry/controller/plugin_controller.go"
click node_skill_controller "https://github.com/agentregistry-dev/agentregistry/blob/main/internal/registry/controller/skill_controller.go"
click node_local_run "https://github.com/agentregistry-dev/agentregistry/blob/main/pkg/cli/runtime/runtime.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_artifacts,node_ai_client toneBlue
class node_cli,node_cli_commands,node_ide_config,node_web_ui,node_ui_api toneAmber
class node_http_server,node_router,node_resource_api,node_compat_api,node_mcp_bridge,node_auth,node_store,node_database toneMint
class node_deploy_controller,node_plugin_controller,node_skill_controller,node_local_run toneRose
class node_developer,node_kubernetes,node_gateway,node_package_sources toneIndigo
```

## Components

### Build and author

- [Artifact definitions](https://github.com/agentregistry-dev/agentregistry/tree/main/pkg/api/v1alpha1): `pkg/api/v1alpha1`

### User interfaces

- [arctl CLI](https://github.com/agentregistry-dev/agentregistry/blob/main/pkg/cli/root.go): `pkg/cli/root.go`
- [CLI workflows](https://github.com/agentregistry-dev/agentregistry/tree/main/internal/cli/commands): `internal/cli/commands`
- [IDE configuration](https://github.com/agentregistry-dev/agentregistry/blob/main/internal/cli/configure/configure.go): `internal/cli/configure/configure.go`
- [Admin web UI](https://github.com/agentregistry-dev/agentregistry/blob/main/ui/app/page.tsx): `ui/app/page.tsx`
- [UI API client](https://github.com/agentregistry-dev/agentregistry/blob/main/ui/lib/api/client/client.gen.ts): `ui/lib/api/client/client.gen.ts`

### Registry services

- [HTTP server](https://github.com/agentregistry-dev/agentregistry/blob/main/internal/registry/api/server.go): `internal/registry/api/server.go`
- [API routes](https://github.com/agentregistry-dev/agentregistry/blob/main/internal/registry/api/router/router.go): `internal/registry/api/router/router.go`
- [Resource handlers](https://github.com/agentregistry-dev/agentregistry/blob/main/pkg/registry/resource/handler.go): `pkg/registry/resource/handler.go`
- [MCP compatibility API](https://github.com/agentregistry-dev/agentregistry/blob/main/internal/registry/api/handlers/mcpregistry/handlers.go): `internal/registry/api/handlers/mcpregistry/handlers.go`
- [MCP catalog bridge](https://github.com/agentregistry-dev/agentregistry/blob/main/internal/mcp/registryserver/server.go): `internal/mcp/registryserver/server.go`
- [Access control](https://github.com/agentregistry-dev/agentregistry/blob/main/pkg/registry/auth/auth.go): `pkg/registry/auth/auth.go`
- [Versioned resource store](https://github.com/agentregistry-dev/agentregistry/blob/main/pkg/registry/v1alpha1store/store.go): `pkg/registry/v1alpha1store/store.go`
- [Database](https://github.com/agentregistry-dev/agentregistry/blob/main/pkg/registry/database/database.go): `pkg/registry/database/database.go`

### Delivery and runtime

- [Deployment reconciliation](https://github.com/agentregistry-dev/agentregistry/blob/main/internal/registry/controller/controller.go): `internal/registry/controller/controller.go`
- [Plugin reconciliation](https://github.com/agentregistry-dev/agentregistry/blob/main/internal/registry/controller/plugin_controller.go): `internal/registry/controller/plugin_controller.go`
- [Skill reconciliation](https://github.com/agentregistry-dev/agentregistry/blob/main/internal/registry/controller/skill_controller.go): `internal/registry/controller/skill_controller.go`
- [Local execution](https://github.com/agentregistry-dev/agentregistry/blob/main/pkg/cli/runtime/runtime.go): `pkg/cli/runtime/runtime.go`

### Other components

- **Developer**
- **Kubernetes environment**
- **AI client**
- **agentgateway**
- **Artifact sources**

## Connections

- Developer → arctl CLI: uses
- Developer → Admin web UI: uses
- Developer → Artifact definitions: defines
- arctl CLI → CLI workflows: dispatches (evidence: `pkg/cli/root.go`)
- CLI workflows → Artifact definitions: registers
- CLI workflows → Local execution: runs locally
- CLI workflows → IDE configuration: configures clients
- Admin web UI → UI API client: requests data
- UI API client → HTTP server: sends HTTP
- HTTP server → API routes: registers routes (evidence: `internal/registry/api/server.go`)
- API routes → Resource handlers: registers handlers (evidence: `internal/registry/api/router/router.go`)
- API routes → MCP compatibility API: registers routes (evidence: `internal/registry/api/router/router.go`)
- Resource handlers → Versioned resource store: reads and writes (evidence: `pkg/registry/resource/handler.go`)
- MCP compatibility API → Versioned resource store: reads resources (evidence: `internal/registry/api/handlers/mcpregistry/handlers.go`)
- MCP catalog bridge → Versioned resource store: reads resources (evidence: `internal/mcp/registryserver/server.go`)
- HTTP server → Access control: configures access (evidence: `internal/registry/api/server.go`)
- Versioned resource store → Database: persists records
- Deployment reconciliation → Versioned resource store: reconciles deployments (evidence: `internal/registry/controller/controller.go`)
- Skill reconciliation → Versioned resource store: resolves skill records (evidence: `internal/registry/controller/skill_controller.go`)
- Plugin reconciliation → Versioned resource store: reconciles plugins (evidence: `internal/registry/controller/plugin_controller.go`)
- Artifact sources → Artifact definitions: supplies packages
- Kubernetes environment → Deployment reconciliation: hosts deployments
- Local execution → AI client: serves locally
- agentgateway → AI client: provides access
- MCP catalog bridge → AI client: serves MCP tools
