Playbook
Role-Based Onboarding Hub
Coaching-staff hub for choosing the right nbadb route by role, task, and first command.
Role-Based Onboarding Hub
Welcome to the coaching staff room for nbadb. Use this page to pick your role, run the opening drill, and get onto the right page before you burn time wandering the whole playbook.
Quick route board
| Role | First read | First command | Next stop |
|---|---|---|---|
| Contributor | Installation | uv sync --extra dev | CLI Reference |
| Analyst | Getting Started | nbadb download or open nba.duckdb | Analytics Quickstart |
| Data engineer | Daily Updates | nbadb daily | Troubleshooting Playbook |
| Stakeholder | Architecture | nbadb schema | Schema Reference |
If you are not sure where to begin, start with the row that matches the job you need done today, not the title on your org chart.
Pick your lane
Each tab gives you the same scan path:
- Run first to get moving
- Open next so you land on the right follow-up page
- Watch for so the common misses do not cost a second possession
Primary route: Installation → CLI Reference → Architecture
Run first
- Set up the repo-local environment:
uv sync --extra dev - Keep the current command surface nearby in CLI Reference.
- Read Architecture before changing pipeline flow, table families, or generated docs.
Open next
| Route | Why |
|---|---|
| Schema Reference | Understand output naming and table families |
| Data Lineage | Trace a transform back upstream |
uv run nbadb docs-autogen --docs-root docs/content/docs | Regenerate generator-owned docs after schema changes |
Watch for
- Generator-owned docs should be regenerated, not hand-edited.
- Underscore-prefixed pipeline tables are internal operational state, not part of the public analytical contract.
- If CI or artifacts fail, jump to the Troubleshooting Playbook.
Primary route: Getting Started → Analytics Quickstart → DuckDB Query Examples
Run first
- Seed a local dataset:
nbadb downloadnba.duckdb/ Parquet export. - Start with
analytics_*surfaces for the fastest first query. - Move into the table-level docs only after you know the question you want to answer.
Open next
| Route | Why |
|---|---|
| DuckDB Query Examples | SQL-first scouting packet |
| Player Comparison | Head-to-head analysis patterns |
| Shot Chart Analysis | Court-map and zone work |
| Parquet Usage | Polars, Pandas, and Arrow workflows |
Watch for
- Keep
season_yearandseason_typeexplicit so repeated analysis stays comparable. - DuckDB is the fastest first possession for joins; Parquet is the cleaner handoff when the rest of the workflow is DataFrame-first.
Primary route: Daily Updates → CLI Reference → Kaggle Setup
Run first
- Review what each run mode actually does:
daily,monthly,full,status,run-quality. - Confirm your data directory and output expectations.
- Keep the latest health artifacts in view:
artifacts/health/daily/dependency-inventory.jsonartifacts/health/daily/data-quality-report.jsonartifacts/endpoint-coverage/*
Open next
| Route | Why |
|---|---|
| Pipeline Flow | Share a stage map quickly |
| Architecture | Review validation tiers, internal state, and run-mode boundaries |
| Kaggle Setup | Handle dataset handoff and publish flow |
Watch for
daily,monthly, andfullend by rebuilding downstream tables inreplacemode.- A single
Ctrl+Cis the graceful stop; a second interrupt forces exit. - When something breaks, start with the exact artifact or command named in the failure message.
Primary route: Architecture → Schema Reference → ER Diagram
Run first
- Read Architecture for the source-to-export story.
- Scan Schema Reference to understand what the public dataset actually contains.
- Review Kaggle Setup when the conversation shifts to distribution and delivery.
Open next
| Route | Why |
|---|---|
| ER Diagram | Fast visual schema read |
| Endpoint Map | Source-coverage conversations |
| Strategic Shift Rollout | Planned migration sequencing |
Watch for
- The public analytical contract is the star/analytics surface, not the underscore-prefixed internal pipeline tables.
- Use this hub as the handoff page for new teammates entering the rotation.
Keep moving
Stay in the same possession
Keep the mental model warm with adjacent pages, section hubs, and search-friendly routes into the same topic cluster.
Analytics Quickstart
Land quick wins fast and move from setup to analysis with intent.
Shot Chart Analysis
Lean into basketball-native visual storytelling on one of the best-fit pages.
Visual Asset Prompt Pack
Generate hero art, OG cards, icons, and texture systems without losing the docs identity.