# concierge-hq/concierge architecture

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

- Interactive diagram: https://gitdiagram.com/concierge-hq/concierge
- Repository: https://github.com/concierge-hq/concierge

## Overview

Concierge is an SDK for MCP servers and AI applications. Its principal workflow is an agent discovering the tools exposed for the current session, invoking a tool, and progressing through allowed workflow stages; applications can also share session state. The SDK supports alternative tool backends, MCP transports, upstream server proxying, widgets, moderation, and operational telemetry. Edges reflect README-documented behavior or visible source references; implementation details for several documented capabilities were not sampled, so those links are shown only where supported.

Main entry points: [`__init__.py`](https://github.com/concierge-hq/concierge/blob/main/__init__.py) (Concierge SDK), [`backends/base_provider.py`](https://github.com/concierge-hq/concierge/blob/main/backends/base_provider.py) (Tool providers), [`backends/search_backend.py`](https://github.com/concierge-hq/concierge/blob/main/backends/search_backend.py) (Semantic search), [`backends/code_backend.py`](https://github.com/concierge-hq/concierge/blob/main/backends/code_backend.py) (Code backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow control"]
  node_concierge["Concierge SDK<br/>[__init__.py]"]
  node_stages["Workflow stages<br/>[__init__.py]"]
  node_transitions["Stage transitions<br/>[__init__.py]"]
end

subgraph group_tools["Tool serving"]
  node_provider["Tool providers<br/>[base_provider.py]"]
  node_search["Semantic search<br/>[search_backend.py]"]
  node_code["Code backend<br/>[code_backend.py]"]
  node_plan["Plan backend<br/>[plan_backend.py]"]
  node_vanilla["Vanilla backend<br/>[vanilla_backend.py]"]
end

subgraph group_protocol["MCP integration"]
  node_adapters["MCP adapters"]
  node_proxy["Upstream proxy<br/>[proxy.py]"]
  node_transports["MCP transports<br/>[__init__.py]"]
  node_widgets["Widget model<br/>[widget.py]"]
end

subgraph group_runtime["Session runtime"]
  node_state_api["Session state API<br/>[__init__.py]"]
  node_state_store[("State backends")]
  node_moderation["Content moderation<br/>[moderation.py]"]
end

subgraph group_operations["Operations"]
  node_telemetry["Telemetry<br/>[telemetry.py]"]
  node_logging["Structured logging<br/>[logging.py]"]
  node_cli["Scaffolding CLI<br/>[__init__.py]"]
end

node_agent(("AI agent"))
node_developer(("Developer<br/>actor"))

node_agent -->|"uses MCP"| node_concierge
node_concierge -->|"exposes tools by stage"| node_stages
node_concierge -->|"enforces paths"| node_transitions
node_agent -->|"discovers and invokes"| node_concierge
node_concierge -->|"offers state access"| node_state_api
node_state_api -->|"reads and writes"| node_state_store
node_concierge -->|"initializes provider"| node_provider
node_provider -->|"supports search mode"| node_search
node_provider -->|"supports code mode"| node_code
node_provider -->|"supports plan mode"| node_plan
node_provider -->|"supports plain mode"| node_vanilla
node_concierge -->|"configures checks"| node_moderation
node_concierge -->|"wraps MCP servers"| node_adapters
node_concierge -.->|"supports upstream proxying"| node_proxy
node_concierge -->|"serves over transports"| node_transports
node_concierge -.->|"provides widgets"| node_widgets
node_concierge -.->|"records runtime metrics"| node_telemetry
node_concierge -->|"sets request context"| node_logging
node_developer -->|"scaffolds project"| node_cli

click node_concierge "https://github.com/concierge-hq/concierge/blob/main/__init__.py"
click node_stages "https://github.com/concierge-hq/concierge/blob/main/__init__.py"
click node_transitions "https://github.com/concierge-hq/concierge/blob/main/__init__.py"
click node_state_api "https://github.com/concierge-hq/concierge/blob/main/__init__.py"
click node_state_store "https://github.com/concierge-hq/concierge/tree/main/state"
click node_provider "https://github.com/concierge-hq/concierge/blob/main/backends/base_provider.py"
click node_search "https://github.com/concierge-hq/concierge/blob/main/backends/search_backend.py"
click node_code "https://github.com/concierge-hq/concierge/blob/main/backends/code_backend.py"
click node_plan "https://github.com/concierge-hq/concierge/blob/main/backends/plan_backend.py"
click node_vanilla "https://github.com/concierge-hq/concierge/blob/main/backends/vanilla_backend.py"
click node_moderation "https://github.com/concierge-hq/concierge/blob/main/security/moderation.py"
click node_adapters "https://github.com/concierge-hq/concierge/tree/main/adapters"
click node_proxy "https://github.com/concierge-hq/concierge/blob/main/proxy.py"
click node_transports "https://github.com/concierge-hq/concierge/blob/main/__init__.py"
click node_widgets "https://github.com/concierge-hq/concierge/blob/main/core/widget.py"
click node_telemetry "https://github.com/concierge-hq/concierge/blob/main/core/telemetry.py"
click node_logging "https://github.com/concierge-hq/concierge/blob/main/core/logging.py"
click node_cli "https://github.com/concierge-hq/concierge/blob/main/concierge_cli/__init__.py"

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_concierge,node_stages,node_transitions toneBlue
class node_provider,node_search,node_code,node_plan,node_vanilla toneAmber
class node_adapters,node_proxy,node_transports,node_widgets toneMint
class node_state_api,node_state_store,node_moderation toneRose
class node_telemetry,node_logging,node_cli,node_agent,node_developer toneIndigo
```

## Components

### Workflow control

- [Concierge SDK](https://github.com/concierge-hq/concierge/blob/main/__init__.py): `__init__.py`
- [Workflow stages](https://github.com/concierge-hq/concierge/blob/main/__init__.py): `__init__.py`
- [Stage transitions](https://github.com/concierge-hq/concierge/blob/main/__init__.py): `__init__.py`

### Tool serving

- [Tool providers](https://github.com/concierge-hq/concierge/blob/main/backends/base_provider.py): `backends/base_provider.py`
- [Semantic search](https://github.com/concierge-hq/concierge/blob/main/backends/search_backend.py): `backends/search_backend.py`
- [Code backend](https://github.com/concierge-hq/concierge/blob/main/backends/code_backend.py): `backends/code_backend.py`
- [Plan backend](https://github.com/concierge-hq/concierge/blob/main/backends/plan_backend.py): `backends/plan_backend.py`
- [Vanilla backend](https://github.com/concierge-hq/concierge/blob/main/backends/vanilla_backend.py): `backends/vanilla_backend.py`

### MCP integration

- [MCP adapters](https://github.com/concierge-hq/concierge/tree/main/adapters): `adapters`
- [Upstream proxy](https://github.com/concierge-hq/concierge/blob/main/proxy.py): `proxy.py`
- [MCP transports](https://github.com/concierge-hq/concierge/blob/main/__init__.py): `__init__.py`
- [Widget model](https://github.com/concierge-hq/concierge/blob/main/core/widget.py): `core/widget.py`

### Session runtime

- [Session state API](https://github.com/concierge-hq/concierge/blob/main/__init__.py): `__init__.py`
- [State backends](https://github.com/concierge-hq/concierge/tree/main/state): `state`
- [Content moderation](https://github.com/concierge-hq/concierge/blob/main/security/moderation.py): `security/moderation.py`

### Operations

- [Telemetry](https://github.com/concierge-hq/concierge/blob/main/core/telemetry.py): `core/telemetry.py`
- [Structured logging](https://github.com/concierge-hq/concierge/blob/main/core/logging.py): `core/logging.py`
- [Scaffolding CLI](https://github.com/concierge-hq/concierge/blob/main/concierge_cli/__init__.py): `concierge_cli/__init__.py`

### Other components

- **AI agent**
- **Developer**: actor

## Connections

- AI agent → Concierge SDK: uses MCP (evidence: `README.md`)
- Concierge SDK → Workflow stages: exposes tools by stage (evidence: `README.md`)
- Concierge SDK → Stage transitions: enforces paths (evidence: `README.md`)
- AI agent → Concierge SDK: discovers and invokes (evidence: `README.md`)
- Concierge SDK → Session state API: offers state access (evidence: `README.md`)
- Session state API → State backends: reads and writes (evidence: `__init__.py`)
- Concierge SDK → Tool providers: initializes provider (evidence: `__init__.py`)
- Tool providers → Semantic search: supports search mode (evidence: `README.md`)
- Tool providers → Code backend: supports code mode (evidence: `README.md`)
- Tool providers → Plan backend: supports plan mode (evidence: `README.md`)
- Tool providers → Vanilla backend: supports plain mode (evidence: `README.md`)
- Concierge SDK → Content moderation: configures checks (evidence: `__init__.py`)
- Concierge SDK → MCP adapters: wraps MCP servers (evidence: `README.md`)
- Concierge SDK → Upstream proxy: supports upstream proxying
- Concierge SDK → MCP transports: serves over transports (evidence: `README.md`)
- Concierge SDK → Widget model: provides widgets
- Concierge SDK → Telemetry: records runtime metrics
- Concierge SDK → Structured logging: sets request context
- Developer → Scaffolding CLI: scaffolds project (evidence: `README.md`)