> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# System Description

> Review the AIvis deployment layers and the security boundaries between application, model, agent, and data services.

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.