arah2/.planning/codebase/ARCHITECTURE.md

Architecture

Analysis Date: 2026-10-21

System Overview

This is a pre-implementation / design-phase project. There is no backend, runtime code, package manifest, build tooling, or test suite yet. The current "architecture" consists of:

1. Planning documents at repo root (DESIGN.md, IDEAS.md) describing the product vision and target stack.
2. Static HTML UI mockups (one directory per screen) under stitch_minimalist_route_navigator/, each self-contained and openable directly in a browser.

┌──────────────────────────────────────────────────────────────┐
│              Current State: Static UI Mockups                 │
├──────────────────┬──────────────────┬────────────────────────┤
│  Mockup screens  │  Design system   │   Planning docs        │
│  stich_.../*/    │ telemetry_rams/  │   DESIGN.md            │
│  code.html       │  DESIGN.md       │   IDEAS.md             │
└──────────────────┴──────────────────┴────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│         Implied Target Architecture (from IDEAS.md)           │
├───────────────────┬──────────────────────┬───────────────────┤
│  Frontend         │  Backend             │  Data / Infra     │
│  Telegram bot +   │  OSRM routing        │  Neon Postgres    │
│  optional PWA     │  (traffic weighting) │  (PostGIS)        │
│  (Cloudflare      │  RabbitMQ queue      │  Cloudflare R2    │
│   Pages)          │  Resend email        │  Maptiler tiles   │
└───────────────────┴──────────────────────┴───────────────────┘

Component Responsibilities

Component	Responsibility	File
active_route_guidance/	Turn-by-turn navigation HUD mockup: maneuver strip, incident telemetry band, map corridor viewport	stitch_minimalist_route_navigator/active_route_guidance/code.html
navigate_map_overview/	Full-map navigation screen mockup: route rendering, layer toggles, recenter control	stitch_minimalist_route_navigator/navigate_map_overview/code.html
telegram_live_traffic_feed/	Telegram-bot-styled traffic feed mockup: inline commands (/traffic, /hazard, /status, /clear), dispatch confirm	stitch_minimalist_route_navigator/telegram_live_traffic_feed/code.html
community_incident_reporter/	Incident-report flow mockup: hazard drawer, modal report, incident type selection	stitch_minimalist_route_navigator/community_incident_reporter/code.html
telemetry_rams/DESIGN.md	Formal design system spec (design tokens: colors, typography, spacing, breakpoints, component rules)	stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md
DESIGN.md	High-level Rams design philosophy: palette, typography, iconography, interaction flows	DESIGN.md
IDEAS.md	Product vision, core principles, target stack outline, gamification and future ideas	IDEAS.md

Pattern Overview

Overall: Design-system-driven static mockup pattern (no application architecture exists yet).

Key Characteristics:

• Each mockup screen is a single self-contained HTML file (code.html) with inline <style> and inline <script>. No shared CSS/JS modules, no bundler, no imports between screens.
• Styling is Tailwind via CDN script (https://cdn.tailwindcss.com) with a per-file inline tailwind.config object encoding the design tokens (colors, borderRadius, spacing). No Tailwind build step.
• Fonts and icons are loaded from CDNs: Google Fonts (Space Grotesk for headlines/telemetry, Geist for body) and Material Symbols Outlined for iconography.
• Imagery is either inline SVG (route vectors, directional glyphs drawn with stroke-linecap="square"), the local project logo (assets/MASTER_FILE-arah2_logo.svg), or legacy remote hosted URLs (lh3.googleusercontent.com/aida/... placeholders in the remaining mockups) — local image assets are limited to the logo and screen.png captures.
• Interactivity is vanilla JS via inline onclick handlers only (demo stubs — e.g., alert('Reroute broadcast loaded.')). No state management, no routing, no data layer.

Layers

Current (mockup-only) layers:

• Presentation: stitch_minimalist_route_navigator/*/code.html — Tailwind markup + inline SVG + demo JS
• Design tokens: stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md (YAML front matter: colors, typography, spacing) duplicated as inline tailwind.config in each mockup's <head>
• Specs/docs: DESIGN.md, IDEAS.md (root)

Implied target layers (per IDEAS.md):

