arah2/.planning/codebase/STACK.md

# Technology Stack

**Analysis Date:** 2026-10-21

## Project Maturity

This is an **early-stage, design-only project**. There is no running application code yet — no backend, no package manager, no build tooling. The repository contains:

- Concept and design-system documents: `DESIGN.md`, `IDEAS.md`
- A design-system extension: `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md` (frontmatter-structured design tokens for colors, typography, spacing)
- Static HTML UI mockup screens (one `code.html` + `screen.png` per screen) — these are the **only executable code** in the repo
- Planning outputs: `.planning/` (not product code)

The stack below is split into (A) **what actually exists today** and (B) **what the design docs imply for the first implementation**. Executors should treat (A) as the working environment and (B) as planned targets, not existing facts.

## Languages

**Primary:**
- HTML 5 — the four mockup screens: `stitch_minimalist_route_navigator/active_route_guidance/code.html`, `stitch_minimalist_route_navigator/navigate_map_overview/code.html`, `stitch_minimalist_route_navigator/community_incident_reporter/code.html`, `stitch_minimalist_route_navigator/telegram_live_traffic_feed/code.html` (each self-contained, inline `<script>` Tailwind config, minimal inline JS for markup behavior)

**Secondary:**
- Markdown — design docs (`DESIGN.md`, `IDEAS.md`, `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`)

**Implied (target implementation per `IDEAS.md`):**
- A backend language/runtime for the Telegram bot (not yet chosen in any doc; nothing in the repo constrains it)

## Runtime

**Environment:**
- None installed. No `package.json`, no `requirements.txt`, no lockfile, no `.nvmrc`, no CI config, no test config anywhere in the repo.
- Mockups run by opening `code.html` directly in a browser (CDN-based dependencies, no local dev server required).

## Frameworks

**Core (in use today, via CDN in mockups):**
- Tailwind CSS via Play CDN (`https://cdn.tailwindcss.com`) — loaded as a `<script>` tag with an inline `tailwind.config` block defining the full "Telemetry Rams" theme (colors like `signal-orange`, `matte-black`, `soft-beige`; fonts; spacing/border-radius tokens). Present in all four mockup screens.
- Google Fonts CDN — `Geist` (body) and `Space Grotesk` (headings/telemetry), plus Material Symbols Outlined for icons (`https://fonts.googleapis.com/css2?...`). Present in all four mockup screens.

**Testing:**
- Not detected. No test framework, no test files.

**Build/Dev:**
- Not detected. No bundler, no formatter, no linter config. Mockups are standalone static files.
- The Play CDN is explicitly a prototyping tool — a first implementation phase should migrate mockup designs to a committed Tailwind setup (build pipeline or v4 binary) before production use.

## Key Dependencies

**Critical (runtime CDN dependencies of the mockups):**
- `cdn.tailwindcss.com` — theming engine for all screens
- `fonts.googleapis.com` / `fonts.gstatic.com` — Geist, Space Grotesk, Material Symbols
- Mockup images were originally hosted/lifted from Google-hosted sample assets (`lh3.googleusercontent.com/aida/...` placeholders in the Stitch output). The logo placeholder has been replaced with the local project logo (`assets/MASTER_FILE-arah2_logo.svg`); any remaining remote URLs are non-logo placeholders.

**Infrastructural (planned only — see `IDEAS.md` "Architecture Overview"; none is wired up):**
- Telegram Bot API — frontend transport (`IDEAS.md`: "Telegram-first")
- Neon Postgres + PostGIS — event/user storage (`IDEAS.md`)
- OSRM — routing engine with dynamic traffic weighting (`IDEAS.md`, restated in `DESIGN.md`: `/navigate origin → destination → OSRM route`)
- Maptiler — map tile provider for grayscale snapshots (`IDEAS.md`, `DESIGN.md`)
- Cloudflare Pages — optional PWA hosting (`IDEAS.md`); Cloudflare R2 — image/snapshot storage (`IDEAS.md`)
- RabbitMQ — event queue for broadcast-nearby flows (`IDEAS.md`)
- Prometheus + Grafana — monitoring (`IDEAS.md`)
- Resend — email (`IDEAS.md`)

## Configuration

**Environment:**
- No `.env*` files, no config files exist. Nothing to document; note that a first backend phase will need to introduce one (e.g., Telegram bot token, Neon connection string, Maptiler key) — treat secret handling from day one since none exists yet.

**Build:**
- No build config files. Tailwind config lives inline per-mockup in `<script id="tailwind-config">`; the canonical design-token source of truth is `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md` (YAML frontmatter with `colors`, `typography`, `spacing` blocks).

## Platform Requirements

**Development:**
- Any modern browser to view the mockups; any text editor. No Node/Python runtime is required by current code.

**Production (target per `IDEAS.md`):**
- Telegram bot process (runtime/tooling TBC), Neon Postgres (with PostGIS extension enabled), OSRM instance or hosted API, Maptiler API key, Cloudflare Pages + R2, RabbitMQ broker, Prometheus/Grafana stack, Resend account.

## Design-System Constraints (binding for future code)

All future implementation must inherit from `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`:
- Palette: Signal Orange `#EB8008`, Functional Red `#ED3F1C`, Olive Green `#736B1E`, Soft Beige `#D9D2C6`, Matte Black `#1A1A1A` (as defined in `DESIGN.md` and in the inline Tailwind config of every mockup)
- Typography: Space Grotesk for headings/telemetry numbers, Geist for body/labels; uppercase + expanded letter-spacing for labels
- Geometry: 8px baseline grid, **zero border-radius**, no shadows/blur/glass (per `telemetry_rams/DESIGN.md` "Elevation & Depth", "Shapes")
- Interfaces are mobile-first (mockups are `shell-type: mobile_tab` / `mobile_stack`), designed for Telegram-embedded panels and a possible PWA

---

*Stack analysis: 2026-10-21*