# Context Engine — Architecture > Single-page system overview. For detailed specs see [`spec.md`](spec.md) and [`docs/`](docs/README.md). ## Deployment Profiles ![Context Engine architecture: fingerprint passkey web sign-in and agent access, Session Worker services, an Access / Network / Data / AI icon legend, and connected deployment modes](docs/assets/readme-architecture-session-worker-mcp.png) 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