How alokera/crystal-ball-approvals works
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: app.ts Express routes · chat.ts Chat actions · AssistantPanel.tsx Assistant panel · api.ts API client
Components 21
Operator interface
- Approvals dashboard
web/src/components/Dashboard.tsx - Queue table
web/src/components/ApprovalsTable.tsx - Assistant panel
web/src/components/AssistantPanel.tsx - Chat view
web/src/components/ChatView.tsx - Summary view
web/src/components/SummaryView.tsx - Assistant state
web/src/store/assistant.ts - API client
web/src/lib/api.ts - Session ID
web/src/lib/session.ts
API and contracts
- Shared schemas
packages/contracts/src/index.ts - Express routes
server/src/app.ts
Assistant capabilities
- Greeting action
server/src/services/greeting.ts - Summary action
server/src/services/summary.ts - Chat actions
server/src/services/chat.ts - Fallback ranking
server/src/services/rules.ts
Policy and model
- Policy retrieval
server/src/knowledge/retrieval.ts - Approval policy
server/src/knowledge/approval-policy.ts - Prompt registry
server/prompts/index.ts - LLM interface
server/src/llm/types.ts - Anthropic provider
server/src/llm/anthropic.ts
Other components
- Operator
- Claude API
Connections 27
- Operator → Approvals dashboard: uses
- Approvals dashboard → Queue table: renders
web/src/components/Dashboard.tsx - Approvals dashboard → Assistant panel: renders
web/src/components/Dashboard.tsx - Assistant panel → Chat view: renders
web/src/components/AssistantPanel.tsx - Assistant panel → Summary view: renders
web/src/components/AssistantPanel.tsx - Assistant panel → Assistant state: reads and updates
web/src/components/AssistantPanel.tsx - Chat view → Assistant state: uses
web/src/components/ChatView.tsx - Summary view → Assistant state: uses
web/src/components/SummaryView.tsx - API client → Session ID: gets session ID
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
server/src/app.ts - Express routes → Greeting action: calls
server/src/app.ts - Express routes → Summary action: calls
server/src/app.ts - Express routes → Chat actions: streams via
server/src/app.ts - Chat actions → Policy retrieval: retrieves policy
server/src/services/chat.ts - Policy retrieval → Approval policy: chunks and indexes
server/src/knowledge/retrieval.ts - Chat actions → Prompt registry: builds prompt
server/src/services/chat.ts - Chat actions → Fallback ranking: uses fallback
server/src/services/chat.ts - Summary action → Fallback ranking: uses fallback
server/src/services/summary.ts - Greeting action → Fallback ranking: uses fallback
server/src/services/greeting.ts - Chat actions → LLM interface: streams through
server/src/services/chat.ts - Summary action → LLM interface: generates through
server/src/services/summary.ts - Greeting action → LLM interface: generates through
server/src/services/greeting.ts - Anthropic provider → Claude API: calls
- Express routes → Shared schemas: shares schemas
server/src/app.ts