How www-zaq-ai/zaq works
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: server_manager.ex Agent server manager · ingest_worker.ex Document ingestion · channels Channel connectors · router.ex Web routes
Components 20
Web and chat
- Web routes
lib/zaq_web/router.ex - Chat interface
lib/zaq_web/chat - Knowledge browser
lib/zaq_web/components/design_system/ingestion_file_list_view.ex
Agent runtime
- Agent configuration
lib/zaq/agent - Agent server manager
lib/zaq/agent/server_manager.ex - Agent tools
lib/zaq/agent/tools - Resource queries
lib/zaq/agent/tools/resources/query.ex
Knowledge and storage
- Document ingestion
lib/zaq/ingestion/ingest_worker.ex - Chunk processing
lib/zaq/ingestion/ingest_chunk_worker.ex - Document preparation
lib/zaq/ingestion/python/pipeline.ex - Mounted storage
lib/zaq/storage.ex
Channels and conversations
- Conversation history
lib/zaq/engine/conversations.ex - Channel connectors
lib/zaq/channels - Channel HTTP client
lib/zaq/channels/http_client.ex
Workflow and administration
- Workflow engine
lib/zaq/engine/workflows - People and access
lib/zaq/accounts - Portal onboarding
lib/zaq/user_portal/client.ex
Other components
- User
- Model provider
- Communication services
Connections 20
- User → Web routes: uses
README.md - Web routes → Chat interface: routes to
- User → Agent configuration: configures
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
README.md - Agent tools → Resource queries: queries resources
- Agent server manager → Conversation history: records conversation
- User → Channel connectors: connects channel
README.md - Channel connectors → Channel HTTP client: uses client
- Channel connectors → Communication services: exchanges messages
- User → Knowledge browser: manages knowledge
README.md - Document ingestion → Document preparation: prepares documents
- Document ingestion → Chunk processing: schedules chunks
- Document ingestion → Mounted storage: materializes records
lib/zaq/ingestion/ingest_worker.ex - User → Workflow engine: authors workflows
README.md - Workflow engine → Agent server manager: runs agent steps
README.md - User → People and access: manages access
README.md - Portal onboarding → People and access: onboards administrator