LexAI/docs/ARCHITECTURE.md

Architecture

The current system and its important boundaries. Describe what is, not aspirations.

System at a glance

• Shape: dual client surfaces (Chrome MV3 extension + VS Code extension) sharing portable LLM core; no LexAI backend
• Stack: TypeScript; Chrome via WXT ^0.20 + React 18; VS Code via packages/vscode (esbuild bundle); Node 22
• Data stores: Chrome chrome.storage.local (encrypted key + prefs); VS Code Secret Storage (API key) + lexai.* settings
• Hosting / deploy target: Chrome Web Store (Gitea CI); VS Code Marketplace not wired yet (local VSIX / extension host)
• Build / release: Chrome npm run build → .output/chrome-mv3/; VS Code npm run vscode:build → packages/vscode/out/extension.js

Component map

shared: src/lib/{providers,actions,types}  (+ crypto/messaging Chrome-only)

Chrome:
  content.ts ──ANALYZE_TEXT──> background.ts ──fetch──> provider API
  options/popup (React) ──storage──> chrome.storage.local

VS Code:
  extension.ts (commands/menus) ──callProvider──> provider API
       │                              ▲
       └── secrets / settings ────────┘

Component	Responsibility	Owns (paths)	Talks to	Notes
Shared core	Actions, prompts, provider adapters	src/lib/providers.ts, actions.ts, types.ts	Provider HTTPS APIs	No Chrome/VS Code imports
Chrome content	Selection, toolbar/modal, replace	entrypoints/content.ts	Background via messaging	DOM timing; data-lexai
Chrome background	Decrypt key, call providers, menus	entrypoints/background.ts	chrome.storage, providers	CORS + key isolation
Chrome Options/Popup	Settings + standalone analyze	entrypoints/options, popup	Storage + background	React; inline styles
VS Code extension	Commands, context menu, replace	packages/vscode/src/**	SecretStorage, settings, providers	Bundles @lib via esbuild
Chrome crypto/messaging	tweetnacl key path; safe chrome wrappers	src/lib/crypto.ts, messaging.ts	chrome.*	Not used by VS Code

Boundaries and contracts

• Trust boundaries: page DOM (Chrome) and editor buffer (VS Code) are untrusted text; API key never logged; only user’s chosen provider receives text/key
• Message contract (Chrome): ANALYZE_TEXT (payload + flat), COPY_AS, LIST_MODELS — see src/lib/types.ts
• VS Code commands: lexai.{fix,rephrase,shorten,expand,explain,prompt,setApiKey,clearApiKey,showStatus}
• Internal imports: VS Code may import @lib/providers|actions|types only — not crypto / messaging
• External dependencies: OpenAI, Anthropic, Groq, OpenRouter chat + models endpoints

Data model (essentials)

• Config: provider, model, writing style, keyProvider
• Sensitive: API key — Chrome encrypted blob + encKey; VS Code Secret Storage
• Legacy: Chrome plaintext apiKey fallback until migrated

Cross-cutting concerns

• Authn/z: none (BYO key)
• Observability: console debug in Chrome replace path (pre-release); VS Code notifications
• Feature flags: none
• Config: Chrome storage schema; VS Code contributes.configuration lexai.*

Open architectural risks

• Chrome and VS Code settings are not synced
• VS Code v1 has no Prompt Builder / Copy As / floating toolbar
• Relocating Chrome into packages/chrome deferred — root remains the WXT app