How bem-team/docket works
1. What this repo is
- A single-document legal AI app built around one Supreme Court opinion.
- The product is a three-pane experience: the full opinion, a case graph, and an AI chat assistant with citations.
2. Primary runtime boundary: Next.js App Router
- The app is a Next.js + React + TypeScript site.
- app/page.tsx is the main product shell.
- app/embed/graph/page.tsx is a focused embeddable graph view.
- app/api/chat/route.ts is the server endpoint for the agent.
3. Static case data layer
- The demo ships with bundled artifacts in data/, so it can run without external backend setup.
- Key assets include the parsed opinion, graph data, metadata, economics data, and the source PDF.
- This makes the case content effectively a local read-only corpus for the app.
4. Document structure and knowledge graph
- The opinion is not treated as raw text only; it is pre-parsed into labeled sections and a typed entity graph.
- The graph represents legal entities such as justices, opinions, precedents, statutes, and holdings.
- components/Graph.tsx consumes this structure for the interactive visual layer.
5. Reader experience
- components/Reader.tsx is the opinion-reading surface.
- It likely renders structured sections rather than a flat PDF, enabling navigation and citation-aware reading.
- components/Markdown.tsx and components/BemMark.tsx are the formatting/rendering helpers for structured text and references.
6. AI chat subsystem
- components/Chat.tsx is the client-side chat UI.
- The server-side chat route streams responses using the Vercel AI SDK, with tool calls for retrieval.
- The assistant is designed to answer from the opinion and cite the exact sections it used.
7. Retrieval and cost control
- The read path is selective: the agent lists/searches/reads only the opinion sections relevant to a question.
- lib/fs-tools.ts supports that file-system-style retrieval surface.
- components/CostMeter.tsx exposes the visible consequence of that design by showing the live cost impact of retrieval.
8. Layout/composition layer
- components/Workspace.tsx likely composes the reader, graph, and chat into the main app layout.
- components/HelpButton.tsx and components/Logo.tsx are supporting UI chrome.
- The architecture is centered on coordinated panes sharing the same underlying case corpus.
9. Domain-specific calculation utilities
- lib/economics.ts suggests a small supporting layer for token/cost accounting or usage economics.
- This is not core product logic, but it matters because the app surfaces retrieval efficiency as part of the UX.
10. SEO and distribution surfaces
- app/robots.ts and app/sitemap.ts provide crawlable metadata.
- public/manifest.webmanifest and the OG media assets support installability and social sharing.
- public/opinion.pdf and the data/og/ assets indicate the opinion and previews are bundled as distributable artifacts.
11. External service boundary
- The live architecture depends on bem for parsing, structured graph generation, and file-system retrieval when connected to a real bucket.
- The LLM interaction layer is mediated through the Vercel AI SDK.
- Deployment is intended for Vercel, but the repo still works locally using the committed case data.
12. End-to-end flow
- Opinion source is parsed into structured sections and entities.
- Those artifacts are persisted as JSON/PDF assets in the repo or a bem bucket.
- The UI reads the structured data for the reader and graph.
- Chat requests hit the API route, which retrieves only needed sections, streams a grounded answer, and updates the cost meter.
Main entry points: route.ts Chat API · Workspace.tsx Workspace · Reader.tsx Reader · page.tsx Main app
Components 25
App Router
Next.js entrypoints and server routes
- Main app · Primary three-pane product shell
app/page.tsx - Graph embed · Focused embeddable graph view
app/embed/graph/page.tsx - Chat API · Streams grounded assistant responses
app/api/chat/route.ts - Layout · Global document and app chrome
app/layout.tsx
UI
Reader, graph, chat, and page composition
- Workspace · Coordinates reader, graph, and chat panes
components/Workspace.tsx - Reader · Structured case reading surface
components/Reader.tsx - Graph view · Interactive legal entity graph
components/Graph.tsx - Chat · Client-side citation-aware chat panel
components/Chat.tsx - Cost meter · Shows retrieval and token cost impact
components/CostMeter.tsx - Markdown · Renders structured opinion text
components/Markdown.tsx - Bem mark · Formats citations and inline references
components/BemMark.tsx - Help · Assistance and guidance entrypoint
components/HelpButton.tsx - Logo · Application branding element
components/Logo.tsx
Case Data
Bundled opinion corpus and supporting artifacts
- Opinion JSON · Structured opinion sections and text
data/document.json - Case graph · Typed legal entities and relations
data/graph.json - Case meta · Opinion metadata and identifiers
data/meta.json - Economics data · Usage or token economics inputs
data/economics.json - Opinion PDF · Bundled source opinion document
public/opinion.pdf
Libraries
Shared retrieval and accounting helpers
Distribution
SEO and install/share assets
Other components
- AI SDK · Streaming LLM interface
- Bem backend · Structured parsing and retrieval backend
Connections 24
- Main app → Workspace: composes · Main shell renders the coordinated panes
- Layout → Logo: includes · Global shell adds branding
- Layout → Help: includes · Global shell adds help affordance
- Workspace → Reader: shows · Primary opinion reading pane
- Workspace → Graph view: shows · Interactive case graph pane
- Workspace → Chat: shows · Assistant conversation pane
- Workspace → Cost meter: shows · Visible retrieval/cost feedback
- Reader → Opinion JSON: reads · Structured opinion content source
- Reader → Markdown: renders · Text sections are formatted through markdown rendering
- Reader → Bem mark: formats · Citations and references are rendered separately
- Graph view → Case graph: reads · Graph visualization consumes entity graph data
- Graph embed → Graph view: embeds · Dedicated graph-only route
- Chat API → FS tools: retrieves · Selective section access for grounded answers
- Chat API → AI SDK: streams · Server response is streamed through the AI SDK
- Chat API → Economics: tracks · Computes visible cost impact
- Chat API → Opinion JSON: consults · Answers are grounded in the parsed opinion
- Chat API → Case graph: consults · Entity graph can support retrieval or citation context
- Chat API → Bem backend: delegates · External structured retrieval/parsing boundary
- Cost meter → Economics data: displays · Cost meter reflects bundled economics inputs
- Economics → Economics data: uses · Accounting helper consumes data inputs
- Opinion JSON → Opinion PDF: derived from · Parsed corpus originates from the bundled opinion source
- Robots → Sitemap: supports · SEO distribution metadata
- Manifest → Main app: enhances · Installable app surface
- Case meta → Main app: informs · Case metadata informs the main experience