Dashboard/Algolia-Central/Documentation/01-System-Overview.md
Algolia-Central

Documentation/01-System-Overview.md

01 — System Overview

Last updated: 2026-04-17. Verified against rc2-algolia @ commit pre-Step-3.

What the system does

The RC2 Algolia system is a streaming AI sales assistant that answers technical/commercial questions about Algolia's products. It's designed for two modes:

  1. Maverick mode — general-purpose discovery conversation. Asks qualifying questions across 8 signals (role, pain, scale, industry, stack, etc.), then hands off to a specialist when qualified.
  2. Specialist mode — deep expert dive after handoff. Two specialists: - Elena — Solutions Engineer (merchandising, analytics, SaaS features) - Bruno — Principal Architect (infra, scale, integration, SDK)

Both specialists run on Agent Studio (external Anthropic service). Maverick runs in-process on Gemini 2.0 Flash.

Stack

Component What Where
API layer Vercel serverless functions api-src/search.ts, api-src/diag.ts, api-src/health.ts
LLM (Maverick) Gemini 2.0 Flash (streaming) lib/llm/* via getLLMProvider()
LLM (Specialists) Agent Studio (Elena + Bruno agents) lib/agent-studio/client.ts + stream-adapter.ts
Retrieval Algolia two-index lib/search/algolia_client.ts, retrieval_orchestrator.ts
Session state Redis (Upstash) lib/search/redis.ts
Frontend React + Vite src/hooks/chat/useChatStream.ts + useSpecialist.ts
Rate limit + circuit breaker In-process + Redis lib/security/*

Explicit non-stack (deprecated RC1): NO Supabase, NO GPT/OpenAI, NO pgvector, NO dual-lane retrieval. If you see references to any of these in code or docs, they are legacy artifacts.

Two Algolia Indexes (both stay alive)

Index Purpose How it's used
Atlas Classification / vertical tagging Hits map a query to a matched vertical (e.g., "Ecommerce", "AI Relevance") → used to bias retrieval
NeuralSearch Semantic breadth The main knowledge store — blog posts, docs, customer stories, pricing, support

Both indexes are hit on every Maverick turn. See 06-Retrieval-Architecture for the strategy selection and chunk merger behavior.

Three Personas

Persona Role Engine System prompt lives in Agent ID
Maverick Discovery + qualification Gemini 2.0 Flash lib/search/prompts/maverick.ts (+ sibling files in prompts/) n/a (in-process)
Elena Solutions Engineer (merch, SaaS, analytics) Agent Studio Agent Studio UI (remote) f029acbb-a7a0-43b1-9a85-a14ef3907cd3
Bruno Principal Architect (infra, SDK, scale) Agent Studio Agent Studio UI (remote) facb549e-8f27-47e9-9e42-e20032b0f1a1

Critical asymmetry: Maverick's prompt is versioned in our repo; Elena's and Bruno's prompts live in Agent Studio and are NOT in git. Changes to specialist behavior require editing the Agent Studio agent — we only control the wire protocol. See 07-Personas-Reference.

Two Entry Points Into the Pipeline

Both start at api-src/search.ts handler. Branching happens on body params:

Entry A — Normal flow (no consent)

POST /api/search with {query, history, persona?, trigger?}. Routes by persona: - If persona is specialist (elena|bruno) → igniteSpecialist(trigger='handshake') — produces the summarize-back-to-me handshake - Else → igniteMaverick() — produces a Maverick discovery turn

Entry B — Consent flow (specialist execute)

POST /api/search with {query, history, persona, consent:true, trigger}. Skips persona routing. Always → igniteSpecialist(trigger='execute') — produces the full deep dive.

The two flows share the same SSE streaming response plumbing but diverge in what they call. api-src/search.ts:193–260 is the consent branch; 263–339 is normal flow.

Known issue (F-027): these two branches duplicate ~60 lines of near-identical stream plumbing. Collapse target in Step 5.

The Three Guardrails

Every request must survive three in-process checks before orchestration runs:

  1. Rate limit (lib/security/rate-limiter) — per-client-ID sliding window
  2. Circuit breaker (lib/security/circuit-breaker) — opens on consecutive orchestrator failures
  3. Input validation — query type + length (max 2000 chars), history array shape

All three sit in api-src/search.ts before igniteMaverick / igniteSpecialist are even imported.

The Big Picture Diagram (text form — mermaid pending)

Client (React hook: useChatStream or useSpecialist)
   │  POST /api/search  { query, history, persona?, consent?, trigger? }
   ▼
Vercel serverless → api-src/search.ts handler()
   │
   ├─ CORS + security headers
   ├─ Rate limit (Redis)
   ├─ Circuit breaker (Redis)
   ├─ Input validation (query, history, length)
   │
   ├─ Branch: consent=true
   │     └─► igniteSpecialist(trigger='execute')   [Agent Studio stream]
   │
   └─ Branch: consent=false (default)
         ├─ isSpecialist(persona)? → igniteSpecialist(trigger='handshake')
         └─ else                    → igniteMaverick()       [Gemini stream]
   │
   ▼
ReadableStream → SSE pipe → res.write per chunk → Client parses events

Where knowledge lives

Four primary source-of-truth locations:

Kind of knowledge Lives in
Algolia content (blogs, docs, customer stories, pricing, support) Algolia indexes (Atlas + NeuralSearch)
Maverick prompts + behavior rules lib/search/prompts/*.ts (in repo)
Specialist prompts + behavior rules Agent Studio (remote — NOT in git)
Session state (signals, asked questions, dossier, turn count) Redis, schema in lib/search/redis.ts

A prompt leak into UI (F-032 Namedrop) means an instruction in a repo prompt got echoed verbatim by the LLM. A hallucination like F-038 means the LLM generated content that matches none of the above. The audit pipeline (see 08-Audit-Pipeline) is what separates the two.

Current Health Snapshot (post-Step-2, 2026-04-17)

Signal State
Maverick pipeline Functional, ~6500ms avg turn (target ≤4000ms)
Specialist handshake ~5s, acceptable
Specialist execute ~33s (F-022 Agent Studio-side, out of scope)
Link HEAD checks ON (enabled in Step 2)
Maverick audit Inline — strips hallucinated sentences
Specialist audit NONE (F-038 — P0 blocker, Step 3 will fix)
Dead code 2 batches removed (~1040 lines) Step 1 + 2
Known open findings F-026, F-028, F-029, F-031–F-039

Cross-references

  • 02-Data-Flow — step-by-step pipeline walk
  • 03-Files-Reference — every file, what it does
  • 08-Audit-Pipeline — how hallucinations are caught (and where they leak — F-038)
  • 10-Known-Issues — F-001 to F-039 master list