# www-zaq-ai/zaq architecture

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

- Interactive diagram: https://gitdiagram.com/www-zaq-ai/zaq
- Repository: https://github.com/www-zaq-ai/zaq

## Overview

ZAQ is a self-hosted platform for configuring AI agents, connecting organizational knowledge and communication channels, and coordinating work in conversations and workflows. Its main user journey is to configure an agent, optionally connect and ingest knowledge, then converse with it in chat or through a channel; workflows add tool steps, conditions, and human approval. The map preserves these product areas and the sampled ingestion, storage, and web entry points. Several internal links are dashed because the relevant implementations were not sampled.

Main entry points: [`lib/zaq/agent/server_manager.ex`](https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/agent/server_manager.ex) (Agent server manager), [`lib/zaq/ingestion/ingest_worker.ex`](https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/ingestion/ingest_worker.ex) (Document ingestion), [`lib/zaq/channels`](https://github.com/www-zaq-ai/zaq/tree/main/lib/zaq/channels) (Channel connectors), [`lib/zaq_web/router.ex`](https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq_web/router.ex) (Web routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and chat"]
  node_router["Web routes<br/>[router.ex]"]
  node_chat["Chat interface"]
  node_ingestion_ui["Knowledge browser"]
end

subgraph group_agents["Agent runtime"]
  node_agent_config["Agent configuration"]
  node_agent_runtime["Agent server manager<br/>[server_manager.ex]"]
  node_agent_tools["Agent tools"]
  node_resource_query["Resource queries<br/>[query.ex]"]
end

subgraph group_knowledge["Knowledge and storage"]
  node_ingestion["Document ingestion<br/>[ingest_worker.ex]"]
  node_chunk_worker["Chunk processing"]
  node_python_pipeline["Document preparation<br/>[pipeline.ex]"]
  node_storage[("Mounted storage<br/>[storage.ex]")]
end

subgraph group_communications["Channels and conversations"]
  node_conversation["Conversation history<br/>[conversations.ex]"]
  node_channel_adapters["Channel connectors"]
  node_channel_http["Channel HTTP client<br/>[http_client.ex]"]
end

subgraph group_coordination["Workflow and administration"]
  node_workflows["Workflow engine"]
  node_accounts["People and access"]
  node_portal["Portal onboarding<br/>[client.ex]"]
end

node_person(("User"))
node_external_model{{"Model provider"}}
node_external_channels{{"Communication services"}}

node_person -->|"uses"| node_router
node_router -.->|"routes to"| node_chat
node_person -->|"configures"| node_agent_config
node_agent_config -.->|"configures"| node_agent_runtime
node_chat -.->|"starts conversation"| node_agent_runtime
node_agent_runtime -.->|"requests completion"| node_external_model
node_agent_runtime -->|"invokes tools"| node_agent_tools
node_agent_tools -.->|"queries resources"| node_resource_query
node_agent_runtime -.->|"records conversation"| node_conversation
node_person -->|"connects channel"| node_channel_adapters
node_channel_adapters -.->|"uses client"| node_channel_http
node_channel_adapters -.->|"exchanges messages"| node_external_channels
node_person -->|"manages knowledge"| node_ingestion_ui
node_ingestion -.->|"prepares documents"| node_python_pipeline
node_ingestion -.->|"schedules chunks"| node_chunk_worker
node_ingestion -->|"materializes records"| node_storage
node_person -->|"authors workflows"| node_workflows
node_workflows -->|"runs agent steps"| node_agent_runtime
node_person -->|"manages access"| node_accounts
node_portal -->|"onboards administrator"| node_accounts

click node_router "https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq_web/router.ex"
click node_chat "https://github.com/www-zaq-ai/zaq/tree/main/lib/zaq_web/chat"
click node_ingestion_ui "https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq_web/components/design_system/ingestion_file_list_view.ex"
click node_agent_config "https://github.com/www-zaq-ai/zaq/tree/main/lib/zaq/agent"
click node_agent_runtime "https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/agent/server_manager.ex"
click node_agent_tools "https://github.com/www-zaq-ai/zaq/tree/main/lib/zaq/agent/tools"
click node_resource_query "https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/agent/tools/resources/query.ex"
click node_conversation "https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/engine/conversations.ex"
click node_channel_adapters "https://github.com/www-zaq-ai/zaq/tree/main/lib/zaq/channels"
click node_channel_http "https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/channels/http_client.ex"
click node_ingestion "https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/ingestion/ingest_worker.ex"
click node_chunk_worker "https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/ingestion/ingest_chunk_worker.ex"
click node_python_pipeline "https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/ingestion/python/pipeline.ex"
click node_storage "https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/storage.ex"
click node_workflows "https://github.com/www-zaq-ai/zaq/tree/main/lib/zaq/engine/workflows"
click node_accounts "https://github.com/www-zaq-ai/zaq/tree/main/lib/zaq/accounts"
click node_portal "https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/user_portal/client.ex"

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_router,node_chat,node_ingestion_ui,node_person toneBlue
class node_agent_config,node_agent_runtime,node_agent_tools,node_resource_query toneAmber
class node_ingestion,node_chunk_worker,node_python_pipeline,node_storage toneMint
class node_conversation,node_channel_adapters,node_channel_http toneRose
class node_workflows,node_accounts,node_portal,node_external_model,node_external_channels toneIndigo
```

## Components

### Web and chat

- [Web routes](https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq_web/router.ex): `lib/zaq_web/router.ex`
- [Chat interface](https://github.com/www-zaq-ai/zaq/tree/main/lib/zaq_web/chat): `lib/zaq_web/chat`
- [Knowledge browser](https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq_web/components/design_system/ingestion_file_list_view.ex): `lib/zaq_web/components/design_system/ingestion_file_list_view.ex`

### Agent runtime

- [Agent configuration](https://github.com/www-zaq-ai/zaq/tree/main/lib/zaq/agent): `lib/zaq/agent`
- [Agent server manager](https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/agent/server_manager.ex): `lib/zaq/agent/server_manager.ex`
- [Agent tools](https://github.com/www-zaq-ai/zaq/tree/main/lib/zaq/agent/tools): `lib/zaq/agent/tools`
- [Resource queries](https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/agent/tools/resources/query.ex): `lib/zaq/agent/tools/resources/query.ex`

### Knowledge and storage

- [Document ingestion](https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/ingestion/ingest_worker.ex): `lib/zaq/ingestion/ingest_worker.ex`
- [Chunk processing](https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/ingestion/ingest_chunk_worker.ex): `lib/zaq/ingestion/ingest_chunk_worker.ex`
- [Document preparation](https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/ingestion/python/pipeline.ex): `lib/zaq/ingestion/python/pipeline.ex`
- [Mounted storage](https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/storage.ex): `lib/zaq/storage.ex`

### Channels and conversations

- [Conversation history](https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/engine/conversations.ex): `lib/zaq/engine/conversations.ex`
- [Channel connectors](https://github.com/www-zaq-ai/zaq/tree/main/lib/zaq/channels): `lib/zaq/channels`
- [Channel HTTP client](https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/channels/http_client.ex): `lib/zaq/channels/http_client.ex`

### Workflow and administration

- [Workflow engine](https://github.com/www-zaq-ai/zaq/tree/main/lib/zaq/engine/workflows): `lib/zaq/engine/workflows`
- [People and access](https://github.com/www-zaq-ai/zaq/tree/main/lib/zaq/accounts): `lib/zaq/accounts`
- [Portal onboarding](https://github.com/www-zaq-ai/zaq/blob/main/lib/zaq/user_portal/client.ex): `lib/zaq/user_portal/client.ex`

### Other components

- **User**
- **Model provider**
- **Communication services**

## Connections

- User → Web routes: uses (evidence: `README.md`)
- Web routes → Chat interface: routes to
- User → Agent configuration: configures (evidence: `README.md`)
- Agent configuration → Agent server manager: configures
- Chat interface → Agent server manager: starts conversation
- Agent server manager → Model provider: requests completion
- Agent server manager → Agent tools: invokes tools (evidence: `README.md`)
- Agent tools → Resource queries: queries resources
- Agent server manager → Conversation history: records conversation
- User → Channel connectors: connects channel (evidence: `README.md`)
- Channel connectors → Channel HTTP client: uses client
- Channel connectors → Communication services: exchanges messages
- User → Knowledge browser: manages knowledge (evidence: `README.md`)
- Document ingestion → Document preparation: prepares documents
- Document ingestion → Chunk processing: schedules chunks
- Document ingestion → Mounted storage: materializes records (evidence: `lib/zaq/ingestion/ingest_worker.ex`)
- User → Workflow engine: authors workflows (evidence: `README.md`)
- Workflow engine → Agent server manager: runs agent steps (evidence: `README.md`)
- User → People and access: manages access (evidence: `README.md`)
- Portal onboarding → People and access: onboards administrator
