# bem-team/docket architecture

> Architecture diagram of the GitHub repository bem-team/docket, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bem-team/docket
- Repository: https://github.com/bem-team/docket

## Overview

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: [`app/api/chat/route.ts`](https://github.com/bem-team/docket/blob/main/app/api/chat/route.ts) (Chat API), [`components/Workspace.tsx`](https://github.com/bem-team/docket/blob/main/components/Workspace.tsx) (Workspace), [`components/Reader.tsx`](https://github.com/bem-team/docket/blob/main/components/Reader.tsx) (Reader), [`app/page.tsx`](https://github.com/bem-team/docket/blob/main/app/page.tsx) (Main app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app_router["App Router"]
  node_app_page["Main app<br/>Next.js page<br/>[page.tsx]"]
  node_app_embed_graph_page["Graph embed<br/>Next.js page<br/>[page.tsx]"]
  node_app_chat_route["Chat API<br/>Server route<br/>[route.ts]"]
  node_app_layout["Layout<br/>App shell<br/>[layout.tsx]"]
end

subgraph group_ui["UI"]
  node_workspace["Workspace<br/>Composer<br/>[Workspace.tsx]"]
  node_reader["Reader<br/>Opinion viewer<br/>[Reader.tsx]"]
  node_graph_view(("Graph view<br/>Entity graph<br/>[Graph.tsx]"))
  node_chat_ui["Chat<br/>Assistant UI<br/>[Chat.tsx]"]
  node_cost_meter["Cost meter<br/>Usage meter<br/>[CostMeter.tsx]"]
  node_markdown["Markdown<br/>Text renderer<br/>[Markdown.tsx]"]
  node_bem_mark["Bem mark<br/>Reference renderer<br/>[BemMark.tsx]"]
  node_help_button(("Help<br/>UI chrome<br/>[HelpButton.tsx]"))
  node_logo(("Logo<br/>Brand chrome<br/>[Logo.tsx]"))
end

subgraph group_data["Case Data"]
  node_document_json["Opinion JSON<br/>Parsed document<br/>[document.json]"]
  node_graph_json[("Case graph<br/>Entity graph data<br/>[graph.json]")]
  node_meta_json["Case meta<br/>[meta.json]"]
  node_economics_json["Economics data<br/>Cost data<br/>[economics.json]"]
  node_opinion_pdf["Opinion PDF<br/>Source artifact<br/>[opinion.pdf]"]
end

subgraph group_lib["Libraries"]
  node_fs_tools["FS tools<br/>Retrieval helper<br/>[fs-tools.ts]"]
  node_economics_lib["Economics<br/>Accounting helper<br/>[economics.ts]"]
end

subgraph group_distribution["Distribution"]
  node_robots["Robots<br/>SEO metadata<br/>[robots.ts]"]
  node_sitemap["Sitemap<br/>SEO metadata<br/>[sitemap.ts]"]
  node_manifest["Manifest"]
end

node_vercel_ai{{"AI SDK<br/>External runtime"}}
node_bem_backend{{"Bem backend<br/>External service"}}

node_app_page -->|"composes"| node_workspace
node_app_layout -->|"includes"| node_logo
node_app_layout -->|"includes"| node_help_button
node_workspace -->|"shows"| node_reader
node_workspace -->|"shows"| node_graph_view
node_workspace -->|"shows"| node_chat_ui
node_workspace -->|"shows"| node_cost_meter
node_reader -->|"reads"| node_document_json
node_reader -->|"renders"| node_markdown
node_reader -->|"formats"| node_bem_mark
node_graph_view -->|"reads"| node_graph_json
node_app_embed_graph_page -->|"embeds"| node_graph_view
node_app_chat_route -->|"retrieves"| node_fs_tools
node_app_chat_route -->|"streams"| node_vercel_ai
node_app_chat_route -->|"tracks"| node_economics_lib
node_app_chat_route -->|"consults"| node_document_json
node_app_chat_route -->|"consults"| node_graph_json
node_app_chat_route -.->|"delegates"| node_bem_backend
node_cost_meter -->|"displays"| node_economics_json
node_economics_lib -->|"uses"| node_economics_json
node_document_json -->|"derived from"| node_opinion_pdf
node_robots -.->|"supports"| node_sitemap
node_manifest -.->|"enhances"| node_app_page
node_meta_json -->|"informs"| node_app_page

click node_app_page "https://github.com/bem-team/docket/blob/main/app/page.tsx"
click node_app_embed_graph_page "https://github.com/bem-team/docket/blob/main/app/embed/graph/page.tsx"
click node_app_chat_route "https://github.com/bem-team/docket/blob/main/app/api/chat/route.ts"
click node_app_layout "https://github.com/bem-team/docket/blob/main/app/layout.tsx"
click node_workspace "https://github.com/bem-team/docket/blob/main/components/Workspace.tsx"
click node_reader "https://github.com/bem-team/docket/blob/main/components/Reader.tsx"
click node_graph_view "https://github.com/bem-team/docket/blob/main/components/Graph.tsx"
click node_chat_ui "https://github.com/bem-team/docket/blob/main/components/Chat.tsx"
click node_cost_meter "https://github.com/bem-team/docket/blob/main/components/CostMeter.tsx"
click node_markdown "https://github.com/bem-team/docket/blob/main/components/Markdown.tsx"
click node_bem_mark "https://github.com/bem-team/docket/blob/main/components/BemMark.tsx"
click node_help_button "https://github.com/bem-team/docket/blob/main/components/HelpButton.tsx"
click node_logo "https://github.com/bem-team/docket/blob/main/components/Logo.tsx"
click node_document_json "https://github.com/bem-team/docket/blob/main/data/document.json"
click node_graph_json "https://github.com/bem-team/docket/blob/main/data/graph.json"
click node_meta_json "https://github.com/bem-team/docket/blob/main/data/meta.json"
click node_economics_json "https://github.com/bem-team/docket/blob/main/data/economics.json"
click node_opinion_pdf "https://github.com/bem-team/docket/blob/main/public/opinion.pdf"
click node_fs_tools "https://github.com/bem-team/docket/blob/main/lib/fs-tools.ts"
click node_economics_lib "https://github.com/bem-team/docket/blob/main/lib/economics.ts"
click node_robots "https://github.com/bem-team/docket/blob/main/app/robots.ts"
click node_sitemap "https://github.com/bem-team/docket/blob/main/app/sitemap.ts"
click node_manifest "https://github.com/bem-team/docket/blob/main/public/manifest.webmanifest"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_page,node_app_embed_graph_page,node_app_chat_route,node_app_layout toneBlue
class node_workspace,node_reader,node_graph_view,node_chat_ui,node_cost_meter,node_markdown,node_bem_mark,node_help_button,node_logo toneAmber
class node_document_json,node_graph_json,node_meta_json,node_economics_json,node_opinion_pdf toneMint
class node_fs_tools,node_economics_lib toneRose
class node_robots,node_sitemap,node_manifest toneIndigo
class node_vercel_ai,node_bem_backend toneNeutral
```

## Components

### App Router

Next.js entrypoints and server routes

- [Main app](https://github.com/bem-team/docket/blob/main/app/page.tsx): Next.js page · Primary three-pane product shell · `app/page.tsx`
- [Graph embed](https://github.com/bem-team/docket/blob/main/app/embed/graph/page.tsx): Next.js page · Focused embeddable graph view · `app/embed/graph/page.tsx`
- [Chat API](https://github.com/bem-team/docket/blob/main/app/api/chat/route.ts): Server route · Streams grounded assistant responses · `app/api/chat/route.ts`
- [Layout](https://github.com/bem-team/docket/blob/main/app/layout.tsx): App shell · Global document and app chrome · `app/layout.tsx`

### UI

Reader, graph, chat, and page composition

- [Workspace](https://github.com/bem-team/docket/blob/main/components/Workspace.tsx): Composer · Coordinates reader, graph, and chat panes · `components/Workspace.tsx`
- [Reader](https://github.com/bem-team/docket/blob/main/components/Reader.tsx): Opinion viewer · Structured case reading surface · `components/Reader.tsx`
- [Graph view](https://github.com/bem-team/docket/blob/main/components/Graph.tsx): Entity graph · Interactive legal entity graph · `components/Graph.tsx`
- [Chat](https://github.com/bem-team/docket/blob/main/components/Chat.tsx): Assistant UI · Client-side citation-aware chat panel · `components/Chat.tsx`
- [Cost meter](https://github.com/bem-team/docket/blob/main/components/CostMeter.tsx): Usage meter · Shows retrieval and token cost impact · `components/CostMeter.tsx`
- [Markdown](https://github.com/bem-team/docket/blob/main/components/Markdown.tsx): Text renderer · Renders structured opinion text · `components/Markdown.tsx`
- [Bem mark](https://github.com/bem-team/docket/blob/main/components/BemMark.tsx): Reference renderer · Formats citations and inline references · `components/BemMark.tsx`
- [Help](https://github.com/bem-team/docket/blob/main/components/HelpButton.tsx): UI chrome · Assistance and guidance entrypoint · `components/HelpButton.tsx`
- [Logo](https://github.com/bem-team/docket/blob/main/components/Logo.tsx): Brand chrome · Application branding element · `components/Logo.tsx`

### Case Data

Bundled opinion corpus and supporting artifacts

- [Opinion JSON](https://github.com/bem-team/docket/blob/main/data/document.json): Parsed document · Structured opinion sections and text · `data/document.json`
- [Case graph](https://github.com/bem-team/docket/blob/main/data/graph.json): Entity graph data · Typed legal entities and relations · `data/graph.json`
- [Case meta](https://github.com/bem-team/docket/blob/main/data/meta.json): Case metadata · Opinion metadata and identifiers · `data/meta.json`
- [Economics data](https://github.com/bem-team/docket/blob/main/data/economics.json): Cost data · Usage or token economics inputs · `data/economics.json`
- [Opinion PDF](https://github.com/bem-team/docket/blob/main/public/opinion.pdf): Source artifact · Bundled source opinion document · `public/opinion.pdf`

### Libraries

Shared retrieval and accounting helpers

- [FS tools](https://github.com/bem-team/docket/blob/main/lib/fs-tools.ts): Retrieval helper · File-system style section access · `lib/fs-tools.ts`
- [Economics](https://github.com/bem-team/docket/blob/main/lib/economics.ts): Accounting helper · Cost and usage calculations · `lib/economics.ts`

### Distribution

SEO and install/share assets

- [Robots](https://github.com/bem-team/docket/blob/main/app/robots.ts): SEO metadata · Crawler directives · `app/robots.ts`
- [Sitemap](https://github.com/bem-team/docket/blob/main/app/sitemap.ts): SEO metadata · Site index for crawlers · `app/sitemap.ts`
- [Manifest](https://github.com/bem-team/docket/blob/main/public/manifest.webmanifest): PWA manifest · Installability metadata · `public/manifest.webmanifest`

### Other components

- **AI SDK**: External runtime · Streaming LLM interface
- **Bem backend**: External service · Structured parsing and retrieval backend

## Connections

- 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
