Architecture

Overview

xbrain runs as 30+ Docker containers on a single VM, connected via a private Docker network (xbrain_net). All external traffic enters through nginx on port 80/443. Internal services never expose ports to the internet.

Since Phase 11 (Brain Monitor + Superadmin Dashboard, 2026-05-17) the stack also includes brain-janitor — a daily cron container that hard-purges soft-deleted entities from Postgres, Qdrant, and Neo4j after the 30-day retention window. Phase 12 introduced the GitHub App auth model (multi-callback + refresh tokens + installation webhooks), replacing the legacy OAuth App + long-lived GITHUB_API_PAT.

The central invariant is memory-api: every data point from every frontend (LibreChat, Open WebUI, Chrome extension, agents) passes through memory-api before persisting. memory-api enforces the 7-field tagging contract and routes data to the right stores: PostgreSQL (event store), Qdrant (vector search), and Neo4j (knowledge graph).

Architecture Diagram

                    ┌─────────────────┐
  Browser ─────────►│  nginx (80/443)  │
                    └────────┬────────┘
                             │
              ┌────────────┼────────────┐
              │              │              │
       ┌──────▼──┐   ┌──────▼──┐   ┌─────▼──────┐
       │ LibreChat │   │Open WebUI│   │ memory-api  │
       └──────┬──┘   └──────┬──┘   └─────┬──────┘
              │              │              │
       ┌─────▼───────────▼──┐   ┌─────▼──────┐
       │  librechat-bridge        │   │ PostgreSQL  │
       │  openwebui-pipeline      │   │ Qdrant      │
       └─────────────────────────┘   │ Neo4j       │
                                      └────────────┘
       ┌──────────────┐   ┌──────────────────────────┐
       │ agent-runtime │   │ MCP Gateway               │
       │ (LangGraph)   │   │ mcp-scraper               │
       └──────┬────────┘   │ mcp-drive-read            │
              │            │ mcp-calendar              │
       ┌─────▼───────┐   │ mcp-deck                  │
       │ graphiti-svc  │   └──────────────────────────┘
       └───────────────┘

       ┌──────────────┐   ┌────────────────────────┐
       │ drive-sync   │   │ Langfuse (observability) │
       └──────────────┘   │ ClickHouse / Redis       │
                          │ MinIO (Chainguard)       │
                          └────────────────────────┘

  All containers: xbrain_net (Docker bridge network)

Container Reference

All 25 containers across Phases 1–5. The Phase column indicates when each container is first introduced. Containers from earlier phases remain active in later phases.

Phase 11 — Brain Monitor + Superadmin Dashboard

Phase 11 (shipped 2026-05-17) extends the universal truth-level + soft-delete contract from memory_items to every brainable entity: conversations, messages, team_messages, tasks, contacts, plus Granola transcripts. Three columns (truth_level, deleted_at, deleted_by) are now mandatory on every entity table.

• Migration 0017_brain_monitor_base patches the 5 missing tables with the columns and per-type backfill defaults (e.g. task → WORKING, contact → VALIDATED).
• Migration 0018_brain_events_view creates the v_brain_events view — a UNION-ALL across the 7 entity types that powers the universal feed at GET /v1/brain/events.
• A new brain-janitor container runs the 30-day hard-purge cron (Postgres first, then Qdrant points, then Neo4j nodes — idempotent).
• Superadmin endpoints (/v1/admin/brain/*) gate behind ADMIN_USER_SUBS with synchronous audit_log writes before any data read. See the Brain Monitor guide.

Phase 12 — GitHub App migration

Phase 12 (shipped 2026-05-17) retired the legacy OAuth App + long-lived GITHUB_API_PAT in favour of a GitHub App. The new model unlocks multi-callback (web + Chrome extension), short-lived installation tokens for org-membership lookups, and user-token refresh (~6 month rolling sessions).

• Server-side: PyJWT[crypto]>=2.10 in memory-api for RS256 signing of the App JWT. Three token types: App JWT (10 min), installation token ghs_ (1h, cached in-process 55 min), user-to-server ghu_ (8h) + ghr_ refresh (6 months).
• Migration 0019_github_app_install adds the installations table and the encrypted token columns on users: github_access_token_enc, github_refresh_token_enc, an HMAC github_access_token_hash for O(log n) Bearer lookup.
• Webhook handler POST /v1/webhooks/github/installation verifies HMAC-SHA256 and upserts on installation.created / deleted / suspend / unsuspend.
• The Chrome extension and the web app share the same GitHub App client ID (Iv23liVnZvIN0Lo6isof) because GitHub Apps support multiple callback URLs natively. See the GitHub Auth guide.

Network Architecture

All containers connect on xbrain_net, a Docker bridge network defined in docker-compose.yml. Container-to-container communication uses service names as hostnames (e.g., http://memory-api:8000).

Exposed ports

Internal-only ports

Data Flow — Chat Message

Here is what happens from the moment a user sends a message in LibreChat to the moment it becomes a searchable memory item:

1. User sends a message in LibreChat.
2. LibreChat saves the message to MongoDB (librechat-mongo) — its own conversation history.
3. librechat-bridge detects the new message via the LibreChat webhook/event.
4. bridge sends POST /v1/messages to memory-api with a Bearer JWT.
5. memory-api enforces the tagging contract — all 7 mandatory fields must be present or the request returns 422.
6. Message is stored in PostgreSQL (event store + audit log) and Qdrant (vector embedding for semantic search).
7. If the message payload includes an entities field, the Neo4j outbox is updated by a background worker.
8. graphiti-service enriches the knowledge graph with temporal facts — this call is fail-soft and async (a graphiti-service outage does not block the memory write).
9. Audit log entry written to PostgreSQL with timestamp, source, and team_scope.

VM Sizing

xbrain's container count grows with each phase. Plan your VM size before deploying a new phase — attempting Phase 2 on a 4 GB VM will cause OOM kills.

See the Deployment guide for detailed instructions on how to resize a GCP VM without data loss.