Repository navigation
Architecture
Storming Bastille is a FastAPI backend with a Next.js frontend, connected by Server-Sent Events (SSE). The backend coordinates five AI agents across four phases, writing results to SQLite with a GCS backup. The frontend maintains Zustand state and renders two concurrent views: a streaming narrative panel and a React Flow causal graph.
User query arrives at POST /api/query
│
├─ Phase 1: RESEARCH (parallel, streams first)
│ ├── DuckDuckGo search ──┐
│ └── Bing search ────────┴── results injected into HistorianAgent prompt
│ │
│ HistorianAgent (Claude Haiku 4.5)
│ - streams narrative chunks via SSE
│ - embeds structured events as JSON in output
│ │
│ [SSE: narrative chunks, ~1-2s first token]
│
├─ Phase 2: GRAPH NODES (immediate after Phase 1 completes)
│ GraphBuilderAgent
│ - parses events from historian output
│ - creates React Flow nodes + timeline data
│ [SSE: graph event with nodes only, no edges yet]
│
├─ Phase 3: CAUSAL ANALYSIS (async, runs concurrently with Phase 2 output)
│ CausalAnalystAgent (Claude Sonnet)
│ - takes events list
│ - identifies relationship types + confidence scores
│ [SSE: graph update event with edges added]
│
└─ Phase 4: SOURCE VERIFICATION (fire-and-forget)
SourceVerifierAgent
- cross-checks claims against scraped sources
- assigns reliability tiers
[SSE: sources event]
[DB: saves to SQLite + GCS backup]
The causal analyst (Claude Sonnet) is doing heavier work than the historian (Claude Haiku 4.5). If the frontend waited for edges before rendering anything, users would watch a blank canvas for 5–10 seconds.
The deliberate design choice: GraphBuilderAgent runs immediately after Phase 1 and emits a graph event with only nodes. The frontend renders these nodes in their initial positions (Dagre layout). Then when the causal analyst finishes, a second graph event arrives with edges, and React Flow updates in place. Users see something meaningful within 2 seconds and watch the graph "complete" rather than appear all at once.
This means the frontend must handle two distinct graph events for the same query:
- First
graphSSE event: nodes array populated, edges array empty - Second
graphSSE event (update): edges array populated, nodes unchanged
The useGraph hook in the frontend handles this by merging rather than replacing.
A deliberate architectural choice: web search results are fetched by Python code (backend/app/tools/web_search.py) and injected as formatted text into the HistorianAgent's prompt, rather than using Claude's built-in tool-use feature.
The reason is latency. Tool-use requires a round-trip: Claude decides to call a tool, the tool executes, results are returned, Claude continues. For this app, the search should happen before Claude starts thinking — not during. By pre-fetching in parallel with the initial request and injecting results as prompt context, the first token from Claude arrives faster and Claude has search results from the very start of its generation.
The tradeoff is that Claude can't decide what to search — queries are derived from the user's question directly. For historical research this works well; the user's question is already the ideal search query.
Every query opens an SSE stream. The frontend's useStreamingQuery hook parses these events in order:
event: session
data: {"session_id": "uuid", "query": "..."}
event: status
data: {"message": "Searching the web...", "phase": 1}
event: narrative
data: {"chunk": "The French Revolution...", "done": false}
... (many narrative chunks)
event: narrative
data: {"chunk": "...", "done": true}
event: status
data: {"message": "Building causal graph...", "phase": 2}
event: graph
data: {"nodes": [...], "edges": [], "timeline": [...]}
event: status
data: {"message": "Analyzing causal relationships...", "phase": 3}
event: graph
data: {"nodes": [...], "edges": [...]}
event: sources
data: {"sources": [...]}
event: done
data: {"session_id": "uuid"}
The frontend renders each event type as it arrives. narrative events are appended to the streaming text panel. graph events update React Flow state. sources events populate the citations panel.
backend/app/agents/orchestrator.py is the entry point for all queries. It:
- Creates or retrieves a session in SQLite
- Initialises the web search tools and runs DuckDuckGo + Bing concurrently via
asyncio.gather - Yields the session SSE event
- Instantiates and runs
HistorianAgent, yielding its narrative chunks as SSE events - Once the historian finishes, passes its extracted events to
GraphBuilderAgentand yields the nodes graph event - Launches
CausalAnalystAgentand yields the edges graph event when done - Fire-and-forgets
SourceVerifierAgentviaasyncio.create_task— the SSE stream doesn't wait for it - Saves the completed graph to the database
backend/app/core/cache.py wraps a cachetools.TTLCache with a 1-hour TTL and max 100 entries. Web search results are cached by query string. Repeated queries for the same topic (e.g., two users ask about the French Revolution within an hour) reuse cached search results, skipping the DuckDuckGo/Bing round-trips entirely.
The cache lives in process memory — it does not persist across restarts and is not shared across Cloud Run instances. This is intentional: it's a latency optimisation, not a correctness concern.
SQLite was chosen over a managed database for a few reasons: zero operational overhead, works inside a single Cloud Run container, and the data volume is modest (session history, not analytics).
The challenge with Cloud Run is that containers are ephemeral — a new revision wipes local disk. The solution:
- On startup, the app checks for
data/bastille.db. If missing, it downloadsbastille.dbfrom GCS (BACKUP_BUCKETenv var). - Every 5 minutes, a background task uploads the current database file to GCS, overwriting the previous backup.
- On SIGTERM (Cloud Run shutdown), a final upload runs before the process exits.
- Schema migrations run at startup via the
schema_migrationstable.
The result: SQLite behaves like a persistent database across container restarts, with at most 5 minutes of potential data loss on an unexpected crash.
If BACKUP_BUCKET is not set (local dev), the backup task is a no-op. The database file lives at DATABASE_PATH (default data/bastille.db).