How zleap-ai/sag works
1. Overall shape
- SAG is a TypeScript monorepo with three runtime surfaces: a Fastify HTTP API, a stdio MCP server, and a React/Vite WebUI.
- The backend is organized as layered services over a PostgreSQL data model, with AI provider calls abstracted behind small client modules.
2. Primary user-facing flow
- The WebUI is the main entry point for creating projects, uploading documents, chatting, and inspecting traces/graphs.
- UI actions call the HTTP API, which routes into service modules; the same services are reused by the MCP server so external agents and the UI see the same project state.
3. Document ingestion pipeline
- Uploaded Markdown/TXT documents go through ingestion-service.
- The pipeline performs chunking, event extraction, entity extraction, and embedding generation.
- Results are stored in PostgreSQL through repository modules, creating the project’s searchable knowledge base.
4. SAG retrieval pipeline
- Search is centered on the SAG structure: chunk -> event, chunk -> entities, and event <-> entities.
- search-service orchestrates retrieval, using project-scoped data and multi-hop expansion over stored relations rather than relying on vector search alone.
- The returned result includes citations and, when requested, an execution trace for debugging.
5. Two search modes
- Fast mode uses entity/full-text matching, multi-hop expansion, and reranking without an LLM query-analysis step.
- Standard mode adds LLM-based query entity extraction before retrieval and reranking.
- This is an important architectural boundary because the search path can be either low-latency or higher-precision.
6. AI provider abstraction
- embedding-client, llm-client, and rerank-client isolate all model-provider interactions.
- The system supports OpenAI-compatible endpoints and has local deterministic fallback behavior when keys are absent.
- This separation keeps retrieval logic independent from any single provider.
7. Database as the core system of record
- PostgreSQL is the persistence layer for projects, documents, chunks, events, entities, embeddings, conversations, settings, and search-related metadata.
- pgvector is used for embeddings, and migrations also add full-text search and schema constraints.
- Repository modules form the boundary between SQL and application services.
8. Project isolation
- Most functionality is project-scoped: documents, conversations, graphs, MCP config, and search all bind to a project/source ID.
- That means the architecture is multi-tenant at the logical level, even though it runs as a single local service.
9. Knowledge graph and exploration
- graph-service exposes the event/entity relationship structure for visualization in the WebUI.
- The graph is not a separate graph database; it is derived from the relational/embedded document model in PostgreSQL.
- The UI graph component consumes this project graph to support expand, inspect, and detail workflows.
10. MCP integration
- The mcp subsystem turns SAG into an MCP server for external agents.
- It exposes tool operations such as ingest, search, explain search, and fetch event details.
- The MCP server reuses the same backend services, so agent access and WebUI access share the same retrieval and storage logic.
11. Observability and inspection
- The repo includes explicit observability support for logger output and raw model-call logs.
- These logs are surfaced in the workbench so users can inspect LLM/embedding/rerank inputs and outputs alongside search traces.
- This is part of the product architecture, not just dev logging.
12. Configuration and environment
- src/config/env.ts centralizes runtime configuration from .env.
- Important config dimensions are database connectivity, HTTP ports, search mode defaults, and model provider endpoints/keys.
- The repository ships Docker Compose and migration scripts, indicating that local deployment depends on bringing up PostgreSQL plus schema initialization.
13. Codebase boundaries
- services/ contains business workflows.
- ingestion/ contains document processing primitives.
- ai/ contains external model adapters.
- db/ contains schema, pools, migrations, and repositories.
- api/ and mcp/ are the two transport layers.
- web/ is a separate frontend application that consumes the API.
14. What an architecture diagram should emphasize
- Show the WebUI, HTTP API, and MCP server as separate entry points into the same backend services.
- Show PostgreSQL/pgvector as the central persistence and retrieval store.
- Show ingestion as a write pipeline into chunks/events/entities/embeddings.
- Show search as a read pipeline that combines SQL expansion, vector/full-text retrieval, and reranking.
- Show AI providers as external dependencies behind adapter clients.
Main entry points: server.ts HTTP API · env.ts Env config · ingestion-service.ts Ingestion service · search-service.ts Search service
Components 21
WebUI
React/Vite client for projects, uploads, chat, traces, and graph exploration.
- App shell · Main WebUI entry for project workflows and inspection.
web/src/App.tsx - Graph view · Project graph visualization and expand/inspect interactions.
web/src/components/ProjectGraphFlow.tsx - API client · Browser-side transport for calling the backend API.
web/src/lib/api.ts
Runtime entrypoints
HTTP and MCP surfaces that enter the shared backend services.
- HTTP API · Fastify surface for UI-driven project, ingestion, and search operations.
src/api/server.ts - MCP server · StdIO MCP entrypoint for external agents and tools.
src/mcp/server.ts
Backend services
Project-scoped application workflows for ingestion, search, graphing, settings, and MCP support.
- UI service · Backend workflow facade for WebUI project actions and shared state.
src/services/webui-service.ts - Ingestion service · Coordinates document ingest from parsing through storage.
src/services/ingestion-service.ts - Search service · Orchestrates fast and standard SAG retrieval, expansion, reranking, and citations.
src/services/search-service.ts - Graph service · Builds project-scoped event/entity graphs for visualization.
src/services/graph-service.ts - MCP tools · Exposes ingest, search, explain, and detail tools over MCP.
src/services/mcp-agent-service.ts
Ingestion pipeline
Document processing stages that turn uploaded text into searchable knowledge.
- Chunking · Splits markdown/TXT content into searchable chunks.
src/ingestion/chunking/markdown.ts - Extraction · Extracts events and entities from chunks.
src/ingestion/extract/extractor.ts
AI adapters
Provider-facing clients for embeddings, LLM calls, and reranking with local fallback behavior.
- Embeddings · Embedding adapter with provider and local fallback behavior.
src/ai/embedding-client.ts - LLM client · Query analysis and model-call adapter for provider-backed or local execution.
src/ai/llm-client.ts - Rerank client · Reranking adapter used after initial retrieval.
src/ai/rerank-client.ts
Persistence
PostgreSQL boundary, vector support, repositories, migrations, and runtime config.
- Repositories · Project-scoped SQL boundary for documents, chunks, events, entities, conversations, and settings.
src/db/repositories.ts - DB pool · PostgreSQL connection and vector support boundary.
src/db/pool.ts - Vector SQL · Embedding/vector helpers and retrieval primitives.
src/db/vector.ts - Env config · Centralized runtime configuration for ports, DB, search mode, and provider endpoints.
src/config/env.ts
Observability
Logging and model-call inspection surfaced through the workbench.
- Logger · Structured application logging.
src/observability/logger.ts - Model logs · Raw model-call logging for inspection in the workbench.
src/observability/model-call-log.ts
Connections 33
- App shell → API client: uses · UI actions call the browser API layer.
- App shell → Graph view: renders · The app includes the project graph exploration view.
- API client → HTTP API: calls · Frontend requests enter through the HTTP API.
- HTTP API → UI service: routes to · HTTP handlers delegate shared project workflows.
- HTTP API → Ingestion service: ingest · API-triggered uploads enter the ingest pipeline.
- HTTP API → Search service: search · API search requests use the shared retrieval service.
- HTTP API → Graph service: graph · Graph inspection is served from the project graph service.
- MCP server → MCP tools: tools · MCP requests are translated into tool operations.
- MCP tools → Ingestion service: ingest · Agent tools reuse the same ingestion workflow.
- MCP tools → Search service: search · Agent search uses the shared retrieval pipeline.
- MCP tools → Graph service: inspect · Agent graph/detail tools reuse project graph access.
- Ingestion service → Chunking: chunks · Documents are split into chunks before extraction.
- Ingestion service → Extraction: extracts · Ingestion derives events and entities from chunks.
- Ingestion service → Embeddings: embeds · Chunks and related content receive embeddings.
- Ingestion service → Repositories: stores · Processed knowledge is persisted through repositories.
- Search service → Repositories: reads · Search starts from project-scoped relational data.
- Search service → LLM client: standard mode · Standard search extracts query entities before retrieval.
- Search service → Rerank client: reranks · Retrieved candidates are reranked before response.
- Search service → Embeddings: matches · Vector similarity supports retrieval when available.
- Graph service → Repositories: builds from · Graph views are derived from stored events and entities.
- Repositories → DB pool: executes on · Repositories run SQL against PostgreSQL.
- Repositories → Vector SQL: vector ops · Embedding and similarity helpers support retrieval.
- Env config → HTTP API: configures · Environment settings control runtime ports and defaults.
- Env config → MCP server: configures · Environment settings control MCP behavior and endpoints.
- Env config → DB pool: connects · Database connection details come from env configuration.
- Env config → Embeddings: providers · Model provider endpoints and keys configure AI adapters.
- Env config → LLM client: providers · Model provider endpoints and keys configure AI adapters.
- Env config → Rerank client: providers · Model provider endpoints and keys configure AI adapters.
- Embeddings → Model logs: logs · Embedding requests and responses are captured for inspection.
- LLM client → Model logs: logs · LLM prompts and outputs are captured for inspection.
- Rerank client → Model logs: logs · Rerank inputs and outputs are captured for inspection.
- Logger → HTTP API: observes · Server activity is emitted through structured logs.
- Logger → MCP server: observes · MCP activity is emitted through structured logs.