System architecture

SAG separates the product interface, HTTP application, Agent Runtime, and knowledge engine. The central dependency rule is simple: the application reaches zleap-sag through one adapter layer, while the knowledge engine never depends on FastAPI, the Web UI, users, conversations, or citations.

One engine, three entry points

SAG retrieval engine architecture

The product frontend, any custom frontend, and external Agents can all use the same backend independently. A Python service can also bypass the reference application and embed zleap-sag directly.

Repository structure

apps/
├── web/                    Next.js 15 + React 19 product UI
├── desktop/                Electron shell and local sidecar
└── api/
    ├── sag_api/
    │   ├── api/v1/         FastAPI routes and serialization
    │   ├── connectors/     File/web connectors and registry
    │   ├── parsing/        MarkItDown and MinerU normalization
    │   ├── jobs/           ingest -> extract background state machine
    │   ├── sag/            Only application adapter that imports zleap-sag
    │   ├── generation/     Retrieval evidence -> streamed cited answers
    │   ├── mcp/            MCP server and HTTP mount
    │   ├── services/       Application and domain orchestration
    │   └── tools/          Built-in and remote MCP Agent tools
    └── sag_agent/          Framework-independent Agent Runtime Core
skills/sag/                 Agent knowledge-exploration Skill
deploy/                     Database initialization resources
docs/assets/readme/         Product screenshots and architecture diagrams

Backend layers

API routes handle protocol, authentication, and serialization. Services orchestrate application behavior. The sag/ adapter converts application objects into knowledge-engine configuration and DTOs. zleap-sag executes chunk, ingest, extract, and search operations.

This boundary lets you:

• replace the Web or desktop interface while retaining the complete API;
• use only the engine in your own Python service;
• evolve Agent conversations and knowledge retrieval independently;
• keep users, citations, jobs, and security policy in the application layer.

Document-processing path

connector -> parser -> document service -> background job
          -> sag adapter -> DataEngine ingest/extract
          -> relational + vector storage

Uploaded files remain in the application data directory. Parsed Markdown, document state, and jobs belong to the application layer. Chunks, events, entities, and retrieval indexes are managed by the engine.

Answer-generation path

Agent run -> retrieval service -> evidence sections
          -> generation LLM -> SSE output + citations

Citations are assembled in the application layer, but each target comes from a source chunk returned by the engine. Generated text and evidence boundaries therefore remain distinct and explainable.

Desktop boundary

Electron packages the same Next.js workspace and manages a Next.js standalone runtime plus a PyInstaller FastAPI sidecar on the local machine. The database, uploads, indexes, and runtime keys are written to the operating system's userData directory, never the installation directory.

Web, API, and the Python sidecar ship as one release and cannot be upgraded independently.