System Description | Alephant Documentation

AIvis is deployed as a set of cooperating services with separate boundaries for user access, application control, knowledge indexing, model workloads, agent execution, and durable data.

Application layer

Component	Role
AIvis Web	The Next.js user interface for administrators and users. It should be reached through the public request router.
AIvis API	The FastAPI service that handles authentication context, business logic, administration actions, chat, connectors, and runtime coordination.
Background Workers	Worker services for document synchronization, indexing, scheduled jobs, and other asynchronous work.

The API service is the control boundary for user context. Other services should not infer a user’s authority from prompt text, runtime output, connector metadata, or a client-supplied field.

Model and retrieval layer

Component	Role
Inference Model Server	Serves models used at query time, such as embedding and reranking workloads.
Indexing Model Server	Isolates document embedding and indexing workloads from live query traffic.
OpenSearch	Provides keyword and vector retrieval for AIvis knowledge search.

Separating indexing and query-time model workloads helps prevent large connector backfills from starving live chat and search requests. Production deployments should monitor both queues separately.

Agent execution layer

Component	Role
Agent Runtime	Runs approved agent work inside the deployment boundary.
Tool Bridge	Exposes only authorized AIvis tools to the runtime.
Runtime Gateway	Optional deployment component for routing runtime traffic through a dedicated internal boundary.

The browser should not call the agent runtime directly. AIvis API reconstructs the user, workspace, conversation, and permission context before work is sent to runtime services.

Primary data flows

Flow	Path	Security boundary
User request	Browser → router → AIvis Web/API → model and retrieval services.	Browser traffic terminates at the public router; internal services trust only server-side context.
Connector ingestion	Background Workers → source systems → object storage, Postgres, OpenSearch, and model servers.	Connector credentials should be scoped to approved source content and kept out of user-visible output.
Search and chat	AIvis API → OpenSearch → model services → AIvis API response.	Retrieved context must come from authorized document scopes for the active user or Agent path.
Agent action	AIvis API → Agent Runtime → Tool Bridge → AIvis services or approved integrations.	Runtime output is not authority; AIvis still authorizes tool calls and data access.
Administration	Admin browser → router → AIvis API → configuration stores.	Administrative routes require role checks and should be logged with request IDs.

Trust boundaries

Boundary	Do not trust	Trust only after
Browser to API	Client-provided role, workspace, model, tool, or document claims.	Session validation and server-side authorization.
Connector to index	Source labels, filenames, or metadata as access control.	Explicit AIvis document access configuration and tested group behavior.
Agent runtime to tools	Prompt instructions or generated tool arguments as permission.	Tool allowlist, user context, Agent configuration, and service-side policy checks.
Model provider to response	Model output as a security decision.	Application validation, policy checks, and safe output handling.

Data layer

Component	Role
Postgres	Stores application data, user sessions, configuration, and system state.
Redis	Provides cache, coordination, and performance support.
MinIO or S3	Stores uploaded files and connector objects.
OpenSearch	Stores searchable content and vector data for retrieval.

Infrastructure layer

Nginx or an equivalent request router should be the public entry point. It terminates or forwards TLS, routes traffic to AIvis Web and API services, and keeps internal service ports private.

Internal service ports for Postgres, Redis, OpenSearch, object storage, model servers, workers, and agent runtime services should not be exposed to the public internet. If a managed service requires public endpoints, restrict access by private networking, firewall rules, identity controls, and TLS.

Component replacement

Object storage can be replaced with S3-compatible services. Redis and Postgres can be replaced with managed services when latency, network policy, and backup requirements are met. OpenSearch can run as a local container, a cluster, or a managed service, but replacing it with a different search engine requires development work because retrieval behavior is tightly integrated with AIvis.

Architecture review checklist

Confirm the public router is the only internet-facing component.
Confirm Web, API, workers, model servers, and runtime services use private network paths.
Confirm connector workers can reach only approved SaaS APIs and internal services.
Confirm OpenSearch and object storage are backed up and access-controlled.
Confirm request IDs appear across router, API, worker, runtime, and model-service logs.