# marmotdata/marmot architecture

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

- Interactive diagram: https://gitdiagram.com/marmotdata/marmot
- Repository: https://github.com/marmotdata/marmot

## Overview

Marmot is a governed data catalog and query gateway: source plugins discover metadata, which users and agents can search, understand, trace, and query under access controls. The main entry points are the web/API, CLI, SDKs, and MCP server; ingestion and OpenLineage populate catalog state, while PostgreSQL backs the application. README statements support the product-level workflow links; source excerpts support the server wiring, ingest behavior, MCP service dependencies, plugin updates, and operator reconciliation shown here. Some unsampled subsystem links are intentionally omitted.

Main entry points: [`internal/api/v1/server.go`](https://github.com/marmotdata/marmot/blob/main/internal/api/v1/server.go) (HTTP API), [`internal/mcp/server.go`](https://github.com/marmotdata/marmot/blob/main/internal/mcp/server.go) (MCP server), [`plugins`](https://github.com/marmotdata/marmot/tree/main/plugins) (Source plugins), [`internal/core/dataquery/service.go`](https://github.com/marmotdata/marmot/blob/main/internal/core/dataquery/service.go) (Governed SQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Access and interfaces"]
  node_web["Web interface<br/>[handler.go]"]
  node_api["HTTP API<br/>[server.go]"]
  node_cli["CLI<br/>[root.go]"]
  node_sdk["Go SDK<br/>[query_client.go]"]
  node_mcp["MCP server<br/>[server.go]"]
end

subgraph group_catalog["Catalog and governance"]
  node_asset_catalog["Asset catalog<br/>[service.go]"]
  node_lineage["Lineage<br/>[service.go]"]
  node_glossary["Glossary<br/>[service.go]"]
  node_products["Data products<br/>[service.go]"]
  node_ownership["Teams and ownership<br/>[service.go]"]
end

subgraph group_ingest["Ingestion and pipelines"]
  node_ingest_cli["Ingest workflow<br/>[ingest.go]"]
  node_plugins["Source plugins"]
  node_plugin_updates["Plugin updates<br/>[manager.go]"]
  node_run_operator["Run operator<br/>[run_controller.go]"]
end

subgraph group_query["Search and governed queries"]
  node_search["Catalog search<br/>[service.go]"]
  node_query_service["Governed SQL<br/>[service.go]"]
  node_query_language["Query language<br/>[query.go]"]
end

subgraph group_platform["Runtime and persistence"]
  node_postgres[("PostgreSQL<br/>[setup.go]")]
  node_auth["Identity and access<br/>[service.go]"]
end

node_people(("People"))
node_agents(("AI agents"))

node_people -->|"use"| node_web
node_people -->|"use"| node_cli
node_people -->|"use"| node_sdk
node_agents -->|"connect"| node_mcp
node_web -.->|"request"| node_api
node_cli -->|"request"| node_api
node_sdk -->|"request"| node_api
node_mcp -->|"searches"| node_search
node_mcp -->|"traces"| node_lineage
node_mcp -->|"looks up"| node_glossary
node_mcp -->|"explores"| node_products
node_mcp -->|"queries"| node_query_service
node_api -->|"serves catalog"| node_asset_catalog
node_api -->|"serves lineage"| node_lineage
node_api -->|"serves glossary"| node_glossary
node_api -->|"serves products"| node_products
node_api -->|"serves search"| node_search
node_api -->|"serves queries"| node_query_service
node_ingest_cli -->|"starts runs"| node_api
node_ingest_cli -->|"runs source"| node_plugins
node_plugins -->|"populate metadata"| node_asset_catalog
node_plugins -->|"provide lineage"| node_lineage
node_api -->|"persists state"| node_postgres
node_query_service -->|"checks roles"| node_auth
node_query_service -->|"records audit"| node_postgres
node_search -->|"supports filters"| node_query_language
node_plugin_updates -->|"switches versions"| node_plugins
node_run_operator -.->|"reconciles run state"| node_postgres
node_asset_catalog -.->|"stores assets"| node_postgres

click node_web "https://github.com/marmotdata/marmot/blob/main/internal/api/v1/ui/handler.go"
click node_api "https://github.com/marmotdata/marmot/blob/main/internal/api/v1/server.go"
click node_cli "https://github.com/marmotdata/marmot/blob/main/internal/cmd/root.go"
click node_sdk "https://github.com/marmotdata/marmot/blob/main/sdk/go/internal/gen/client/query/query_client.go"
click node_mcp "https://github.com/marmotdata/marmot/blob/main/internal/mcp/server.go"
click node_asset_catalog "https://github.com/marmotdata/marmot/blob/main/internal/core/asset/service.go"
click node_lineage "https://github.com/marmotdata/marmot/blob/main/internal/core/lineage/service.go"
click node_glossary "https://github.com/marmotdata/marmot/blob/main/internal/core/glossary/service.go"
click node_products "https://github.com/marmotdata/marmot/blob/main/internal/core/dataproduct/service.go"
click node_ownership "https://github.com/marmotdata/marmot/blob/main/internal/core/team/service.go"
click node_ingest_cli "https://github.com/marmotdata/marmot/blob/main/internal/cmd/ingest.go"
click node_plugins "https://github.com/marmotdata/marmot/tree/main/plugins"
click node_plugin_updates "https://github.com/marmotdata/marmot/blob/main/internal/plugin/updates/manager.go"
click node_run_operator "https://github.com/marmotdata/marmot/blob/main/internal/operator/controller/run_controller.go"
click node_search "https://github.com/marmotdata/marmot/blob/main/internal/core/search/service.go"
click node_query_service "https://github.com/marmotdata/marmot/blob/main/internal/core/dataquery/service.go"
click node_query_language "https://github.com/marmotdata/marmot/blob/main/internal/query/query.go"
click node_postgres "https://github.com/marmotdata/marmot/blob/main/internal/store/postgres/setup.go"
click node_auth "https://github.com/marmotdata/marmot/blob/main/internal/core/auth/service.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_web,node_api,node_cli,node_sdk,node_mcp toneBlue
class node_asset_catalog,node_lineage,node_glossary,node_products,node_ownership toneAmber
class node_ingest_cli,node_plugins,node_plugin_updates,node_run_operator toneMint
class node_search,node_query_service,node_query_language toneRose
class node_postgres,node_auth,node_people,node_agents toneIndigo
```

## Components

### Access and interfaces

- [Web interface](https://github.com/marmotdata/marmot/blob/main/internal/api/v1/ui/handler.go): `internal/api/v1/ui/handler.go`
- [HTTP API](https://github.com/marmotdata/marmot/blob/main/internal/api/v1/server.go): `internal/api/v1/server.go`
- [CLI](https://github.com/marmotdata/marmot/blob/main/internal/cmd/root.go): `internal/cmd/root.go`
- [Go SDK](https://github.com/marmotdata/marmot/blob/main/sdk/go/internal/gen/client/query/query_client.go): `sdk/go/internal/gen/client/query/query_client.go`
- [MCP server](https://github.com/marmotdata/marmot/blob/main/internal/mcp/server.go): `internal/mcp/server.go`

### Catalog and governance

- [Asset catalog](https://github.com/marmotdata/marmot/blob/main/internal/core/asset/service.go): `internal/core/asset/service.go`
- [Lineage](https://github.com/marmotdata/marmot/blob/main/internal/core/lineage/service.go): `internal/core/lineage/service.go`
- [Glossary](https://github.com/marmotdata/marmot/blob/main/internal/core/glossary/service.go): `internal/core/glossary/service.go`
- [Data products](https://github.com/marmotdata/marmot/blob/main/internal/core/dataproduct/service.go): `internal/core/dataproduct/service.go`
- [Teams and ownership](https://github.com/marmotdata/marmot/blob/main/internal/core/team/service.go): `internal/core/team/service.go`

### Ingestion and pipelines

- [Ingest workflow](https://github.com/marmotdata/marmot/blob/main/internal/cmd/ingest.go): `internal/cmd/ingest.go`
- [Source plugins](https://github.com/marmotdata/marmot/tree/main/plugins): `plugins`
- [Plugin updates](https://github.com/marmotdata/marmot/blob/main/internal/plugin/updates/manager.go): `internal/plugin/updates/manager.go`
- [Run operator](https://github.com/marmotdata/marmot/blob/main/internal/operator/controller/run_controller.go): `internal/operator/controller/run_controller.go`

### Search and governed queries

- [Catalog search](https://github.com/marmotdata/marmot/blob/main/internal/core/search/service.go): `internal/core/search/service.go`
- [Governed SQL](https://github.com/marmotdata/marmot/blob/main/internal/core/dataquery/service.go): `internal/core/dataquery/service.go`
- [Query language](https://github.com/marmotdata/marmot/blob/main/internal/query/query.go): `internal/query/query.go`

### Runtime and persistence

- [PostgreSQL](https://github.com/marmotdata/marmot/blob/main/internal/store/postgres/setup.go): `internal/store/postgres/setup.go`
- [Identity and access](https://github.com/marmotdata/marmot/blob/main/internal/core/auth/service.go): `internal/core/auth/service.go`

### Other components

- **People**
- **AI agents**

## Connections

- People → Web interface: use
- People → CLI: use
- People → Go SDK: use
- AI agents → MCP server: connect
- Web interface → HTTP API: request
- CLI → HTTP API: request
- Go SDK → HTTP API: request
- MCP server → Catalog search: searches (evidence: `internal/mcp/server.go`)
- MCP server → Lineage: traces (evidence: `internal/mcp/server.go`)
- MCP server → Glossary: looks up (evidence: `internal/mcp/server.go`)
- MCP server → Data products: explores (evidence: `internal/mcp/server.go`)
- MCP server → Governed SQL: queries (evidence: `internal/mcp/server.go`)
- HTTP API → Asset catalog: serves catalog (evidence: `internal/api/v1/server.go`)
- HTTP API → Lineage: serves lineage (evidence: `internal/api/v1/server.go`)
- HTTP API → Glossary: serves glossary (evidence: `internal/api/v1/server.go`)
- HTTP API → Data products: serves products (evidence: `internal/api/v1/server.go`)
- HTTP API → Catalog search: serves search (evidence: `internal/api/v1/server.go`)
- HTTP API → Governed SQL: serves queries (evidence: `internal/api/v1/server.go`)
- Ingest workflow → HTTP API: starts runs (evidence: `internal/cmd/ingest.go`)
- Ingest workflow → Source plugins: runs source (evidence: `internal/cmd/ingest.go`)
- Source plugins → Asset catalog: populate metadata
- Source plugins → Lineage: provide lineage
- HTTP API → PostgreSQL: persists state
- Governed SQL → Identity and access: checks roles
- Governed SQL → PostgreSQL: records audit
- Catalog search → Query language: supports filters
- Plugin updates → Source plugins: switches versions (evidence: `internal/plugin/updates/manager.go`)
- Run operator → PostgreSQL: reconciles run state
- Asset catalog → PostgreSQL: stores assets