# Architecture — alivedata Brand Docs

**Version:** 2026.05  
**Owner:** Strategy / Engineering  
**Approved:** Hanni Ishkan, CEO  
**Last updated:** May 2026

---

## Overview

`alivedata_brand_docs` is the single source of truth for all alivedata product marketing, release documentation, and technical references. It publishes a branded internal product hub to Cloudflare Pages, accessible only to `@alivedata.com.au` accounts via Cloudflare Access.

```
alivedata-products.pages.dev
│
├── /                            Product Hub (index)
├── /spine/marketing/            Spine product sheet
├── /auto-insights/marketing/    Auto Insights product sheet
└── /presentations/              Interactive HTML presentations
```

---

## Repository layout

```
alivedata_brand_docs/
│
├── dist/                        Build artifact — Cloudflare Pages deploy root (gitignored)
│   ├── index.html               Product hub
│   ├── spine/marketing/
│   ├── auto-insights/marketing/
│   ├── presentations/
│   └── docs/                    Versioned project docs
│
├── docs/
│   ├── ai_rules/                AI assistant rule suite (01–09)
│   ├── brand_guidlines/         Brand guidelines HTML + PDF
│   ├── product_sheet/           Brochure deployment guide
│   └── presentations/           Presentation deployment guide
│
├── scripts/
│   ├── python/                  Data utilities (check_parquet.py)
│   ├── sql/                     DuckDB profiling queries
│   └── root_cause/              Ishikawa / incident notes
│
├── src/                         Shared library code (data, models, utils, viz)
├── tests/                       Pytest test suite
├── config/settings.yaml         Project path and logging defaults
├── pyproject.toml               Poetry project — Python 3.12 stack
│
├── template_product_brochure.html   Brochure template (brand tokens + placeholders)
├── alivedata_202603_from_attendance_to_behaviour.html   Interactive presentation
│
├── ARCHITECTURE.md              This file
├── CHANGELOG.md                 Version history
└── README.md                    Project overview and quick-start
```

---

## Content architecture

Three pillars, each serving a distinct audience:

| Pillar | Audience | Content types |
|---|---|---|
| **Marketing** | Exec, Sales, Prospects | Product Sheet (HTML + PDF), Presentation |
| **Releases** | Data Teams, Analysts | Release Note, Data Dictionary, Changelog |
| **Technical** | Engineers, Integrators | Pipeline Doc, Schema Reference, Deployment Guide |

Per-product site tree:

```
/
└── /<product-slug>/
    ├── /marketing/    Product sheet · presentations
    ├── /releases/     Release notes · data dictionary
    └── /docs/         Pipeline doc · schema reference · deployment guide
```

Current products: `spine`, `auto-insights`. New products require only a YAML/config entry; the hub index is data-driven.

---

## Technology stack

### Data & scripting

| Component | Technology | Notes |
|---|---|---|
| Pipeline language | Python 3.12 (Poetry) | `pyproject.toml` |
| DataFrame / ETL | Polars ≥1.0 | No pandas |
| Pipeline SQL | DuckDB ≥1.0 | Parquet queries, column profiling |
| Validation | Pydantic v2 | Config + schema boundaries |
| Logging | Loguru | Rotating file + stderr |
| Testing | Pytest ≥8 | `tests/` |
| Linting / types | Ruff ≥0.5 + mypy (strict) | Line-length 120 |

### Front-end

| Component | Technology | Notes |
|---|---|---|
| Fonts | Space Grotesk · IBM Plex Mono | Google Fonts CDN |
| Geo visualisation | deck.gl 8.x | ArcLayer + TileLayer (CARTO tiles) |
| Location map | Kepler.gl 3.x | Embedded via `<iframe>` |
| PDF generation | Chrome headless (`--headless=new`) | A4 / A3 portrait |

### Infrastructure

| Component | Technology | Notes |
|---|---|---|
| Hosting | Cloudflare Pages | `alivedata-products.pages.dev` |
| Deploy CLI | Wrangler 4.x (`npx wrangler pages deploy dist/`) | |
| Access control | Cloudflare Access (Zero Trust) | Email OTP · `@alivedata.com.au` only |
| Version control | Git / GitHub | `norrye/alivedata_brand_docs` |

---

## Build & deploy pipeline

```
Source edits
    │
    ▼
Edit HTML / Markdown / scripts in workspace
    │
    ▼
Build dist/ (manual step)
    cp <product_sheet>.html  dist/<product>/marketing/index.html
    cp <presentation>.html   dist/presentations/
    cp docs/*.md             dist/docs/                         (versioned suffix)
    (hub index.html maintained directly in dist/)
    │
    ▼
Deploy
    npx wrangler pages deploy dist --project-name alivedata-products --branch main
    │
    ▼
Cloudflare Pages serves dist/ at alivedata-products.pages.dev
    │
    ▼
Cloudflare Access enforces @alivedata.com.au login (Zero Trust · email OTP)
```

---

## PDF generation

Chrome headless converts any HTML page to print-accurate PDF. Dimensions are set via `--paper-width` / `--paper-height` (inches):

| Format | Width | Height | Use |
|---|---|---|---|
| A4 portrait | 8.27 | 11.69 | Product sheets |
| A3 portrait | 11.69 | 16.54 | Architecture / ontology docs |

Script pattern: `scripts/python/generate_pdf.py` (copy from `alivedata_spine_202605/documentation/product_sheet/generate_pdf.py` and update paths).

---

## Brand tokens

All HTML assets use these CSS custom properties — **do not hardcode colours**:

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

The A-mark SVG path is canonical — do not modify:
```
M 3.3 100 L 0 99.8 L 49.4 0.7 L 51.8 0 L 99.9 95.2 L 99.9 97.5 L 98 99.2
L 39.3 99.5 L 37.7 98.4 L 37.3 95.5 L 49.1 72.7 L 52.5 72.8 L 55.5 78.3
L 56.9 79.3 L 66.2 79.3 L 68.1 77.5 L 68 76 L 53.2 46.4 L 51 45.1
L 48.9 46.5 L 22.8 98.8 L 21.3 99.6 Z
```

---

## AI assistant rules

Nine rule documents in `docs/ai_rules/` define behaviour for all AI coding assistants working in this repo. Rules are also mirrored to `.amazonq/rules/rules.md` for Amazon Q. Priority order:

1. Data Verification
2. Compliance Enforcement
3. Root Cause Analysis
4. Data Integrity
5. Production Standards
6. Code Quality & Testing
7. Versioning

---

## Security

- **No credentials in repo** — Mapbox token is embedded in `eels_roosters_kepler.gl.html`; rotate before sharing externally.
- **`data/`** directories are gitignored — raw parquet and DuckDB files do not enter version control.
- **`dist/`** is gitignored — rebuild before each deploy; never commit build artifacts.
- **Cloudflare Access** restricts all `alivedata-products.pages.dev` routes to `@alivedata.com.au` email OTP.

---

*© 2026 Alivedata (AUST) Pty Ltd. Proprietary — Internal Use Only.*