Line 7 now uses a real markdown link for DESIGN.md instead of the
inline code formatting, and a new line below invites readers to
https://bookly.codyborders.com/architecture for the literate-program
walkthrough.
Adds --number-sections to the pandoc invocation and rewrites the header
CSS so sections are visually separated from their titles:
- TOC gets real disc/circle bullets with nesting
- Each h1 starts with a top border and extra vertical rhythm
- h2 gets its own lighter divider
- Numbered sections (1, 2, 8.1, 8.2, ...) sit in a muted slot ahead of
the title so the eye parses them as metadata, not as part of the
heading text
- TOC has a "Contents" label above the list
- All colors still derived from the app palette (#f5f3ee background,
#2e5b8a accent)
Security and performance fixes addressing a comprehensive review:
- Server-issued HMAC-signed session cookies; client-supplied session_id
ignored. Prevents session hijacking via body substitution.
- Sliding-window rate limiter per IP and per session.
- SessionStore with LRU eviction, idle TTL, per-session threading locks,
and a hard turn cap. Bounds memory and serializes concurrent turns for
the same session so FastAPI's threadpool cannot corrupt history.
- Tool-use loop capped at settings.max_tool_use_iterations; Anthropic
client gets an explicit timeout. No more infinite-loop credit burn.
- Every tool argument is regex-validated, length-capped, and
control-character-stripped. asserts replaced with ValueError so -O
cannot silently disable the checks.
- PII-safe warning logs: session IDs and reply bodies are hashed, never
logged in clear.
- hmac.compare_digest for email comparison (constant-time).
- Strict Content-Security-Policy plus X-Content-Type-Options,
X-Frame-Options, Referrer-Policy, Permissions-Policy via middleware.
- Explicit handlers for anthropic.RateLimitError, APIConnectionError,
APIStatusError, ValueError; static dir resolved from __file__.
- Prompt cache breakpoints on the last tool schema and the last message
so per-turn input cost scales linearly, not quadratically.
- TypedDict handler argument shapes; direct block.name/block.id access.
- functools.lru_cache on _get_client.
- Anchored word-boundary regexes for out-of-scope detection to kill
false positives on phrases like "I'd recommend contacting...".
Literate program:
- Bookly.lit.md is now the single source of truth for the five core
Python files. Tangles byte-for-byte; verified via tangle.ts --verify.
- Prose walkthrough, three mermaid diagrams, narrative per module.
- Woven to static/architecture.html with the app's palette
(background #f5f3ee) via scripts/architecture-header.html.
- New GET /architecture route serves the HTML with a relaxed CSP that
allows pandoc's inline styles. Available at
bookly.codyborders.com/architecture.
- scripts/rebuild_architecture_html.sh regenerates the HTML after edits.
- code_reviews/2026-04-15-1433-code-review.md captures the review that
drove these changes.
All 37 tests pass.
Add the public URL at the top, plus a "Try it yourself" section listing
the four mock orders, the happy paths, the sad paths, and the categories
of refusal the guardrails are designed to enforce — so a first-time
visitor can poke at every flow without reading the source.
A FastAPI + vanilla JS chat app fronting an Anthropic Claude agent for
order status, returns, and policy questions.
Architecture:
- agent.py: system prompt, runtime reminder injection, output validation,
agentic tool-use loop with prompt caching on the system prompt block
- tools.py: four tools (lookup_order, check_return_eligibility,
initiate_return, lookup_policy) with per-session SessionGuardState
enforcing protocol ordering on the tool side
- mock_data.py: orders, return policy, and FAQ entries used as the single
source of truth by both the prompt and the tools
- server.py: FastAPI app exposing /api/chat, /health, and the static UI
- static/: vanilla HTML/CSS/JS chat UI, no build step
- tests/: 30 tests covering tool-side enforcement, the privacy boundary,
output validation, and the agent loop with a mocked Anthropic client
- deploy/: systemd unit and nginx site config for production
