Dashboard/Algolia-Central/Documentation/00-README.md
Algolia-Central

Documentation/00-README.md

Algolia RC2 System Documentation

Purpose: Single source of truth for the RC2 Algolia codebase — every file, every function, every data flow, every dependency. Captured 2026-04-17 during the Phase 4 pipeline audit. Kept live as the system evolves.

Why this exists: Before this doc, system knowledge lived in heads and scattered stale files. Acquiring it required re-reading 18 files + running 40 traces. That cost must never be paid again. This wiki is the canonical reference; existing docs in /docs of the codebase are legacy and should be migrated into here or deleted.

Scope

This documentation covers the RC2 codebase at /Users/arijitchowdhury/AI-Development/RAG/AlgoliaRAG-Google/rc2-algolia. The RC3-Phoenix repo holds only testing notes — code lives in RC2.

Production URL: main branch. RC3-Phoenix = preview only.

Table of Contents

# Chapter Status What it covers
01 01-System-Overview draft High-level architecture, personas, entry points
02 02-Data-Flow draft End-to-end pipeline: Maverick path, Specialist path, SSE events, timings
03 03-Files-Reference draft File-by-file catalog (lib/search, api-src, agent-studio, hooks)
04 04-Functions-Reference draft Every ALIVE function: signature, deps, side effects
05 05-Prompts-Reference draft Where prompts live, what they contain, known leakage
06 06-Retrieval-Architecture draft Atlas + NeuralSearch two-index pattern, strategies, chunk merger
07 07-Personas-Reference draft Maverick, Elena, Bruno — model, agent IDs, responsibilities
08 08-Audit-Pipeline draft InlineStreamAuditor + ContentAuditor post-Step-2 reality
09 09-Session-State draft What persists per session + where
10 10-Known-Issues draft F-001 through F-039 cross-reference

Authoritative Facts (do not drift)

These are load-bearing facts the rest of this wiki depends on. If any of these change, update here first.

  • Codebase root: /Users/arijitchowdhury/AI-Development/RAG/AlgoliaRAG-Google/rc2-algolia
  • LLM for Maverick: Gemini 2.0 Flash (NOT 2.5 — 2.5 has a 10–30s thinking penalty)
  • Agent Studio IDs:
  • Elena (Solutions Engineer): f029acbb-a7a0-43b1-9a85-a14ef3907cd3
  • Bruno (Principal Architect): facb549e-8f27-47e9-9e42-e20032b0f1a1
  • Two Algolia indexes (both stay):
  • Atlas — filtering / vertical classification
  • NeuralSearch — semantic breadth
  • SSE chunk format: {"content": "..."} (NOT {"text": "..."})
  • Agent Studio returns: XML-tagged markdown — parser must handle it
  • NO Supabase, NO GPT, NO pgvector — RC1 stack is fully deprecated. Current stack = Algolia + Gemini + Agent Studio.

How to Use This Documentation

If you're a future session asked to "resume the audit"

  1. Start at 02-Data-Flow to understand how a request moves through the system
  2. Then 03-Files-Reference to find the file you need
  3. Then 04-Functions-Reference to understand a specific function

If you're debugging a production issue

  1. Check 10-Known-Issues first — it's probably a cataloged finding
  2. If not, trace the request through 02-Data-Flow to identify which step fails
  3. Use 03-Files-Reference to find the owner file

If you're proposing a change

  1. Read the relevant chapter
  2. Run the verification in 00-Verification-Protocol (TBD)
  3. Update the doc first, then ship the code

Maintenance Rules

  • Verify before writing. Every function signature, every file listed, every data flow step MUST come from reading the actual code or observing the actual trace. No guesses. This is a documentation wiki, not a sales deck.
  • Mark uncertainty explicitly. If something is assumed but not yet verified, tag it [UNVERIFIED] and add a verification task.
  • Date-stamp at the top of each chapter. When you update, update the date.
  • Delete legacy docs that conflict. Do not leave /docs/BACKEND_ARCHITECTURE_V2.md alongside this wiki claiming different facts. One source of truth.

Source Material

This wiki was bootstrapped from: - rc3-phoenix/testing/Phase-4-Execution-Map.md — the 7-step audit plan + findings F-001 to F-039 - rc3-phoenix/testing/Detailed-Audit-Finding-Record.md — live trace evidence - Live traces: Runs 001–006 (session timings) - Direct code reads across lib/search/*, api-src/*, lib/agent-studio/*, src/hooks/chat/*

Every numerical claim (line counts, step timings, response sizes) was measured, not estimated.

Last updated: 2026-04-17. Owner: Arijit.