Paren Pulse — weekly network snapshot

Self-contained TypeScript service that computes a weekly Paren network snapshot (USA + Canada) and emits a Slack Block Kit payload. Numbers reconcile to the Hex "Paren Dashboard" (AFDC-spine model). No runtime dependency on Hex or Superset.

What it reports

Per country (US, CA), three categories — each split Non-Tesla / Tesla / Aggregate:

1. Infrastructure growth — tracked stations, ports, port coverage %, and "opened this week".
2. Utilization — session volume, WoW %, success rate.
3. Pricing — avg non-member $/kWh (US in USD, CA in CAD).

Plus a grand total. Each category is dated to its own freshest source (infra current, pricing ~current, sessions lag on a monthly batch — see caveats in the message footer).

Run locally

Requires the SSH tunnels to the Paren databases (ClickHouse :8123, MySQL :25060). The tunnel script lives in the sibling ohio-dashboard repo:

bash "../ohio-dashboard/scripts/tunnel.sh"   # start tunnels
cp .env.example .env                          # fill in DB creds
npm install
npm run snapshot         # prints { data, blocks } JSON to stdout
npm run snapshot -- --text   # also prints a human-readable preview to stderr
npm run reconcile        # runs the consistency/drift watchdog (exit 1 on drift)
npm run typecheck

n8n wiring (production)

Deterministic core + CLI, invoked by n8n — no HTTP server:

Schedule Trigger  →  Execute Command: `node bin/snapshot.ts`  →  Slack node (post `blocks`)

The Execute Command node captures stdout JSON; map .blocks into the Slack message. Channel, creds, and cron timing are configured in n8n. Run node bin/reconcile.ts on the same schedule (or before posting) to gate on drift.

The n8n host must run Node and reach the databases (the same access support-ticketing relies on).

Source of truth & reconciliation

• Curated SQL lives in src/curated/*.sql.ts with provenance comments pointing back to the Hex notebook / canonical Superset queries, and the date last synced.
• All v1 metrics reconcile to the Hex "Paren Dashboard" (infra, sessions, pricing — US + CA, Non-Tesla / Tesla / Aggregate). src/reconcile/ is the ongoing drift watchdog.

Maintainer notes (intentional definitions, not bugs):

• Sessions = completed (successful), matching the dashboard "Total Sessions" KPI (non_tesla "Of which, success" + tesla "Of which, success") — NOT total attempts.
• CA "Non-Tesla" on the Hex dashboard includes Tesla (its cell omits the 'tesla' exclusion), so its ~2,071 equals our CA Aggregate. We keep Non-Tesla Tesla-excluded for consistency with US.
• No "new/opened this week" in v1 — the dashboard has no equivalent and created_at / AFDC OpenDate are unreliable proxies. Phase 2: persist weekly snapshots and diff our own tracked count.

Layout

src/lib/        DB clients (ported from ohio-dashboard) + date/number helpers
src/curated/    the metric SQL (AFDC-spine infra, sessions, pricing) + Tesla classification
src/snapshot/   frontier resolution, orchestrator, types, Slack formatter
src/reconcile/  consistency + drift watchdog
bin/            snapshot.ts, reconcile.ts (CLIs n8n invokes)