• Frontend: Telegram Bot interface + optional PWA hosted on Cloudflare Pages
• Transport: Telegram API (bot commands, inline queries, location sharing)
• Services: OSRM routing with dynamic traffic weighting; RabbitMQ for event queueing; Resend for email
• Data: Neon (Postgres + PostGIS) for event/route storage; Cloudflare R2 for map snapshot storage; Maptiler for basemap tiles
• Observability: Prometheus + Grafana

Data Flow

Mockup Screen Flow (current)

1. Open code.html in a browser (or view companion screen.png capture)
2. Tailwind CDN applies design tokens from the inline tailwind.config
3. Inline onclick handlers fire demo stubs (e.g., insertCommand('/hazard ...'), closeHazardDrawer()) — no persistence

Implied Report Flow (target, per DESIGN.md)

1. User sends /report accident (with location) via Telegram bot
2. Bot confirms; event stored in database (Postgres/PostGIS)
3. Event broadcast to nearby users via bot feedback loop

Implied Navigation Flow (target, per DESIGN.md)

1. User sends /navigate origin → destination
2. OSRM computes route with traffic weighting
3. Bot replies with text directions + grayscale map snapshot with accent overlays

State Management:

• None today. Mockup JS is stateless demo handlers only. Nothing implies persistence patterns yet.

Key Abstractions

Design token set ("Telemetry Rams" system):

• Purpose: Single source of truth for colors, typography, spacing, component rules
• Examples: stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md, duplicated inline in each code.html <head> as tailwind.config
• Pattern: YAML-front-matter spec → inline Tailwind config (manual duplication — a known inconsistency risk)

Screen directory contract:

• Each screen is one directory holding exactly code.html (the mockup) and screen.png (a visual capture)
• Examples: all four screen directories under stitch_minimalist_route_navigator/

Incident/traffic domain concepts (documented, not implemented):

• Event types appear consistently across docs and mockups: CONGESTION (traffic/orange), ACCIDENT/CRASH-BLOCK (red), POLICE RADAR / SPEED_TRAP (green)
• Examples: stitch_minimalist_route_navigator/telegram_live_traffic_feed/code.html (confirmDispatch('CONGESTION'), confirmDispatch('CRASH / BLOCK'), confirmDispatch('POLICE RADAR'))

Entry Points

Static mockup entry points (operational today):

• Location: stitch_minimalist_route_navigator/<screen>/code.html for each of the four screens
• Triggers: opening the file directly in a browser (file:// works — all dependencies are CDN-hosted)
• Responsibilities: render the screen for design review; demo-interactions via inline handlers

No application entry points exist — there is no src/, main.*, index.*, server.*, package manifest, or container config.

Architectural Constraints

• Runtime: None required for mockups; plain browser. An internet connection is required (Tailwind CDN, Google Fonts, remote images).
• Global state: None. Each mockup is fully isolated; no shared modules exist.
• Circular imports: Not applicable (no modules).
• Token duplication: The palette/typography/spacing defined in telemetry_rams/DESIGN.md is hand-copied into every mockup's inline tailwind.config. Any token change must be replicated N times until a real build pipeline exists.
• Windows Zone.Identifier files: *:Zone.Identifier metadata files are scattered throughout and should be excluded from any future build/lint tooling.

Anti-Patterns (recommendations for the target codebase)

Per-file Tailwind config duplication

What happens: Each mockup re-declares the full design-token set inline. Why it's wrong: Tokens drift between screens; changing a color requires editing every file. Do this instead: When real frontend work begins, centralize tokens in a single Tailwind config / CSS variables file consumed by all screens (source it from telemetry_rams/DESIGN.md).

Inline onclick demo handlers

What happens: Behavior lives in onclick="..." attributes calling inline functions (alert() stubs). Why it's wrong: Untestable and unrefactorable; acceptable only for visual demo mockups. Do this instead: Structure real code with separated modules, event listeners, and a typed frontend framework per IDEAS.md.

Error Handling

Strategy: None exists. No backend, no error states implemented. The design system only reserves Functional Red (#ED3F1C) for warnings/hazards/terminal errors (stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md).

Cross-Cutting Concerns

Logging: Not implemented; target stack names Prometheus + Grafana (IDEAS.md). Validation: Not implemented; target implies Telegram command/location validation. Authentication: Not implemented; target is Telegram-identity-based (bot commands per user), no other auth mentioned.

---

Architecture analysis: 2026-10-21