# alokera/crystal-ball-approvals architecture

> Architecture diagram of the GitHub repository alokera/crystal-ball-approvals, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alokera/crystal-ball-approvals
- Repository: https://github.com/alokera/crystal-ball-approvals

## Overview

Crystal Ball is an approvals assistant: operators view a seeded approvals queue and use a panel for a greeting, prioritized summary, conversational help, policy guidance, or a walkthrough. The web client communicates with an Express API; the server validates requests, calls Claude where appropriate, and provides deterministic fallbacks. The README documents the overall HTTP/SSE and shared-contract flow. Source excerpts show route ownership and chat’s retrieval, prompt, timeout, and fallback behavior; connections for unsampled service internals are included only where the README documents them.

Main entry points: [`server/src/app.ts`](https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/app.ts) (Express routes), [`server/src/services/chat.ts`](https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/services/chat.ts) (Chat actions), [`web/src/components/AssistantPanel.tsx`](https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/components/AssistantPanel.tsx) (Assistant panel), [`web/src/lib/api.ts`](https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Operator interface"]
  node_dashboard["Approvals dashboard<br/>[Dashboard.tsx]"]
  node_queue_view["Queue table<br/>[ApprovalsTable.tsx]"]
  node_panel["Assistant panel<br/>[AssistantPanel.tsx]"]
  node_chat_view["Chat view<br/>[ChatView.tsx]"]
  node_summary_view["Summary view<br/>[SummaryView.tsx]"]
  node_ui_state["Assistant state<br/>[assistant.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_session["Session ID<br/>[session.ts]"]
end

subgraph group_api["API and contracts"]
  node_contracts["Shared schemas<br/>[index.ts]"]
  node_express_api["Express routes<br/>[app.ts]"]
end

subgraph group_assistant["Assistant capabilities"]
  node_greeting["Greeting action<br/>[greeting.ts]"]
  node_summary["Summary action<br/>[summary.ts]"]
  node_chat["Chat actions<br/>[chat.ts]"]
  node_rules["Fallback ranking<br/>[rules.ts]"]
end

subgraph group_knowledge["Policy and model"]
  node_retrieval["Policy retrieval<br/>[retrieval.ts]"]
  node_policy["Approval policy<br/>[approval-policy.ts]"]
  node_prompts["Prompt registry<br/>[index.ts]"]
  node_llm_client["LLM interface<br/>[types.ts]"]
  node_anthropic["Anthropic provider<br/>[anthropic.ts]"]
end

node_operator(("Operator"))
node_claude(("Claude API"))

node_operator -->|"uses"| node_dashboard
node_dashboard -->|"renders"| node_queue_view
node_dashboard -->|"renders"| node_panel
node_panel -->|"renders"| node_chat_view
node_panel -->|"renders"| node_summary_view
node_panel -->|"reads and updates"| node_ui_state
node_chat_view -->|"uses"| node_ui_state
node_summary_view -->|"uses"| node_ui_state
node_api_client -->|"gets session ID"| node_session
node_operator -->|"requests actions"| node_api_client
node_api_client -->|"HTTP and SSE"| node_express_api
node_ui_state -.->|"requests data"| node_api_client
node_contracts -->|"validates requests"| node_express_api
node_express_api -->|"calls"| node_greeting
node_express_api -->|"calls"| node_summary
node_express_api -->|"streams via"| node_chat
node_chat -->|"retrieves policy"| node_retrieval
node_retrieval -->|"chunks and indexes"| node_policy
node_chat -->|"builds prompt"| node_prompts
node_chat -->|"uses fallback"| node_rules
node_summary -->|"uses fallback"| node_rules
node_greeting -->|"uses fallback"| node_rules
node_chat -->|"streams through"| node_llm_client
node_summary -->|"generates through"| node_llm_client
node_greeting -->|"generates through"| node_llm_client
node_anthropic -->|"calls"| node_claude
node_express_api -->|"shares schemas"| node_contracts

click node_dashboard "https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/components/Dashboard.tsx"
click node_queue_view "https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/components/ApprovalsTable.tsx"
click node_panel "https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/components/AssistantPanel.tsx"
click node_chat_view "https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/components/ChatView.tsx"
click node_summary_view "https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/components/SummaryView.tsx"
click node_ui_state "https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/store/assistant.ts"
click node_api_client "https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/lib/api.ts"
click node_session "https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/lib/session.ts"
click node_contracts "https://github.com/alokera/crystal-ball-approvals/blob/main/packages/contracts/src/index.ts"
click node_express_api "https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/app.ts"
click node_greeting "https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/services/greeting.ts"
click node_summary "https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/services/summary.ts"
click node_chat "https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/services/chat.ts"
click node_rules "https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/services/rules.ts"
click node_retrieval "https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/knowledge/retrieval.ts"
click node_policy "https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/knowledge/approval-policy.ts"
click node_prompts "https://github.com/alokera/crystal-ball-approvals/blob/main/server/prompts/index.ts"
click node_llm_client "https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/llm/types.ts"
click node_anthropic "https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/llm/anthropic.ts"

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_dashboard,node_queue_view,node_panel,node_chat_view,node_summary_view,node_ui_state,node_api_client,node_session toneBlue
class node_contracts,node_express_api toneAmber
class node_greeting,node_summary,node_chat,node_rules,node_claude toneMint
class node_retrieval,node_policy,node_prompts,node_llm_client,node_anthropic toneRose
class node_operator toneIndigo
```

## Components

### Operator interface

- [Approvals dashboard](https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/components/Dashboard.tsx): `web/src/components/Dashboard.tsx`
- [Queue table](https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/components/ApprovalsTable.tsx): `web/src/components/ApprovalsTable.tsx`
- [Assistant panel](https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/components/AssistantPanel.tsx): `web/src/components/AssistantPanel.tsx`
- [Chat view](https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/components/ChatView.tsx): `web/src/components/ChatView.tsx`
- [Summary view](https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/components/SummaryView.tsx): `web/src/components/SummaryView.tsx`
- [Assistant state](https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/store/assistant.ts): `web/src/store/assistant.ts`
- [API client](https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`
- [Session ID](https://github.com/alokera/crystal-ball-approvals/blob/main/web/src/lib/session.ts): `web/src/lib/session.ts`

### API and contracts

- [Shared schemas](https://github.com/alokera/crystal-ball-approvals/blob/main/packages/contracts/src/index.ts): `packages/contracts/src/index.ts`
- [Express routes](https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/app.ts): `server/src/app.ts`

### Assistant capabilities

- [Greeting action](https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/services/greeting.ts): `server/src/services/greeting.ts`
- [Summary action](https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/services/summary.ts): `server/src/services/summary.ts`
- [Chat actions](https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/services/chat.ts): `server/src/services/chat.ts`
- [Fallback ranking](https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/services/rules.ts): `server/src/services/rules.ts`

### Policy and model

- [Policy retrieval](https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/knowledge/retrieval.ts): `server/src/knowledge/retrieval.ts`
- [Approval policy](https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/knowledge/approval-policy.ts): `server/src/knowledge/approval-policy.ts`
- [Prompt registry](https://github.com/alokera/crystal-ball-approvals/blob/main/server/prompts/index.ts): `server/prompts/index.ts`
- [LLM interface](https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/llm/types.ts): `server/src/llm/types.ts`
- [Anthropic provider](https://github.com/alokera/crystal-ball-approvals/blob/main/server/src/llm/anthropic.ts): `server/src/llm/anthropic.ts`

### Other components

- **Operator**
- **Claude API**

## Connections

- Operator → Approvals dashboard: uses
- Approvals dashboard → Queue table: renders (evidence: `web/src/components/Dashboard.tsx`)
- Approvals dashboard → Assistant panel: renders (evidence: `web/src/components/Dashboard.tsx`)
- Assistant panel → Chat view: renders (evidence: `web/src/components/AssistantPanel.tsx`)
- Assistant panel → Summary view: renders (evidence: `web/src/components/AssistantPanel.tsx`)
- Assistant panel → Assistant state: reads and updates (evidence: `web/src/components/AssistantPanel.tsx`)
- Chat view → Assistant state: uses (evidence: `web/src/components/ChatView.tsx`)
- Summary view → Assistant state: uses (evidence: `web/src/components/SummaryView.tsx`)
- API client → Session ID: gets session ID (evidence: `web/src/lib/api.ts`)
- Operator → API client: requests actions
- API client → Express routes: HTTP and SSE
- Assistant state → API client: requests data
- Shared schemas → Express routes: validates requests (evidence: `server/src/app.ts`)
- Express routes → Greeting action: calls (evidence: `server/src/app.ts`)
- Express routes → Summary action: calls (evidence: `server/src/app.ts`)
- Express routes → Chat actions: streams via (evidence: `server/src/app.ts`)
- Chat actions → Policy retrieval: retrieves policy (evidence: `server/src/services/chat.ts`)
- Policy retrieval → Approval policy: chunks and indexes (evidence: `server/src/knowledge/retrieval.ts`)
- Chat actions → Prompt registry: builds prompt (evidence: `server/src/services/chat.ts`)
- Chat actions → Fallback ranking: uses fallback (evidence: `server/src/services/chat.ts`)
- Summary action → Fallback ranking: uses fallback (evidence: `server/src/services/summary.ts`)
- Greeting action → Fallback ranking: uses fallback (evidence: `server/src/services/greeting.ts`)
- Chat actions → LLM interface: streams through (evidence: `server/src/services/chat.ts`)
- Summary action → LLM interface: generates through (evidence: `server/src/services/summary.ts`)
- Greeting action → LLM interface: generates through (evidence: `server/src/services/greeting.ts`)
- Anthropic provider → Claude API: calls
- Express routes → Shared schemas: shares schemas (evidence: `server/src/app.ts`)
