> ## Documentation Index
> Fetch the complete documentation index at: https://docs.allcodex.allmaker.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# System Architecture

> Deep dive into the three AllCodex services—Portal, AllKnower, and Core—covering ports, stacks, data flow, and the BFF proxy security model.

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

| Service             | Stack                                     | Port   | Primary Responsibility                                                                                                                                         |
| :------------------ | :---------------------------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **AllCodex Portal** | Next.js 16, React 19, Bun, Tailwind CSS 4 | `3000` | The user interface. Serves the grimoire web UI, manages local state, and proxies all API requests server-side.                                                 |
| **AllKnower**       | Elysia, Bun, Prisma (Postgres), LanceDB   | `3001` | The parsing brain. Handles OpenRouter models, stores vector embeddings, manages background dump processing, and hosts analytics.                               |
| **AllCodex Core**   | Node.js, Express 5, SQLite                | `8080` | The database. A customized, headless fork of the Trilium note-taking application. Stores all nodes, attributes, and relations, and renders public share pages. |

***

## 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.

```
  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)
                            ┌───────┴──────────────────────────────┐
                            │       Semantic Graph Compiler        │
                            │                                      │
                            │ 1. Vector Search (LanceDB)           │
                            │ 2. Relational Analytics (PostgreSQL) │
                            │ 3. Semantic Parsing (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 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:

<Steps>
  <Step title="Core startup">
    On startup, AllCodex Core reads the `ALLCODEX_PASSWORD` environment variable and configures its administrator password.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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](/guides/sharing-lore).