# datagallery-ai/dataagent architecture

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

## Overview

DataFoundry is an enterprise data-agent workbench: a user submits an analysis question, the API assembles a governed agent run, and streamed events and outputs become inspectable, replayable results. The Web workbench is the documented primary entry point; the TUI is an alternate client. Major supporting capabilities include semantic context, multi-source read-only data access, knowledge retrieval, reusable artifacts, and optional DataLink graph grounding. Edges reflect shown imports/calls or README statements; DataLink’s MCP connection and some unsampled subsystem wiring are documented at a high level only.

Main entry points: [`apps/api/src/server.ts`](https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/api/src/server.ts) (API server), [`packages/agent-runtime/src/capabilities/action-router.ts`](https://github.com/datagallery-ai/dataagent/blob/datafoundry/packages/agent-runtime/src/capabilities/action-router.ts) (Agent actions), [`apps/api/src/run-event-pipeline.ts`](https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/api/src/run-event-pipeline.ts) (Event pipeline), [`apps/web/src/app/data-tasks/data-tasks-app.tsx`](https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/web/src/app/data-tasks/data-tasks-app.tsx) (Web workbench)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User workbenches"]
  node_web["Web workbench<br/>[data-tasks-app.tsx]"]
  node_tui["Terminal client<br/>[App.tsx]"]
  node_trace["Trace console<br/>[TraceDagCanvas.tsx]"]
end

subgraph group_api["API and runs"]
  node_api["API server<br/>[server.ts]"]
  node_auth["Authentication<br/>[routes.ts]"]
  node_runconfig["Run configuration"]
  node_assembly["Run assembly"]
  node_events["Event pipeline"]
  node_memory["Conversation memory"]
end

subgraph group_runtime["Agent runtime"]
  node_runtime["Agent actions<br/>[action-router.ts]"]
  node_context["Context assembly"]
  node_protocol["Protocol routing<br/>[protocol-router.ts]"]
  node_tools["Governed tools"]
end

subgraph group_data["Data and knowledge"]
  node_gateway["Datasource adapters"]
  node_knowledge["Knowledge retrieval<br/>[retriever.ts]"]
  node_metadata[("Run persistence<br/>[config-store.ts]")]
  node_artifacts["Session outputs"]
end

subgraph group_datalink["Semantic graph"]
  node_datalink["DataLink service<br/>[server.py]"]
  node_buildgraph["Graph build pipeline<br/>[pipeline.py]"]
  node_graphstore[("Graph storage<br/>[storage.py]")]
  node_retrieval["Graph retrieval<br/>[retrieval.py]"]
  node_mcp["MCP interface<br/>[server.py]"]
end

node_analyst(("Analyst"))

node_analyst -->|"asks question"| node_web
node_web -->|"submits run"| node_api
node_tui -.->|"calls API"| node_api
node_api -->|"routes auth"| node_auth
node_api -->|"resolves config"| node_runconfig
node_api -->|"assembles run"| node_assembly
node_api -->|"persists message"| node_memory
node_assembly -.->|"configures actions"| node_runtime
node_runtime -.->|"uses context"| node_context
node_runtime -.->|"routes protocol"| node_protocol
node_runtime -.->|"dispatches tools"| node_tools
node_tools -.->|"queries sources"| node_gateway
node_context -.->|"retrieves knowledge"| node_knowledge
node_api -->|"creates writer"| node_events
node_events -->|"writes events"| node_metadata
node_events -->|"observes events"| node_memory
node_events -.->|"projects trace"| node_trace
node_runtime -->|"ingests outputs"| node_artifacts
node_web -->|"renders trace"| node_trace
node_analyst -.->|"configures semantics"| node_datalink
node_datalink -->|"runs build"| node_buildgraph
node_buildgraph -->|"stores graph"| node_graphstore
node_mcp -->|"queries graph"| node_retrieval
node_retrieval -.->|"reads graph"| node_graphstore
node_runtime -.->|"uses optional MCP"| node_mcp

click node_web "https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/web/src/app/data-tasks/data-tasks-app.tsx"
click node_tui "https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/tui/src/ui/App.tsx"
click node_api "https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/api/src/server.ts"
click node_auth "https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/api/src/auth/routes.ts"
click node_runconfig "https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/api/src/run-config-resolver.ts"
click node_assembly "https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/api/src/run-agent-assembly.ts"
click node_events "https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/api/src/run-event-pipeline.ts"
click node_memory "https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/api/src/conversation-memory.ts"
click node_runtime "https://github.com/datagallery-ai/dataagent/blob/datafoundry/packages/agent-runtime/src/capabilities/action-router.ts"
click node_context "https://github.com/datagallery-ai/dataagent/blob/datafoundry/packages/agent-runtime/src/context/inventory/context-package-builder.ts"
click node_protocol "https://github.com/datagallery-ai/dataagent/blob/datafoundry/packages/agent-runtime/src/protocol/protocol-router.ts"
click node_tools "https://github.com/datagallery-ai/dataagent/blob/datafoundry/packages/agent-runtime/src/tools/governed-tool-factory.ts"
click node_gateway "https://github.com/datagallery-ai/dataagent/blob/datafoundry/packages/data-gateway/src/adapter-registry.ts"
click node_knowledge "https://github.com/datagallery-ai/dataagent/blob/datafoundry/packages/knowledge/src/retriever.ts"
click node_metadata "https://github.com/datagallery-ai/dataagent/blob/datafoundry/packages/metadata/src/config-store.ts"
click node_artifacts "https://github.com/datagallery-ai/dataagent/blob/datafoundry/packages/artifacts/src/session-output-service.ts"
click node_trace "https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/web/src/app/data-tasks/components/task-console/TraceDagCanvas.tsx"
click node_datalink "https://github.com/datagallery-ai/dataagent/blob/datafoundry/services/datalink/src/datalink/api/server.py"
click node_buildgraph "https://github.com/datagallery-ai/dataagent/blob/datafoundry/services/datalink/src/datalink/builder/pipeline.py"
click node_graphstore "https://github.com/datagallery-ai/dataagent/blob/datafoundry/services/datalink/src/datalink/graph/storage.py"
click node_retrieval "https://github.com/datagallery-ai/dataagent/blob/datafoundry/services/datalink/src/datalink/graph/retrieval.py"
click node_mcp "https://github.com/datagallery-ai/dataagent/blob/datafoundry/services/datalink/src/datalink/mcp/server.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_web,node_tui,node_trace toneBlue
class node_api,node_auth,node_runconfig,node_assembly,node_events,node_memory toneAmber
class node_runtime,node_context,node_protocol,node_tools toneMint
class node_gateway,node_knowledge,node_metadata,node_artifacts toneRose
class node_datalink,node_buildgraph,node_graphstore,node_retrieval,node_mcp,node_analyst toneIndigo
```

## Components

### User workbenches

- [Web workbench](https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/web/src/app/data-tasks/data-tasks-app.tsx): `apps/web/src/app/data-tasks/data-tasks-app.tsx`
- [Terminal client](https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/tui/src/ui/App.tsx): `apps/tui/src/ui/App.tsx`
- [Trace console](https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/web/src/app/data-tasks/components/task-console/TraceDagCanvas.tsx): `apps/web/src/app/data-tasks/components/task-console/TraceDagCanvas.tsx`

### API and runs

- [API server](https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/api/src/server.ts): `apps/api/src/server.ts`
- [Authentication](https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/api/src/auth/routes.ts): `apps/api/src/auth/routes.ts`
- [Run configuration](https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/api/src/run-config-resolver.ts): `apps/api/src/run-config-resolver.ts`
- [Run assembly](https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/api/src/run-agent-assembly.ts): `apps/api/src/run-agent-assembly.ts`
- [Event pipeline](https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/api/src/run-event-pipeline.ts): `apps/api/src/run-event-pipeline.ts`
- [Conversation memory](https://github.com/datagallery-ai/dataagent/blob/datafoundry/apps/api/src/conversation-memory.ts): `apps/api/src/conversation-memory.ts`

### Agent runtime

- [Agent actions](https://github.com/datagallery-ai/dataagent/blob/datafoundry/packages/agent-runtime/src/capabilities/action-router.ts): `packages/agent-runtime/src/capabilities/action-router.ts`
- [Context assembly](https://github.com/datagallery-ai/dataagent/blob/datafoundry/packages/agent-runtime/src/context/inventory/context-package-builder.ts): `packages/agent-runtime/src/context/inventory/context-package-builder.ts`
- [Protocol routing](https://github.com/datagallery-ai/dataagent/blob/datafoundry/packages/agent-runtime/src/protocol/protocol-router.ts): `packages/agent-runtime/src/protocol/protocol-router.ts`
- [Governed tools](https://github.com/datagallery-ai/dataagent/blob/datafoundry/packages/agent-runtime/src/tools/governed-tool-factory.ts): `packages/agent-runtime/src/tools/governed-tool-factory.ts`

### Data and knowledge

- [Datasource adapters](https://github.com/datagallery-ai/dataagent/blob/datafoundry/packages/data-gateway/src/adapter-registry.ts): `packages/data-gateway/src/adapter-registry.ts`
- [Knowledge retrieval](https://github.com/datagallery-ai/dataagent/blob/datafoundry/packages/knowledge/src/retriever.ts): `packages/knowledge/src/retriever.ts`
- [Run persistence](https://github.com/datagallery-ai/dataagent/blob/datafoundry/packages/metadata/src/config-store.ts): `packages/metadata/src/config-store.ts`
- [Session outputs](https://github.com/datagallery-ai/dataagent/blob/datafoundry/packages/artifacts/src/session-output-service.ts): `packages/artifacts/src/session-output-service.ts`

### Semantic graph

- [DataLink service](https://github.com/datagallery-ai/dataagent/blob/datafoundry/services/datalink/src/datalink/api/server.py): `services/datalink/src/datalink/api/server.py`
- [Graph build pipeline](https://github.com/datagallery-ai/dataagent/blob/datafoundry/services/datalink/src/datalink/builder/pipeline.py): `services/datalink/src/datalink/builder/pipeline.py`
- [Graph storage](https://github.com/datagallery-ai/dataagent/blob/datafoundry/services/datalink/src/datalink/graph/storage.py): `services/datalink/src/datalink/graph/storage.py`
- [Graph retrieval](https://github.com/datagallery-ai/dataagent/blob/datafoundry/services/datalink/src/datalink/graph/retrieval.py): `services/datalink/src/datalink/graph/retrieval.py`
- [MCP interface](https://github.com/datagallery-ai/dataagent/blob/datafoundry/services/datalink/src/datalink/mcp/server.py): `services/datalink/src/datalink/mcp/server.py`

### Other components

- **Analyst**

## Connections

- Analyst → Web workbench: asks question (evidence: `README.md`)
- Web workbench → API server: submits run (evidence: `README.md`)
- Terminal client → API server: calls API
- API server → Authentication: routes auth (evidence: `apps/api/src/server.ts`)
- API server → Run configuration: resolves config (evidence: `apps/api/src/server.ts`)
- API server → Run assembly: assembles run (evidence: `apps/api/src/server.ts`)
- API server → Conversation memory: persists message (evidence: `apps/api/src/server.ts`)
- Run assembly → Agent actions: configures actions
- Agent actions → Context assembly: uses context
- Agent actions → Protocol routing: routes protocol
- Agent actions → Governed tools: dispatches tools
- Governed tools → Datasource adapters: queries sources
- Context assembly → Knowledge retrieval: retrieves knowledge
- API server → Event pipeline: creates writer (evidence: `apps/api/src/server.ts`)
- Event pipeline → Run persistence: writes events (evidence: `apps/api/src/run-event-pipeline.ts`)
- Event pipeline → Conversation memory: observes events (evidence: `apps/api/src/run-event-pipeline.ts`)
- Event pipeline → Trace console: projects trace
- Agent actions → Session outputs: ingests outputs
- Web workbench → Trace console: renders trace (evidence: `apps/web/src/app/data-tasks/data-tasks-app.tsx`)
- Analyst → DataLink service: configures semantics (evidence: `README.md`)
- DataLink service → Graph build pipeline: runs build (evidence: `services/datalink/src/datalink/api/server.py`)
- Graph build pipeline → Graph storage: stores graph (evidence: `services/datalink/src/datalink/builder/pipeline.py`)
- MCP interface → Graph retrieval: queries graph (evidence: `services/datalink/src/datalink/mcp/server.py`)
- Graph retrieval → Graph storage: reads graph
- Agent actions → MCP interface: uses optional MCP (evidence: `README.md`)