Architecture
Service topology and request flow for self-hosted ctx|.
Self-hosted ctx| uses the same product architecture as fully managed ctx|, but the operator owns the runtime, network boundary, secrets, and stateful services. Keep the browser, REST API, auth callbacks, and MCP endpoint on the same public backend origin.
Request flow
- The browser opens your public
AUTH_BASE_URL. - The backend serves API, auth, webhook, and MCP routes from that origin.
- The backend proxies UI requests to the
uiservice. - Auth sessions, repository records, connections, and workflow state live in Postgres.
- Repository ingestion calls
codesearch, which clones repositories and maintains Zoekt indexes. - The worker runs OpenWorkflow jobs for ingestion, connector setup, Confluence sync, and Forge provisioning.
- Extracted claims and relationships are projected into the configured graph database.
- Chat and MCP tools retrieve from Postgres, codesearch, and the graph database before calling your configured model provider.
Services
| Service | Default port | Stateful | Purpose |
|---|---|---|---|
backend | 3000 | No | Public API, auth, MCP, callbacks, UI proxy |
ui | 3002 | No | Product web app, proxied by backend |
worker | internal | No | Background workflows and connector jobs |
codesearch | 3001 | Yes | Repository clone cache and Zoekt index |
postgres | 5432 in container, 5433 on host by default | Yes | Primary relational state |
falkordb | 6379 Redis, 7687 Bolt | Yes | Default graph database |
otel-collector | 4318 | No | Optional OTLP collector for logs, traces, metrics |
Public surface
Expose the backend origin publicly. Keep internal services private unless you have a specific operational need.
| Route or endpoint | Public? | Notes |
|---|---|---|
/ | Yes | Backend proxies UI requests |
/.auth/* | Yes | Better Auth routes and provider callbacks |
/api/v1/* | Yes | REST API and connector callbacks |
/:orgSlug/api/v1/* | Yes | Organization-scoped REST API |
/mcp?orgSlug=... | Yes | Streamable HTTP MCP endpoint |
/.status | Optional | Basic backend status endpoint |
ui:3002 | No | Internal service behind backend |
codesearch:3001 | No | Internal service called by backend and workflows |
postgres, falkordb | No | Stateful infrastructure |
Stateful data
Back up anything you cannot rebuild quickly.
| Data | Location | Recovery note |
|---|---|---|
| App database | Postgres | Required. Contains users, sessions, repositories, connections, workflow state, and encrypted connector metadata. |
| Graph data | FalkorDB or another graph database | Back up for fast recovery. Some graph data may be regenerated by reindexing, but that can be slow and may not cover all operational state. |
| Repository cache | repo_cache volume in Compose | Rebuildable by recloning, but useful to retain. |
| Zoekt index | zoekt_index_deploy volume in Compose | Rebuildable by reindexing, but can be expensive for large repositories. |
| Secrets | Deployment secret store or .env files | Required to decrypt sessions and connector credentials. Protect and version changes carefully. |