# allenwalker3/playcall architecture

> Architecture diagram of the GitHub repository allenwalker3/playcall, 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/allenwalker3/playcall
- Repository: https://github.com/allenwalker3/playcall

## Overview

playcall is a natural-language NFL play-by-play analytics application. A user asks a question in the chat UI; the backend builds context for an LLM, dispatches its tool calls, and returns a streamed answer. The main query stages are player lookup, column discovery, and SQL execution against DuckDB views over parquet data. The product also includes data synchronization, provider/model and settings controls, and an optional evaluation workflow. Relationships for unsampled modules are limited to those identified by the source index or README.

Main entry points: [`frontend/src/lib/api.js`](https://github.com/allenwalker3/playcall/blob/main/frontend/src/lib/api.js) (API client), [`backend/app.py`](https://github.com/allenwalker3/playcall/blob/main/backend/app.py) (Chat API), [`backend/db.py`](https://github.com/allenwalker3/playcall/blob/main/backend/db.py) (DuckDB views), [`frontend/src/App.jsx`](https://github.com/allenwalker3/playcall/blob/main/frontend/src/App.jsx) (Chat interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web interface"]
  node_app_ui["Chat interface<br/>[App.jsx]"]
  node_chat_hook["Chat state<br/>[useChat.js]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_service["Chat service"]
  node_chat_api["Chat API<br/>[app.py]"]
  node_prompt["Prompt builder<br/>[system_prompt.py]"]
  node_provider["LLM providers<br/>[base.py]"]
  node_ollama["Ollama adapter<br/>[ollama.py]"]
  node_openai["OpenAI adapter<br/>[openai.py]"]
  node_anthropic["Anthropic adapter<br/>[anthropic.py]"]
end

subgraph group_query["Query and data"]
  node_registry["Tool dispatcher<br/>[registry.py]"]
  node_player_lookup["Player search<br/>[players.py]"]
  node_column_search["Column search<br/>[columns.py]"]
  node_sql_tool["SQL execution<br/>[sql.py]"]
  node_duckdb[("DuckDB views<br/>[db.py]")]
  node_schema["Curated schema<br/>[pbp_curated.py]"]
end

subgraph group_ops["Data and settings"]
  node_data_ui["Data sync UI<br/>[SyncModal.jsx]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_ui["Evaluation UI<br/>[EvalView.jsx]"]
  node_eval_hook["Evaluation state<br/>[useEval.js]"]
  node_eval_api["Evaluation API<br/>[app.py]"]
  node_eval_runner["Evaluation runner<br/>[runner.py]"]
  node_eval_cases["Evaluation cases<br/>[cases.py]"]
end

node_user(("Question asker"))
node_llm_service(("Language model"))
node_parquet[("NFL parquet data")]

node_user -->|"asks"| node_app_ui
node_app_ui -->|"uses"| node_chat_hook
node_chat_hook -->|"streams chat"| node_api_client
node_api_client -->|"posts messages"| node_chat_api
node_chat_api -->|"builds context"| node_prompt
node_chat_api -->|"requests completion"| node_provider
node_chat_api -->|"dispatches tools"| node_registry
node_provider -.->|"implemented by"| node_ollama
node_provider -.->|"implemented by"| node_openai
node_provider -.->|"implemented by"| node_anthropic
node_ollama -.->|"calls"| node_llm_service
node_openai -.->|"calls"| node_llm_service
node_anthropic -.->|"calls"| node_llm_service
node_registry -->|"dispatches"| node_player_lookup
node_registry -->|"dispatches"| node_column_search
node_registry -->|"dispatches"| node_sql_tool
node_player_lookup -->|"queries"| node_duckdb
node_column_search -->|"reads columns"| node_duckdb
node_sql_tool -->|"executes SQL"| node_duckdb
node_duckdb -->|"reads"| node_parquet
node_prompt -->|"renders schema"| node_schema
node_prompt -->|"gets columns"| node_duckdb
node_app_ui -->|"opens sync"| node_data_ui
node_data_ui -->|"requests sync"| node_api_client
node_api_client -.->|"calls data endpoints"| node_chat_api
node_app_ui -->|"shows evaluation"| node_eval_ui
node_eval_ui -->|"uses"| node_eval_hook
node_eval_hook -->|"streams evaluation"| node_api_client
node_api_client -->|"posts evaluation"| node_eval_api
node_eval_api -->|"runs cases"| node_eval_runner
node_eval_runner -->|"scores"| node_eval_cases
node_eval_runner -->|"streams chat requests"| node_chat_api

click node_app_ui "https://github.com/allenwalker3/playcall/blob/main/frontend/src/App.jsx"
click node_chat_hook "https://github.com/allenwalker3/playcall/blob/main/frontend/src/hooks/useChat.js"
click node_api_client "https://github.com/allenwalker3/playcall/blob/main/frontend/src/lib/api.js"
click node_chat_api "https://github.com/allenwalker3/playcall/blob/main/backend/app.py"
click node_prompt "https://github.com/allenwalker3/playcall/blob/main/backend/schema/system_prompt.py"
click node_provider "https://github.com/allenwalker3/playcall/blob/main/backend/llm/base.py"
click node_ollama "https://github.com/allenwalker3/playcall/blob/main/backend/llm/ollama.py"
click node_openai "https://github.com/allenwalker3/playcall/blob/main/backend/llm/openai.py"
click node_anthropic "https://github.com/allenwalker3/playcall/blob/main/backend/llm/anthropic.py"
click node_registry "https://github.com/allenwalker3/playcall/blob/main/backend/tools/registry.py"
click node_player_lookup "https://github.com/allenwalker3/playcall/blob/main/backend/tools/players.py"
click node_column_search "https://github.com/allenwalker3/playcall/blob/main/backend/tools/columns.py"
click node_sql_tool "https://github.com/allenwalker3/playcall/blob/main/backend/tools/sql.py"
click node_duckdb "https://github.com/allenwalker3/playcall/blob/main/backend/db.py"
click node_schema "https://github.com/allenwalker3/playcall/blob/main/backend/schema/pbp_curated.py"
click node_data_ui "https://github.com/allenwalker3/playcall/blob/main/frontend/src/components/SyncModal.jsx"
click node_eval_ui "https://github.com/allenwalker3/playcall/blob/main/frontend/src/components/EvalView.jsx"
click node_eval_hook "https://github.com/allenwalker3/playcall/blob/main/frontend/src/hooks/useEval.js"
click node_eval_api "https://github.com/allenwalker3/playcall/blob/main/backend/app.py"
click node_eval_runner "https://github.com/allenwalker3/playcall/blob/main/eval/runner.py"
click node_eval_cases "https://github.com/allenwalker3/playcall/blob/main/eval/cases.py"

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_ui,node_chat_hook,node_api_client toneBlue
class node_chat_api,node_prompt,node_provider,node_ollama,node_openai,node_anthropic,node_parquet toneAmber
class node_registry,node_player_lookup,node_column_search,node_sql_tool,node_duckdb,node_schema toneMint
class node_data_ui toneRose
class node_eval_ui,node_eval_hook,node_eval_api,node_eval_runner,node_eval_cases,node_user,node_llm_service toneIndigo
```

## Components

### Web interface

- [Chat interface](https://github.com/allenwalker3/playcall/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Chat state](https://github.com/allenwalker3/playcall/blob/main/frontend/src/hooks/useChat.js): `frontend/src/hooks/useChat.js`
- [API client](https://github.com/allenwalker3/playcall/blob/main/frontend/src/lib/api.js): `frontend/src/lib/api.js`

### Chat service

- [Chat API](https://github.com/allenwalker3/playcall/blob/main/backend/app.py): `backend/app.py`
- [Prompt builder](https://github.com/allenwalker3/playcall/blob/main/backend/schema/system_prompt.py): `backend/schema/system_prompt.py`
- [LLM providers](https://github.com/allenwalker3/playcall/blob/main/backend/llm/base.py): `backend/llm/base.py`
- [Ollama adapter](https://github.com/allenwalker3/playcall/blob/main/backend/llm/ollama.py): `backend/llm/ollama.py`
- [OpenAI adapter](https://github.com/allenwalker3/playcall/blob/main/backend/llm/openai.py): `backend/llm/openai.py`
- [Anthropic adapter](https://github.com/allenwalker3/playcall/blob/main/backend/llm/anthropic.py): `backend/llm/anthropic.py`

### Query and data

- [Tool dispatcher](https://github.com/allenwalker3/playcall/blob/main/backend/tools/registry.py): `backend/tools/registry.py`
- [Player search](https://github.com/allenwalker3/playcall/blob/main/backend/tools/players.py): `backend/tools/players.py`
- [Column search](https://github.com/allenwalker3/playcall/blob/main/backend/tools/columns.py): `backend/tools/columns.py`
- [SQL execution](https://github.com/allenwalker3/playcall/blob/main/backend/tools/sql.py): `backend/tools/sql.py`
- [DuckDB views](https://github.com/allenwalker3/playcall/blob/main/backend/db.py): `backend/db.py`
- [Curated schema](https://github.com/allenwalker3/playcall/blob/main/backend/schema/pbp_curated.py): `backend/schema/pbp_curated.py`

### Data and settings

- [Data sync UI](https://github.com/allenwalker3/playcall/blob/main/frontend/src/components/SyncModal.jsx): `frontend/src/components/SyncModal.jsx`

### Evaluation

- [Evaluation UI](https://github.com/allenwalker3/playcall/blob/main/frontend/src/components/EvalView.jsx): `frontend/src/components/EvalView.jsx`
- [Evaluation state](https://github.com/allenwalker3/playcall/blob/main/frontend/src/hooks/useEval.js): `frontend/src/hooks/useEval.js`
- [Evaluation API](https://github.com/allenwalker3/playcall/blob/main/backend/app.py): `backend/app.py`
- [Evaluation runner](https://github.com/allenwalker3/playcall/blob/main/eval/runner.py): `eval/runner.py`
- [Evaluation cases](https://github.com/allenwalker3/playcall/blob/main/eval/cases.py): `eval/cases.py`

### Other components

- **Question asker**
- **Language model**
- **NFL parquet data**

## Connections

- Question asker → Chat interface: asks (evidence: `README.md`)
- Chat interface → Chat state: uses (evidence: `frontend/src/App.jsx`)
- Chat state → API client: streams chat (evidence: `frontend/src/hooks/useChat.js`)
- API client → Chat API: posts messages (evidence: `frontend/src/lib/api.js`)
- Chat API → Prompt builder: builds context (evidence: `backend/app.py`)
- Chat API → LLM providers: requests completion (evidence: `backend/app.py`)
- Chat API → Tool dispatcher: dispatches tools (evidence: `backend/app.py`)
- LLM providers → Ollama adapter: implemented by (evidence: `backend/llm/ollama.py`)
- LLM providers → OpenAI adapter: implemented by (evidence: `backend/llm/openai.py`)
- LLM providers → Anthropic adapter: implemented by (evidence: `backend/llm/anthropic.py`)
- Ollama adapter → Language model: calls
- OpenAI adapter → Language model: calls
- Anthropic adapter → Language model: calls
- Tool dispatcher → Player search: dispatches (evidence: `backend/tools/registry.py`)
- Tool dispatcher → Column search: dispatches (evidence: `backend/tools/registry.py`)
- Tool dispatcher → SQL execution: dispatches (evidence: `backend/tools/registry.py`)
- Player search → DuckDB views: queries (evidence: `backend/tools/players.py`)
- Column search → DuckDB views: reads columns (evidence: `backend/tools/columns.py`)
- SQL execution → DuckDB views: executes SQL (evidence: `backend/tools/sql.py`)
- DuckDB views → NFL parquet data: reads (evidence: `backend/db.py`)
- Prompt builder → Curated schema: renders schema (evidence: `backend/schema/system_prompt.py`)
- Prompt builder → DuckDB views: gets columns (evidence: `backend/schema/system_prompt.py`)
- Chat interface → Data sync UI: opens sync (evidence: `frontend/src/App.jsx`)
- Data sync UI → API client: requests sync (evidence: `frontend/src/components/SyncModal.jsx`)
- API client → Chat API: calls data endpoints
- Chat interface → Evaluation UI: shows evaluation (evidence: `frontend/src/App.jsx`)
- Evaluation UI → Evaluation state: uses (evidence: `frontend/src/components/EvalView.jsx`)
- Evaluation state → API client: streams evaluation (evidence: `frontend/src/hooks/useEval.js`)
- API client → Evaluation API: posts evaluation (evidence: `frontend/src/lib/api.js`)
- Evaluation API → Evaluation runner: runs cases (evidence: `backend/app.py`)
- Evaluation runner → Evaluation cases: scores (evidence: `eval/runner.py`)
- Evaluation runner → Chat API: streams chat requests (evidence: `eval/runner.py`)
