Skip to main content
AllCodex is designed from the ground up as a decoupled, multi-tier system. Instead of running a single monolithic application, AllCodex splits concerns into three dedicated services:
  1. AllCodex Portal (Web Frontend)
  2. AllKnower (AI Orchestrator & RAG Engine)
  3. AllCodex Core (Headless Lore Database)

​
Service Inventory

ServiceStackPortPrimary Responsibility
AllCodex PortalNext.js 16, React 19, Bun, Tailwind CSS 43000The user interface. Serves the grimoire web UI, manages local state, and proxies all API requests server-side.
AllKnowerElysia, Bun, Prisma (Postgres), LanceDB3001The AI brain. Handles OpenRouter models, stores vector embeddings, manages background dump processing, and hosts analytics.
AllCodex CoreNode.js, Express 5, SQLite8080The database. A customized, headless fork of the Trilium note-taking application. Stores all nodes, attributes, and relations, and renders public share pages.

​
Communication & Data Flow

To ensure high security, the browser never communicates directly with the database (Core) or the AI brain (AllKnower). The Portal acts as a strict BFF (Backend-for-Frontend) proxy. 
  Browser (Client)
         │
         │ (HTTP requests with HTTP-only session cookie)
         ▼
  AllCodex Portal (:3000)
   ┌─────┴──────────────────────────────────┐
   │ Next.js API Routes (Server-Side)       │
   └─────┬──────────────────────────┬───────┘
         │                          │
         │ (Private REST /etapi)    │ (Elysia REST API with Bearer token)
         ▼                          ▼
  AllCodex Core (:8080)     AllKnower (:3001)
                            ┌───────┴──────────────────────────────┐
                            │ AI Orchestrator                      │
                            │                                      │
                            │ 1. Vector Search (LanceDB)           │
                            │ 2. Relational Analytics (PostgreSQL) │
                            │ 3. LLM Queries (OpenRouter)          │
                            └───────┬──────────────────────────────┘
                                    │
                                    │ (Calls ETAPI to write extracted lore)
                                    ▼
                             AllCodex Core (:8080)

​
Security Boundary

  1. No Client Tokens: AllCodex Core external API (ETAPI) tokens and AllKnower authorization Bearer tokens are kept strictly server-side.
  2. HTTP-only Cookies: The Portal resolves user sessions from HTTP-only cookies (allknower_token and allknower_url). Browser-based JavaScript cannot read these cookies, eliminating token theft vectors.
  3. Unidirectional Database Writes:
    • The user writes directly to Core via Portal proxy (when editing notes manually).
    • The user triggers AI jobs (like Brain Dump) via Portal. AllKnower computes the changes and writes them to Core via the secure Core ETAPI interface.
    • Core never makes outbound calls to AllKnower or the Portal.

​
Auth & Bootstrap Sequence (Auto-Provisioning)

To make self-hosting painless, AllCodex includes a zero-login bootstrap chain:
1

Core Startup

On startup, AllCodex Core reads the ALLCODEX_PASSWORD environment variable and auto-configures its administrator password.
2

AllKnower Startup

AllKnower checks if a default administrator exists. If not, it creates a default account and runs a loopback authentication call to AllCodex Core using the startup password. It then generates an ETAPI token and stores it as an encrypted UserIntegration record in its Postgres database.
3

Portal Intercept

When a browser first visits the Portal, Next.js middleware detects that the allknower_token cookie is missing. It calls AllKnower’s internal /internal/auto-provision route using a shared portal secret, retrieves a session token for the bootstrapped default user, and sets it as an HTTP-only cookie in the user’s browser.
The result is a zero-click startup experience in developer/single-user setups, while full authentication gates remain active for multi-user TTRPG groups.