Technical Guidebook

Architecture

A high-level map of AverQel's chat, documents, memory, providers, integrations, and security boundaries.

Web and desktop clients

The browser and Electron clients provide the user interface. Electron loads the shared web experience and does not receive provider secrets.

API boundary

The FastAPI service authenticates requests, applies tenant and user authorization, orchestrates work, and exposes health endpoints.

Workers and inference

Celery workers process documents, DeepSpace jobs, MCP work, maintenance, and schedules. The inference service handles local model work.

State and storage

PostgreSQL stores durable state, Redis coordinates queues and events, MinIO stores private objects, and ClamAV scans files before processing.

External providers

OAuth providers, model providers, SearXNG, and approved remote MCP servers are reached by the backend through bounded and policy checked integrations.

How a request moves

The browser or Electron client sends a tenant-authenticated request.
The API loads authorized history, document context, memory, and provider configuration.
The API selects permitted tools and queues background work when the request needs it.
The selected model or remote provider returns data through the backend policy boundary.
The result streams to the client and durable conversation state is persisted.

Runtime boundaries

Client
  -> frontend
  -> api
     -> PostgreSQL and Redis
     -> MinIO and ClamAV
     -> inference and SearXNG
     -> approved external providers
  -> worker, ingestion, MCP, maintenance, and scheduler queues

The production service layout is defined by the checked-in backend Compose files. Optional packages, including the separate LiveKit server materials, are not considered active until their service, configuration, networking, and health checks are deployed explicitly.

Safety boundaries

Authentication, tenant isolation, encrypted secrets, provider policy, approval checks, and MCP authorization remain backend responsibilities. Clients display authorized results and request actions, while the backend makes the final authorization decision immediately before execution.