# alivedata Brand Docs

Brand assets, product brochure system, and design documentation for Alivedata (AUST) Pty Ltd.

## What's in this repo

| Asset | Path |
|---|---|
| **Interactive presentation** | `alivedata_202603_from_attendance_to_behaviour.html` |
| **Product brochure template** | `template_product_brochure.html` |
| **Brand guidelines** (HTML + PDF) | `docs/brand_guidlines/` |
| **AI / coding rules** | `docs/ai_rules/` (9 documents) |
| **Amazon Q rules** | `.amazonq/rules/rules.md` |
| **Presentation deployment guide** | `docs/presentations/DEPLOYMENT.md` |
| **Brochure deployment guide** | `docs/product_sheet/DEPLOYMENT.md` |
| **Parquet validator** | `scripts/python/check_parquet.py` |
| **DuckDB column profiler** | `scripts/sql/exact_summarize.sql` |
| **Root cause notes** | `scripts/root_cause/` |
| **Project config** | `config/settings.yaml` |
| **Python project** | `pyproject.toml` (Poetry, Python 3.12) |
| **Cloudflare Pages deploy dir** | `dist/` (gitignored build artifact) |

## Interactive presentations

| Presentation | Slides | Live map layers | Source data |
|---|---|---|---|
| From attendance to behaviour, at scale | 8 | Kepler.gl (slide 2) · deck.gl ArcLayer (slide 4) | Eels v Roosters · CommBank Stadium · 23 Aug 2025 |

Deploy to Cloudflare Pages → see **[`docs/presentations/DEPLOYMENT.md`](docs/presentations/DEPLOYMENT.md)**

## Completed product sheets

| Product | HTML | PDF | Project |
|---|---|---|---|
| alivedata Spine 202605 | `documentation/product_sheet/` | same folder | `alivedata_spine_202605/` |
| alivedata Auto Insights 202605 | `reports/product_sheet/` | same folder | `auto_insights_202605/` |

## Creating a new product brochure

See **[`docs/product_sheet/DEPLOYMENT.md`](docs/product_sheet/DEPLOYMENT.md)** for the full step-by-step guide.

Quick summary:

```bash
# 1. Copy template and PDF script into the product project
cp template_product_brochure.html /path/to/<product>/reports/product_sheet/<slug>_product_sheet.html

# 2. Extract stats from the delivery parquet (see DEPLOYMENT.md for queries)
python3 -c "import duckdb; ..."

# 3. Replace all [token] placeholders in the HTML

# 4. Preview in browser
cd /path/to/<product>/reports/product_sheet/
python3 -m http.server 8099

# 5. Generate PDF (requires Google Chrome)
python3 generate_pdf.py
```

### Placeholder token reference (short form)

| Section | Key tokens |
|---|---|
| Hero | `[pn1]` `[pn2]` `[prod_ver]` `[prod_eye]` `[h1]` `[lead]` `[s1_val]` `[s2_val]` `[pulse]` |
| Stats bar | `[sb1_val]`–`[sb4_val]` · `[sb1_lbl]`–`[sb4_lbl]` |
| Pillars | `[pill_hdr]` · `[p1_head]`–`[p4_head]` · `[p1_body]`–`[p4_body]` |
| State coverage | `[tot_rec]` · `[nsw_n]`–`[nt_n]` · bar `width:%` inline |
| Coverage cards | `[c1_lbl]`–`[c4_lbl]` · `[c1_val]`–`[c4_val]` · `[c1_bw]`–`[c4_bw]` · `[c1_body]`–`[c4_body]` |
| Domain list | `[dom_hdr]` · `[d1]`–`[d14]` |
| Applications | `[app_hdr]` · `[a1]`–`[a6]` |
| Spec table | `[sf1]`–`[sf14]` · `[sv1]`–`[sv14]` |
| CTA | `[cta_h]` · `[cta_b]` · `[mo_yr]` |

Full token descriptions with examples → `docs/product_sheet/DEPLOYMENT.md`

## Brand tokens

```css
--deep-navy:  #0F1B2D   --coral:   #E8573D
--navy:       #1E3A5F   --teal:    #0D7C6D
--amber:      #C47B0A   --surface: #F7F8FA
--font-sans:  'Space Grotesk'
--font-mono:  'IBM Plex Mono'
```

## PDF generation

Requires **Google Chrome** at `/Applications/Google Chrome.app`. WeasyPrint is not used — Chrome headless produces pixel-accurate A4 output for CSS Grid/Flexbox layouts.

```bash
python3 generate_pdf.py
# Done    ~200 KB
```

## Python development setup

```bash
# Install dependencies (requires Poetry)
poetry install

# Run tests
poetry run pytest tests/ -q

# Lint
poetry run ruff check scripts/ src/

# Validate a parquet directory
poetry run python scripts/python/check_parquet.py data/processed/

# Profile any DuckDB table (replace {{table_name}})
duckdb my.db < scripts/sql/exact_summarize.sql
```

Python 3.12 · Polars ≥1.0 · DuckDB ≥1.0 · Pydantic v2 · Loguru · Pytest ≥8 · Ruff ≥0.5 · mypy (strict)

## Tech stack

| Tool | Role |
|---|---|
| Python 3.12 | Data utilities, PDF generation, pipeline scripting |
| Poetry | Dependency and virtual environment management |
| Polars ≥1.0 | DataFrame / tabular operations (project-wide standard; no pandas) |
| DuckDB ≥1.0 | Parquet queries, column profiling, pipeline SQL |
| Pydantic v2 | Configuration and schema validation |
| Loguru | Structured logging with rotation |
| Pytest ≥8 + Ruff + mypy | Testing, linting, and type-checking |
| Google Chrome (headless) | PDF rendering |
| deck.gl 8.x | ArcLayer + TileLayer for interactive geo visualisations |
| Kepler.gl 3.x | Location ping map (embedded via iframe) |
| CARTO dark matter tiles | Basemap for deck.gl maps (no API key required) |
| Cloudflare Pages + Wrangler | Hosting and deployment for interactive presentations |
| Space Grotesk + IBM Plex Mono | Brand typography (Google Fonts CDN) |