Skip to main content
AllCodex is a decoupled, multi-tier system. AllCodex splits concerns into three dedicated services:
  1. AllCodex Portal (Web Frontend)
  2. AllKnower (Semantic Graph Compiler & RAG Engine)
  3. AllCodex Core (Headless Lore Database)

​
Service inventory

​
Communication and data flow

To maintain security, the browser does not communicate directly with the database (Core) or the parsing brain (AllKnower). The Portal acts as a BFF (Backend-for-Frontend) proxy.

​
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 parsing 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 and bootstrap sequence (auto-provisioning)

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

Core startup

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

AllKnower startup

AllKnower checks if a default administrator exists. If not, it creates a default account and records that user as the owner — the single principal authorized to call protected APIs. AllKnower then runs a loopback authentication call to AllCodex Core using the startup password, 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. The middleware calls AllKnower’s internal /internal/auto-provision route using a shared portal secret and retrieves a session token for the bootstrapped default user. It then sets that token as an HTTP-only cookie in the user’s browser./internal/auto-provision is only enabled when NODE_ENV is not production, so it cannot be used to mint sessions against a production deployment.
The result is a zero-click startup experience for single-user, self-hosted deployments.

​
Single-owner authorization model

AllKnower enforces a single-owner model: only the user recorded as the owner during bootstrap can call protected APIs.
  • Authenticated requests from any other user receive 403 Forbidden.
  • Anonymous requests receive 401 Unauthorized.
  • Public sign-up via POST /api/auth/sign-up/email is disabled and returns 403 FORBIDDEN unless the request includes an X-AllCodex-Bootstrap-Secret header matching PORTAL_INTERNAL_SECRET. This header is used internally during bootstrap and is not intended for end-user account creation.
AllCodex is designed for a single self-hosted worldbuilder per deployment. To collaborate on a world, see Sharing lore.