System description

The Organizational AI Memory product runtime has four application services, a command-line client, and four infrastructure dependencies. It can run on self-managed infrastructure or use compatible managed services. Content comes in through connectors and uploads. Original bytes are stored as immutable revision evidence, and people and AI agents only ever see what they are allowed to see.

This page describes what runs, how the services talk to each other, and where data and authority live. The lifecycle and authorization pages build on it.

System architecture

The two Nginx layers have different jobs. Nginx Proxy Manager owns the public DNS and TLS boundary. The Nginx process in the web container serves the built React and Vite client and routes application traffic to the API or MCP gateway. API and MCP are not exposed directly.

Core components

Application layer

• Edge reverse proxy: Nginx Proxy Manager terminates public TLS and routes the product and identity-provider hostnames into the private deployment network. It is deployment infrastructure, not a product service.
• Web gateway and frontend client: An unprivileged Nginx process serves the built React and Vite application and routes same-origin calls to the API and MCP gateway. The client provides the Assistant, governed Assets, source administration, knowledge graph exploration, and MCP connection setup.
• API server: Spring Boot service handling product business logic, browser sessions, bearer-token requests, the public REST contract, and database migrations.
• Background worker: Spring Boot service polling connectors, leasing ingestion and graph-indexing jobs, parsing and embedding content, and publishing search and graph projections.
• MCP gateway: Stateless Spring Boot resource server allowing AI agents to search Knowledge and retrieve governed Assets. It validates the caller's token and forwards that credential to the API; it has no direct database or object-storage access.
• Command-line client: OAuth-enabled client connecting agents to MCP and validating, publishing, and installing Skill packages.

The API server and background worker share one application and domain model. The domain does not depend on a deployable service or provider integration.

A Knowledge Asset is governed source content used in retrieval. A registry Asset is a separately versioned package, such as a Skill, delivered through the Assets registry.

The documentation portal is a separate Next.js and Fumadocs deployment. It is not part of the product runtime shown above and never reads product databases.

Model and retrieval layer

• Model gateways: Provider-neutral adapters route Assistant chat, graph extraction, keyword planning, and document embeddings to configured AI providers. The shipped adapters support OpenAI-compatible and Anthropic Messages protocols through Spring AI.
• Permission-aware retrieval: The default GraphRAG engine mixes entity, relation, and chunk evidence under a server-owned plan. A separate canonical hybrid engine provides full-text and vector retrieval.

Model output is untrusted. Extraction is validated before publication, and retrieval evidence is authorized before it enters a prompt. Clients cannot pick a retrieval strategy, widen scope, or renumber citations. Reranking ships disabled and requires a named adapter to enable.

Data layer

• Relational database: PostgreSQL 18 is the source of truth for identity, source and Asset ledgers, immutable versions, sealed ACL generations, jobs, publication heads, audit records, vectors, and graph contributions.
• Object storage: MinIO stores original source bytes and Skill packages. The API streams them through authenticated application routes; clients never receive presigned object-store URLs.

Full-text, vector, and graph records are rebuildable projections. If a projection is lost, it is rebuilt from the ledger and the immutable bytes.

Identity and authorization layer

• Identity provider: Keycloak signs in browser users and issues tokens for agents. An external user becomes an actor only through an explicit OIDC issuer/subject binding; directory-managed provisioning (SCIM) runs on its own plane with credentials the product API rejects.
• Relationship authorization store: OpenFGA answers relationship questions for organizations, Knowledge Spaces, Knowledge Assets, and registry Assets under a versioned authorization model.
• Source permission evidence: Permissions captured from the source system form a separate, immutable ceiling on content reads that no admin grant can bypass.

Authorization covers the full model.

How the services talk to each other

• Public traffic first reaches Nginx Proxy Manager. The web container then serves the frontend or routes the request to the API or MCP gateway over the private application network.
• Browsers authenticate through the API's confidential OIDC flow against Keycloak and hold an HttpOnly session cookie — never a token.
• AI agents and the CLI reach the MCP gateway through the same trusted ingress boundary. MCP validates audience and scope, applies rate limits, exchanges the caller token for the API audience, and calls the API.
• Both paths converge on one canonical actor. The API derives identity, organization, and department server-side; token roles, email, and display attributes are never authorization inputs.
• Only the API and worker open database connections. The worker validates the schema and never runs migrations.

Component replacements

• Model providers, object storage, connectors, observability, and sidecar decoding are ports — adapters can be swapped without touching the domain.
• OpenSearch and Neo4j adapters exist for the graph and search projections but are not part of the default deployment.
• The PostgreSQL ledger is not replaceable. It is the evidence authority that every projection rebuilds from, and exact Asset releases are immutable by database constraint.
• Replacing an adapter never moves authorization into it. Adapters return candidates; the application always performs the final recheck.

Continue with Ingestion lifecycle, Authorization, or Secure retrieval and GraphRAG.