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