Lens / E.D.I.T.H.

Architecture

Conversation pipelineRequest lifecycle
Conversation pipeline: see the component list below
Components and connections (9 / 8)
  • Visitor message (Client): Bounded text; unknown fields dropped by schema
  • Small talk + abilities (Process): Greeting, identity, 'what can you do?'
  • Retrieval (Service): TF-IDF-style over the fact index with synonyms
  • Origin + rate limit (Network): Same-host Origin, salted HMAC client key, sliding window
  • Open / perform (Process): Only a true open verb; chip or hands-on act
  • Gemini (off) (External): Grounded rephrase if enabled and facts match
  • Policy gate (Process): Distress first, then injection, explicit, private, abuse
  • Mind (Service): Counts, filters, compare, recommend, follow-ups
  • Honest fallback (Process): 'I don't have a verified answer for that yet'
  • Visitor message to Origin + rate limit
  • Origin + rate limit to Policy gate
  • Policy gate to Small talk + abilities: ok
  • Small talk + abilities to Open / perform: no match
  • Open / perform to Mind: no match
  • Mind to Retrieval: defers
  • Retrieval to Gemini (off): optional
  • Retrieval to Honest fallback: nothing grounded

What happens to a visitor's message, in order. Each stage can answer and stop.

Client-side architectureLogical
Client-side architecture: see the component list below
Components and connections (9 / 7)
  • EdithGate (eager) (Client): Summon listener, warms the host once
  • EdithHost (lazy) (Service): Store, sprite, CSS, timers; about 5.8 KB gzip JS
  • Capability kernel (Service): Registry, tickets, receipts, undo
  • Head avatar (Client): Hat and face layers only
  • Hands-on actor (Process): CSS-only movement via DOM landmarks
  • OS ports (External): OSPreferences, theme port, routes, media session
  • Messages / detached chat (Client): Shared conversation store
  • Guide layer (lazy) (Process): Ring and card from published guides
  • CMS Studio (External): Owner lines and entrance mix, fail-soft
  • EdithGate (eager) to EdithHost (lazy): warm
  • Head avatar to EdithGate (eager)
  • Messages / detached chat to Capability kernel: plan
  • EdithHost (lazy) to Hands-on actor: task
  • EdithHost (lazy) to Guide layer (lazy): tour
  • Capability kernel to OS ports: execute
  • CMS Studio to EdithHost (lazy): published only

Everything heavy is lazy; the shell holds only a gate and an avatar.

Package boundaries

  • @repo/edith is source-only with five entry points: . and ./contracts (browser-safe zod contracts), ./server (services, handler, limiter), ./next (App Router adapter) and ./express (an Express 5 router over the same handler, not imported by the Next app).
  • One catch-all route, /api/edith/[...path], on the Node runtime delegates to a single transport-neutral handler with limits, origin check and routing.
  • All tuning lives in a typed config file (apps/desktop/config/edith.config.ts) with no environment variables; the only runtime secret is GEMINI_API_KEY, inert while Gemini is disabled.