Architecture

GuideKit is built as a modular monorepo with clear separation of concerns. This page covers the internal architecture.

Package Structure

guidekit/
  packages/
    core/           # @guidekit/core — pipeline, DOM, LLM, context
      src/
        pipeline/   # v2 PipelineOrchestrator (scan → render)
        dom/        # DOM Intelligence Engine
        cognitive/  # Tier C experimental subpath
        telemetry/  # Tier C experimental subpath
    intelligence/   # @guidekit/intelligence — Platform Mode enrich/validate
    knowledge/      # @guidekit/knowledge — client-side RAG
    plugins/        # @guidekit/plugins — plugin hooks and tools
    react/          # @guidekit/react — Provider + hooks + widget
    server/         # @guidekit/server — JWT tokens, async SessionStore, proxy
    vanilla/        # @guidekit/vanilla — IIFE script-tag bundle
    cli/            # @guidekit/cli — CLI tools
  apps/
    docs/           # Documentation site (Nextra)
    example-nextjs/ # Reference Next.js integration

See Platform Mode for the full v2 pipeline stage diagram.

Core Subsystems

DOM Intelligence Engine

Builds a compact PageModel (~5KB) using TreeWalker traversal:

• Section scoring: Viewport-visible sections scored highest
• data-guidekit-target: Developer-provided stable selectors
• data-guidekit-ignore: Skip sensitive DOM subtrees
• Budget: 5000-node limit, yields via requestIdleCallback with adaptive time budget
• MutationObserver: Debounced (500ms), circuit breaker at 100 mutations/sec

LLM Orchestrator

Streaming multi-turn conversation with tool calling:

• Provider adapters: Gemini (default), custom adapters via LLMProviderAdapter
• Tool execution: Multi-turn loop with parallel tool calls
• Context window: Sliding window, summarize oldest turns at 80% capacity
• Content filter: Retry with simplified prompt, graceful user message

Voice Pipeline

Half-duplex voice with echo cancellation:

Mic → VAD (Silero) → STT (Deepgram / Web Speech API) → LLM (Gemini) → TTS (ElevenLabs / Web Speech API) → Speaker

• State machine: IDLE → LISTENING → PROCESSING → SPEAKING → IDLE
• Barge-in: Detect speech during TTS, abort stream, switch to LISTENING
• Echo detection: 60% word overlap within 3-second window
• Degradation: Voice failure → text-only mode (not Web Speech API)

Visual Guidance

Spotlight overlay and tooltip system:

• Spotlight: Box-shadow cutout on document.body (outside Shadow DOM)
• Tracking: ResizeObserver + scroll listeners (not rAF polling)
• Scrollable containers: Detect ancestor overflow, clip to intersection
• Tours: Sequential guided tour with auto/manual modes
• Accessibility: aria-live="assertive" announcements for screen readers

User Awareness

Passive signals for proactive behavior:

Security Model

Token-Based Auth

Client → POST /api/guidekit/token → JWT (sessionId, permissions, exp)
Client → JWT to server middleware → Server looks up provider keys → Proxy to provider

• JWT tokens do NOT contain API keys (base64-decodable)
• Provider keys stay server-side in a SessionStore (in-memory for dev; Redis for multi-instance production — see Server SDK)
• Tokens refresh at 80% of TTL, multi-tab coordination via BroadcastChannel
• Signing secret rotation: accepts array [newSecret, oldSecret]
• Proxy routes enforce permissions (llm / stt / tts) and optional allowedOrigins (JWT aud → Origin header)

Production security checklist

1. Proxy mode only — never ship provider API keys to the browser (Privacy & Security).
2. Session store — RedisSessionStore when running more than one instance (compatibility).
3. Rate limits — tune createGuideKitHandler rateLimit (Server SDK).
4. Origin allowlist — set allowedOrigins when minting tokens in production.
5. Observability — use pipeline telemetry to debug latency and token-heavy turns (Observability).

Privacy

Protections

• data-guidekit-ignore: Skip sensitive subtrees
• onBeforeLLMCall: Developer privacy hook for custom scrubbing
• Tooltip textContent only (never innerHTML — prevents XSS)
• Client-side rate limits (cost protection, not security)
• Password/email/phone inputs: values never included in PageModel

Error Handling

All errors extend GuideKitError with actionable guidance:

class GuideKitError extends Error {
  code: string;
  provider?: string;
  recoverable: boolean;
  suggestion: string;
  docsUrl: string;
}

Error types: AuthenticationError, ConfigurationError, NetworkError, TimeoutError, RateLimitError, PermissionError, BrowserSupportError, ContentFilterError, ResourceExhaustedError, InitializationError.

See Troubleshooting for how recoverable maps to user-facing retry behavior.

Observability

Each user message records per-stage pipeline spans (latency, token metadata). Use Observability and the DevTools Telemetry tab during development.

EventBus

Typed pub/sub with namespace support:

bus.on('dom:scan-complete', handler);
bus.on('llm:*', handler);     // Namespace wildcard
bus.onAny(handler);            // All events
const unsub = bus.on('error', handler);
unsub();                       // Cleanup

Error isolation: one handler throwing does not prevent others from executing.

Resource Management

All allocated resources tracked via ResourceManager:

• AbortController signal pattern for event listeners
• Ref-counted singleton (StrictMode safe)
• Per-resource 2s cleanup timeout on teardown
• Instance isolation via instanceId

LLM Tools

Agent Runtime

Agent Runtime v1 combines:

1. Site knowledge: token-protected server search over indexed website documents.
2. Live page model: current DOM sections, forms, overlays, navigation, and action-aware interactives.
3. Guided autonomy: same-origin navigation and safe clicks can run automatically; submit, purchase, destructive, and auth actions require confirmation unless handled by developer-defined actions.

PageMemory remains session/current-page memory. Whole-site context comes from siteKnowledge, which keeps large or private indexes server-side.

Technology Stack