LexAI/docs/ARCHITECTURE.md

Architecture — LexAI

The current system and its important boundaries. Update in the same change that alters behavior; log the reason in DECISIONS.md.

System at a glance

• Shape: Browser extension (Chrome, Manifest V3) with three cooperating contexts message-passed over chrome.runtime. No backend.
• Stack: WXT ^0.20 (wraps Vite), React 18 + TypeScript (Options/Popup pages only), tweetnacl/tweetnacl-util for key encryption, Zustand installed but unused.
• Data stores: chrome.storage.local (provider, model, apiKeyEnc, encKey, legacy plaintext apiKey). No server, no DB.
• Hosting / deploy: Chrome Web Store. Build output .output/chrome-mv3/.
• Build / release: Gitea CI (.gitea/workflows/) → typecheck → test → build → zip to Gitea registry; v*.*.* tag → Chrome Web Store deploy.

Component map

entrypoints/content.ts   (content script, injected into <all_urls>)
  • Detects selection: textarea/input (selectionStart/End) vs contenteditable/DOM (Range API)
  • Renders floating toolbar + result modal + toasts (inline-styled, appended to document.body)
  • Snapshots selection state BEFORE any async call; Replace uses the snapshot
  • Sends { type: 'ANALYZE_TEXT', payload: {text, action, style} } to background

entrypoints/background.ts  (service worker — the LLM proxy)
  • onMessage: ANALYZE_TEXT and COPY_AS  (returns true to keep async channel open)
  • Reads provider/apiKey/apiKeyEnc/encKey/model from chrome.storage.local
  • Decrypts key (tweetnacl secretbox), routes to the correct provider fetch
  • Registers right-click context menus (action × style) on install

entrypoints/options/Options.tsx  (React settings page)
  • Provider + model + API key form; encrypts key → apiKeyEnc/encKey in storage

entrypoints/popup/Popup.tsx  (React toolbar popup)
  • Standalone text box → same ANALYZE_TEXT flow; shows config status; links to Options

Component	Responsibility	Owns (paths)	Talks to	Notes
content script	selection, toolbar/modal UI, replace	entrypoints/content.ts	background via messages	DOM-timing-sensitive; snapshot before await
background SW	LLM proxy, key decrypt, routing, context menus	entrypoints/background.ts	provider APIs, storage	only context allowed to fetch providers
options page	provider/model/key config + encrypt	entrypoints/options/Options.tsx	storage	React
popup	standalone analyze + status	entrypoints/popup/Popup.tsx	background via messages	React
shared utils	reference notes, future shared code	src/utils/**	—	see REFERENCE_NOTES.md

Boundaries and contracts

• CORS/key boundary: Content script and popup must not call provider APIs. All provider fetch and key handling live in background.ts. Route through ANALYZE_TEXT / COPY_AS.
• Message contract:
  • ANALYZE_TEXT accepts both { payload: {text, action, style} } and flat { text, action, style } — keep both if you touch the handler.
  • action ∈ grammar | rephrase | shorten | expand | explain. Context menu/popup emit fix, normalized to grammar by getSystemPrompt.
  • The onMessage listener must return true to keep the async channel open; removing it silently breaks every response.
• Provider layer: Each provider is duplicated — callX (system prompt from action) and callXWithPrompt (arbitrary prompt, used by COPY_AS). Request-shape changes usually need both. (Known smell — see DECISIONS + TASKS.)
• DOM guard: Every injected node carries data-lexai="true"; handlers check closest('[data-lexai="true"]') to avoid self-triggering. z-index: 2147483647 keeps UI above host pages.

Data model (essentials)

• Storage keys: provider, model, apiKeyEnc, encKey, apiKey (legacy plaintext, back-compat only).
• Sensitive data: the LLM API key. Prefer the encrypted path; never log it; never transmit except to the user's selected provider. Don't drop the plaintext fallback without a migration.

Cross-cutting concerns

• Config/secrets: provider list + default models + endpoints currently duplicated across Options.tsx and background.ts (drift risk — see TASKS).
• Observability: intentional [LexAI …] console logs in content.ts replace path (should be gated behind a DEV flag — see TASKS).
• Testing: Vitest (jsdom) unit + Playwright e2e. Unit tests currently exercise the chrome.storage mock rather than importing real handlers; e2e has [EXTENSION_ID] placeholders and won't pass as-is (see TASKS/EVALS).

Known constraints and debt

• Tailwind inactive; all UI is inline style objects (WXT PostCSS never wired). Do not assume Tailwind classes work.
• No shadow DOM; UI injected directly into document.body, isolated only by data-lexai + max z-index.
• Version bump is a manual two-file edit (package.json + wxt.config.ts).

---

Record non-obvious choices in DECISIONS.md; keep exposure current in attacksurface.md.