# Context Engine — Architecture
> Single-page system overview. For detailed specs see [`spec.md`](spec.md) and [`docs/`](docs/README.md).
## Deployment Profiles

App hosting, public/private session access, and session infrastructure are
separate choices. A publicly hosted web app can open either a private
worker-canonical session or a public decentralized session. [Session
Infrastructure Profiles](docs/run-modes.md#session-infrastructure-profiles)
describes each profile, what it needs, and who can read its data. The diagrams
below show how their parts connect.
### Implemented Profiles
```mermaid
flowchart LR
Creator["Session creator"] --> Choice{"/new: Runs on"}
Choice --> Hosted["Session Worker: Hosted & Fast
where /new starts"]
Choice --> Trustless["On-chain registry: Trustless & Slower
implemented opt-in"]
Hosted --> DeployHelper["Deploy helper
request-only Cloudflare API token"]
Hosted --> NativeDeploy["Native Deploy to Cloudflare
token-free dashboard handoff"]
DeployHelper --> Worker["Creator-owned per-session Worker
worker_canonical authority"]
NativeDeploy --> Worker
Worker --> Cloudflare["Worker KV / Cloudflare payload storage
public results by default; worker_envelope optional"]
Worker --> AI["Selected AI provider"]
Passkey["Passkey-derived EOA
signing/admin identity"] --> Worker
Trustless --> EVM["Public EVM registry/contracts
wallet transaction + gas"]
Trustless --> Arweave["Arweave metadata and payloads"]
Trustless --> WorkerServices["Session worker services
AI, auth, fetch, profile-enabled routes"]
Trustless -.->|Lit encryption selected| Lit["Lit Protocol"]
```
### Company-Operated (planned)
```mermaid
flowchart LR
Clients["Web app, participants, and agents"] --> Boundary["Planned organization adapter boundary"]
Boundary --> IAM["Identity / IAM"]
Boundary --> Keys["KMS or key release"]
Boundary --> Storage["Organization storage"]
Boundary --> AIGateway["AI gateway"]
Boundary --> Network["Internal networking"]
Boundary --> Observability["Observability"]
Boundary -.->|possible future optional adapter| PrivateEVM["Private EVM"]
```
## Layer Descriptions
| Layer | What it does | Profile role | Primary location |
|-------|-------------|--------------|-----------------|
| **Client** | React SPA: survey authoring, response collection, SBT management, encryption gates, admin, session wizard | Shared across implemented profiles | `client/src/` |
| **Session Worker** | Auth, canonical config, AI proxy, transcription, storage routes, controlled URL/image fetch, and profile-enabled chain/Arweave helpers | Canonical authority for Hosted & Fast; service boundary for decentralized/custom profiles | `workers/sessionCorsWorker/` |
| **Agent HTTP** | Scoped `/api/agent/*` routes, submission queue, Session Wrapped, and atomically coordinated one-time invite exchange | Integrated domain modules using canonical Session Worker authority | `workers/sessionCorsWorker/agent/` |
| **Cloudflare storage** | Worker KV config, secrets, payloads and indexes (Worker-encrypted when selected), and optional advanced R2 blobs | Hosted & Fast default | Worker bindings (external) |
| **Contracts** | Session registry, surveys, SBTs, gates, and factory on supported EVM chains | Trustless & Slower and explicit chain-backed custom profiles | `contracts/` |
| **Arweave** | Immutable metadata, survey/question payloads, SBT tokenURI, and document-library files | Trustless & Slower and explicit Arweave-backed custom profiles | External |
| **Lit Protocol (Chipotle)** | Wraps and releases content keys behind SBT gates; the browser encrypts content locally and the session Worker calls a registered Lit Action | Optional when Lit encryption is selected | Lit Chipotle API via the Session Worker |
| **Organization adapters** | IAM, key release/KMS, storage, AI, networking, and observability | Planned Company-Operated profile; not shipped | Future adapter boundary |
## Data Flows
### 1. Session Creation (`/new`, canonicalized to `/session/new`)
Hosted & Fast:
```text
Wizard UI ──▸ Sign in with a passkey to confirm Create
──▸ Deploy the per-session Worker, KV, Durable Object, and runtime secrets: through the deploy helper with a request-only Cloudflare API token, or from the immutable native Deploy to Cloudflare template in the dashboard
──▸ Persist and read back admin-signed canonical Worker config
──▸ Return reload-safe session/admin URLs with the public Worker URL
No Arweave upload, registry write, RPC call, gas payment, or EVM transaction.
```
Trustless & Slower:
```text
Wizard UI ──▸ Configure profile-enabled session Worker services
──▸ Upload metadata JSON to Arweave (optionally Lit-encrypted)
──▸ SessionRegistry.createSession(slug, sessionId, chainId, metadataURI, encryptedMetadataURI), paying the creation fee
──▸ SessionRegistry.setSessionFields(slug, [corsWorkerUrl, sponsored_*])
──▸ SessionRegistry.setResourceGates(slug, gates[])
```
Sponsored bootstrap deploys run on the sponsoring `sessionCorsWorker`. They do
not fall back to the standalone deploy helper; a Worker with embedded deploy
disabled refuses the grant.
```
Browser ──▸ source sessionCorsWorker /sponsored/redeem-deploy
──▸ embedded deploy-helper core inside source worker
```
### 2. Survey Response
```text
User submits ──▸ Store the payload through the profile-selected backend
├─ Hosted & Fast: Cloudflare storage, worker-envelope when selected
└─ Trustless & Slower: Arweave, with Lit only when selected
Chain-backed sessions then anchor the response hashes with a wallet transaction
to Surveys.submitResponses(...). Worker-canonical sessions send no transaction.
```
### 3. SBT Mint (chain-backed profiles)
```
User claims ──▸ CustomSBT.claim() / .startClaim() + .claimWithPassword() /
.mintWithGroupSignature() / .claimWithInvite()
Collection metadata is stored on Arweave; SBTFactory sets its tokenURI on creation.
```
### 4. Gate Check (Worker Login)
```text
Client ──▸ POST /auth/nonce { address, sessionSlug }
──▸ Sign the worker login message
──▸ POST /auth/login { address, message, signature, sessionSlug }
Hosted & Fast: worker-canonical roles/groups determine scopes; no registry read.
Trustless/custom chain gates: Worker reads SessionRegistry gates and selected
SBT balances before issuing scoped access.
```
### 5. Encryption / Gated Decrypt
```text
Worker encryption (optional in Hosted & Fast):
Worker encrypts payloads at rest with worker-envelope keys
Worker roles/conditions gate each key release
Lit opt-in:
Client encrypts content locally with a fresh content key
Session Worker asks a registered Lit Action to wrap that key for the SBT gate
On read, the Worker signs the exact request; the Lit Action verifies it and
checks the SBT gate, then encrypts its reply to that Worker's ephemeral key
Scoped execution credentials alone cannot choose a requester or read the key
The Worker operator sees content keys; Lit account/permission managers can
authorize other Actions and remain trusted, so this is not end-to-end encryption
Arweave or Cloudflare stores the resulting ciphertext according to the profile
```
Lit encrypts only the fields you lock; who answered which question stays public.
See [Worker authorization for Lit key release](docs/lit-worker-authorization.md)
for the protocol and setup.
## Corpus Data
- `ai-discourse-corpus/` is a tracked top-level dataset with reusable JSON sub-corpuses covering AI policy, safety research, technical evaluations, science fiction, debates, practitioner interviews, and enriched social-media discourse.
- The corpus is kept outside the client so it can be versioned and reused independently of the client demo runtime.
## Key File Map
### Client (`client/src/`)
| Area | Files |
|------|-------|
| Entry / routing | `components/MainSite/AppShell.tsx`, `routeTable.ts` |
| Home tab shell | `components/MainContent/MainAreaTabs.tsx`, `ToolExplorer.tsx`, `OnboardingWalkthrough.tsx` |
| Account / login settings | `components/Account/LoginAndSettingsModal.tsx`, `LoginButton.tsx` |
| Session wizard | `components/Sessions/SessionWizard.tsx` |
| Session page shell | `components/OnePageSession/OnePageSession.tsx`; hosted agent access uses `OnePageSessionAgentShell.tsx`, `onePageSessionAgentController.ts`, and `onePageSessionAgentActions.ts` |
| Shared demo-session views | `components/DemoViews/CorpusViewer.tsx`, `components/DemoViews/DemoAnalysis/`, `components/DemoViews/DebateHUD/` |
| Document library | `components/DocumentLibrary/SessionDocumentsPage.tsx`, `DocumentLibraryPanel.tsx` |
| Admin | `components/Admin/AdminPage.tsx` |
| About page | `components/About/AboutPage.tsx` |
| Survey tool | `components/SurveyTool/SurveyTool.tsx`, `CreateQuestionsAndSurveys.tsx`, `SurveyResults.tsx` |
| Shared UI | `components/Shared/AudioInput/AudioInput.tsx`, `components/Shared/Json/JsonControls.tsx`, `components/Shared/Json/JsonDisplay.tsx` |
| SBT management | `components/SBTs/SBTsPage.tsx`, `SBTsList.tsx`, `SBTPage.tsx`, `CreateSBTGroup.tsx` |
| Gate components | `components/Gates/` |
| **Utilities** | |
| Web3 / contracts | `utilities/web3/chainGateway.ts`, `contractScripts.impl.ts`, `contractHelpers.ts`, `chainEventStreams.ts`, `profileChainReads.ts`, `sessionRegistry.ts` |
| Wallet | `client/src/wallet/` passkey EOA wallet config, encrypted keystore, EIP-1193 provider, and soft-session worker |
| Crypto / Lit | `shared/encryption/envelopeV1Core.mjs` owns the shared envelope-v1 primitives; `utilities/crypto/cryptography.ts`, `litProtocol.ts`, and `encryptedFields.ts` own browser providers, Lit integration, and response orchestration |
| Arweave | `utilities/arweave/arweaveClient.js`, `arweaveUrls.ts` |
| Session helpers | `utilities/session/sessionSlug.ts` owns identity/transport/storage slug conversions; `sessionNaming.ts`, `sessionMetadata.ts`, `resourceKeys.ts`, `sessionModeProfile.ts`, `groupCreationPolicy.ts`, `sessionBackendKind.ts`, `agentClientLogin.ts`, `agentSessionData.ts`, and `agentSessionBackend.ts` own higher-level session behavior |
| Worker auth | `utilities/worker/workerAuth.ts`, `corsProxy.ts` |
| Cache | `utilities/cache/cacheScripts.ts` |
| AI | `utilities/ai/aiClient.ts`, `aiSettings.ts` |
| Survey logic | `utilities/survey/questionRouting.ts`, `filterStateUtils.ts`, `compareUsers.ts` |
| **Config / variables** | |
| Feature flags | `variables/appConfig.ts` |
| Chain config | `variables/chains.ts` |
| Session fallback | `variables/demo/demo_sessions.json` |
### Contracts (`contracts/`)
| Contract | Purpose |
|----------|---------|
| `SessionRegistry.sol` | Session registry, resource gates (Any/All SBT rules), metadata URI pointers |
| `Surveys.sol` | Survey/question registration and response hash anchoring. Explicit existence state preserves `bytes32(0)` as the absence sentinel; zero IDs, zero content/response hashes, and mismatched optional survey-response pairs revert. |
| `CustomSBT.sol` | Non-transferable ERC-721 (SBT) with ERC-5192 / ERC-5484-aligned lock + burn-auth surfaces, password/invite/signature mint paths, `SBTActivity` history events, and `getHistorySummary()` for count-only reads. Transfers, approvals, and `safeTransferFrom` revert with `Soulbound()`. |
| `SBTFactory.sol` | Deploys new CustomSBT instances (optionally deterministic via CREATE2). Configured deterministic deployments require the transaction sender to be the configured SBT admin. |
`Surveys.sol` reserves distinct IDs for surveys and questions, including questions
in a survey's initial batch. This prevents the shared `userResponses[user][id]`
mapping from aliasing a survey response and a question response.
### Workers (`workers/`)
| Worker | Purpose |
|--------|---------|
| `sessionCorsWorker/worker.js` | Canonical config/auth/storage for Hosted & Fast, plus profile-enabled AI, Arweave, fetch, transcription, and faucet routes |
| `deploy-helper/worker.js` | Worker deployment for the `/new` API-token path, including optional Agent HTTP setup |
| `sessionCorsWorker/agent/` | Scoped Agent HTTP, credential exchange, optional registry queue and Session Wrapped under canonical Session Worker authority |
### Verification
Public unit and integration coverage lives beside client source and under
`tests/root/`. Supported public commands are documented in `docs/testing.md`.
## Contract Addresses
Contracts are chain-agnostic EVM Solidity. The SPA's canonical deployment
manifest is `client/src/variables/contracts.json`, exposed through
`client/src/variables/chains.ts` as `SESSION_REGISTRY_ADDRESSES` and
`SESSION_CONTRACTS_BY_CHAIN`.
| Chain | SessionRegistry | Surveys | SBTFactory |
|-------|----------------|---------|------------|
| OP Sepolia (11155420) | `0xDcB1731984E9F75c6a061c38dD8b67d18De4C0c1` | `0x59664B9dA510a33F2edB7E14Cf0c2749bf506B8A` | `0x8CBeE1EE46603b446b499cb32F63fa9860a50478` |
OP Sepolia is the current default and the only chain configured in the canonical
manifest. Its immutable Surveys and SBTFactory deployments predate the current
source hardening. The contract restrictions described in this document become
live only after a testnet redeploy and a manifest update.
The current OP Sepolia `SBTFactory` default above was deployed in tx
`0x57b91018ed6b93f64c83d5a44bfb9d0be1920f96929ecc045aa3946ba7cc917e`.
### SBT Claim Authorization
Group-claim signatures use EIP-191 over `keccak256(abi.encode(domain, chainId,
collection, claimant))`. Invite signatures replace the claimant with a positive
one-use slot bounded by the collection limit. The domain is the keccak256 hash
of `ContextEngine.SBT.GroupMint:1` or `ContextEngine.SBT.Invite:1`, respectively.
Slots redeem independently of mint order and remain consumed after burns.
A wallet can hold tokens from other collections; only another live token in
the same collection prevents claiming.
Limited-group creators keep their signing password private and export one
pre-signed code per slot. Each code contains only chain ID, collection address,
slot and signature (`c`, `a`, `n`, `s` in base64url JSON). Recipients cannot use
a reusable password to generate fresh slots. Claim links still identify the
group, with the code entered separately. `sbtAuthorization.ts` supplies the
same signing implementation to the browser and the local contract smoke test.
The client derives a group-password signer with PBKDF2-SHA256 (600,000
iterations) over the NFKC-normalized password, salted by
`keccak256(abi.encodePacked("sbt-group-password-v4", sbtAddress))`; the SBT
stores only `keccak256(signer address)` as `groupPasswordHash`. Because the salt
is the group's own address, group-password groups deploy through
`SBTFactory.createSBTDeterministicConfigured` at their predicted CREATE2
address, and the factory sets `groupPasswordHash` once during that deployment.
See `shared/crypto/groupPasswordDerivation.cjs`.
The current CustomSBT source uses one mutable `admin`, rotated with `changeAdmin`.
It exposes no transferable collection ownership. Zero admin permanently disables
issuer actions; holder burns still follow `OwnerOnly`/`Both`, and `Neither`
remains unburnable. Ordinary deployments preserve an explicit zero admin.
Configured CREATE2 deployment requires an initial nonzero admin matching the
sender to prevent capture; that admin may retire to zero after initialization.
CustomSBT instances are deployed per-group via SBTFactory. Configured
deterministic SBT creation is admin-submitted.
### Historical Base Sepolia Record
Base Sepolia (`84532`) remains a best-effort legacy/development compatibility
target, not an actively supported runtime. The canonical client manifest has no
Base contract set. The historical addresses below are retained for auditability;
they are not active client configuration.
| SessionRegistry | Surveys | SBTFactory |
|-----------------|---------|------------|
| `0xD55Aa8fb29964d034d59B90DFFD23790f7B34B00` | `0xcccb5c1a96b3e10f395e318ae75db24e45bd3808` | `0x538A48BC439A36D2A86e63114DCD9c429d2ddEcA` |
The historical Base Sepolia `SBTFactory` was deployed in tx
`0x4a0428a0fe6d6090fd6112885ea46b30ff84a1a551d0806c0f9afda4b44a5f21`.
To activate a new chain: verify the representative compatibility flows, deploy
contracts, add the canonical set to `contracts.json`, expose the chain through
`chains.ts`, and add its chain definition to the chain registry.
### Address Discovery
Contract address discovery is file-based, with no on-chain or dynamic step.
`client/src/variables/chains.ts` imports the base deployment map from `contracts.json`.
`SESSION_REGISTRY_ADDRESSES` maps each configured chain ID to its `SessionRegistry` address.
`SESSION_CONTRACTS_BY_CHAIN` provides the per-chain contract configuration used by the SPA.
For local development, `local-contracts.json` can override the checked-in defaults.
Those local overrides are merged into both exported maps before the client reads them.
## Auth Model
```text
Client ──▸ POST /auth/nonce { address, sessionSlug }
◂── nonce
──▸ sign login message with passkey-derived EOA or wallet
──▸ POST /auth/login { address, message, signature, sessionSlug }
Worker verifies signature, then evaluates profile-specific authorization:
Hosted & Fast -> worker-canonical roles/groups and session config
Trustless/custom -> selected SessionRegistry gates and SBT balances
Worker ──▸ { token, exp } with session-scoped permissions + config epoch
Client ──▸ authenticated Worker requests with Authorization: Bearer
```
Worker-canonical login does not query an EVM registry. Chain reads occur only
when the selected profile uses on-chain authorization. Login tokens use a
base64url payload plus HMAC, expire after four hours, and have a same-TTL
`authToken:{slug}:{sub}:{jti}` KV marker. Before protected route side effects,
the Worker also requires the token's server-managed authorization epoch to
match current config and re-evaluates the current default plus route-specific
gate. Registry gate changes therefore take effect on the next request;
authority-sensitive config changes invalidate previously issued tokens, while
content edits such as the session's name, context, agent instructions or
interview settings sign no one out (`shared/sessionConfigEdits.mjs`). A sign-out
everywhere, or making a session private, can take up to one second to reach
every request: answers and reads by people the config does not name may reuse a
Worker instance's config read for that long, while admin actions and config
changes always read it fresh. The mandatory Session coordinator
Durable Object serializes nonce issue/consume and per-route counters across
isolates; nonce state is stored only in the coordinator, without redundant KV mirrors.
## Session Config Data Shape
Config authority follows the selected session profile:
| Store | Profiles | Authority | Shape docs |
|-------|----------|-----------|-----------|
| **Worker KV** (`session:{slug}:config`) | Hosted & Fast; worker-backed custom profiles | Canonical identity/content for `worker_canonical`; operational config for other worker-backed profiles | [`docs/session-cors-worker.md`](docs/session-cors-worker.md) |
| **Worker KV** (`session:{slug}:secrets`) | Worker-backed profiles | AI keys and only the profile-enabled runtime credentials; never public config | [`docs/session-cors-worker.md`](docs/session-cors-worker.md) |
| **SessionRegistry** (on-chain) | Trustless & Slower; explicit registry profiles | Session identity, metadata pointer, admin, gates, sponsored flags | [`docs/session-registry.md`](docs/session-registry.md) |
| **Arweave metadata** | Trustless & Slower; explicit Arweave profiles | Durable content, UI defaults, contracts, and selected encryption metadata | [`docs/session-registry.md` §Arweave](docs/session-registry.md) |
See [`docs/session-registry.md`](docs/session-registry.md) for the decentralized
metadata schema and [`docs/session-cors-worker.md`](docs/session-cors-worker.md)
for canonical Worker config, secrets, and storage bindings.
## Storage Model
```text
Hosted & Fast (implemented default)
───────────────────────────────────
Per-session Worker
session:{slug}:config canonical identity/content and policy
session:{slug}:secrets AI and profile-enabled runtime secrets
Cloudflare storage routes payloads (Worker-encrypted when selected) and indexes in KV
optional existing R2 for advanced blob storage
passkey-derived EOA signing/admin identity; no required chain tx
Trustless & Slower (implemented opt-in)
────────────────────────────────────────
SessionRegistry / Surveys / SBTs public identity, gates, hashes, membership
Arweave metadata, payloads, tokenURI, documents
Public EVM wallet transactions, gas, contract reads
Lit (optional) SBT-gated key release via the session Worker
Company-Operated (planned)
──────────────────────────
Organization-selected IAM, key release/KMS, storage, AI, networking, and
observability adapters. Public EVM and Arweave are not architectural
requirements; a private EVM would be an optional future adapter.
```
## Further Reading
- [`spec.md`](spec.md) — Full feature specification
- [`docs/session-registry.md`](docs/session-registry.md) — On-chain registry + Arweave metadata schema
- [`docs/session-cors-worker.md`](docs/session-cors-worker.md) — Worker endpoints, KV layout, auth flow
- [`docs/arweave-payloads.md`](docs/arweave-payloads.md) — Arweave payload shapes
- [`docs/path-rpc.md`](docs/path-rpc.md) — PATH/provider ordering and overrides
- [`docs/rpc-scan-scope.md`](docs/rpc-scan-scope.md) — scan-scope and profile-scan guardrails
- [`docs/cache/README.md`](docs/cache/README.md) — managed cache backend + namespace guide
- [`docs/lit-protocol-information.md`](docs/lit-protocol-information.md) — Lit Protocol integration
- [`docs/resource-keys.md`](docs/resource-keys.md) — Resource key resolution
- [`docs/passkey-wallet.md`](docs/passkey-wallet.md) — passkey EOA wallet
- [`docs/forking-wallet.md`](docs/forking-wallet.md) — fork-owned RP ID setup
- [`docs/security-model.md`](docs/security-model.md) — embedded wallet security model
- [`docs/local-chain.md`](docs/local-chain.md) — Local Anvil development