Soma Books Interactive Dashboards

Client: Amina Msangi, Managing Director, Soma Books What you're building: Interactive plotly charts and dual-audience Metabase dashboards for a three-location bookstore chain in Dar es Salaam, Tanzania. Amina wants to explore her sales data interactively. Her store managers need a simpler guided view.

Tech stack

• Python 3.11+ (Miniconda, "analytics" environment)
• DuckDB (data storage and querying)
• Jupyter Notebook (analysis and plotly charts)
• pandas (data manipulation)
• plotly (interactive visualisations)
• Metabase via Docker (persistent dashboards)
• Git / GitHub

File structure

materials/
  soma-books-pos.csv          -- 18 months of POS data, ~42,000 rows
  data-dictionary.md          -- Column definitions and business terminology
  dashboard-design-guide.md   -- Interaction paths, self-service patterns, thresholds
  CLAUDE.md                   -- This file

Key materials

• soma-books-pos.csv -- Transaction-level POS data from three stores (Oyster Bay, Kariakoo, Mikocheni). Categories: Fiction, Non-Fiction, Children's, Stationery, Cafe. 18 months of data.
• data-dictionary.md -- Column definitions for the POS export and business terminology (school partnerships, bulk orders, store names).
• dashboard-design-guide.md -- Design principles for interactive dashboards: interaction paths, exploratory vs guided views, minimum-data-point thresholds, hover label standards.

Work breakdown

1. Data profiling and setup -- Load POS data into DuckDB, profile columns, identify patterns (school bulk order spikes, store differences)
2. Quality assessment and metric definitions -- Assess quality from experience (no template), discover hidden constraints from Amina, define metrics for cross-tool consistency
3. Interactive plotly charts -- Build three interactive charts with drill-downs, human-readable hover labels, minimum-data-point warnings. Use plan mode for decomposition.
4. Metabase dual-audience dashboards -- Exploratory dashboard for Amina (full drill-down) and guided view for store managers (pre-set questions, single-store focus)
5. Client review -- Share with Amina, handle scope creep (author events data -- defer), verify cross-tool metric consistency
6. Project close -- README, commit, push to GitHub, final message to Amina

Verification targets

• Metric consistency: same metric produces same number in plotly, exploratory Metabase, and guided Metabase views
• All plotly hover labels use human-readable names (not raw column names)
• Minimum-data-point warnings appear when filter combinations produce < 20 transactions
• Guided manager view answers "How is my store doing this month?" within 10 seconds of opening
• School bulk orders separated or annotated in trend views
• All interaction paths tested (every store, every category filter, edge cases)

Commit convention

Commit after each meaningful piece of work with descriptive messages explaining what was done and why. Include decision rationale for metric definitions and design choices.