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