152 lines
10 KiB
Markdown
152 lines
10 KiB
Markdown
<!-- refreshed: 2026-10-21 -->
|
|
# 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.
|
|
|
|
```text
|
|
┌──────────────────────────────────────────────────────────────┐
|
|
│ 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*
|