forked from c-fu/arah2
docs(01-design-tokens-rams-foundation): create phase plan (4 plans, 3 waves)
This commit is contained in:
araharah-planner
@@ -0,0 +1,151 @@
|
||||
<!-- 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"`) or **remote hosted URLs** (`lh3.googleusercontent.com/aida/...` logo images) — no local image assets besides `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*
|
||||
@@ -0,0 +1,148 @@
|
||||
# Codebase Concerns
|
||||
|
||||
**Analysis Date:** 2026-10-21
|
||||
|
||||
**Repo state:** Early-stage design-only project. No git repo, no package manifest, no tests, no backend. Content is two planning docs (`DESIGN.md`, `IDEAS.md`) plus the `stitch_minimalist_route_navigator/` directory of Stitch-generated HTML UI mockups (4 screens with `code.html` + `screen.png`, 1 design-system doc).
|
||||
|
||||
---
|
||||
|
||||
## Tech Debt
|
||||
|
||||
**Directory hygiene: Windows `*:Zone.Identifier` metadata files committed alongside assets**
|
||||
- Issue: Every downloaded asset carries an NTFS Alternate Data Stream export (`*:Zone.Identifier` files) from unzipping on Windows. Top-level `DESIGN.md` and `IDEAS.md` have no counterparts, but 10 of the mockup assets do (e.g., `stitch_minimalist_route_navigator/active_route_guidance/code.html:Zone.Identifier`).
|
||||
- Files: all `stitch_minimalist_route_navigator/*/*:Zone.Identifier` (10 files — one per `code.html` and per `screen.png` in the four screen directories)
|
||||
- Impact: Noise pollution in every glob/grep operation, misleading file listings, and potential pipeline breakage when tooling glob patterns accidentally match these files as HTML/PNG sources. Their one-time content even leaked a local Windows path (`X:\Donlod\...zip`) — a minor information-disclosure artifact.
|
||||
- Fix approach: Delete all `*:Zone.Identifier` files now (`find . -name "*:Zone.Identifier" -delete`). Once a git repo is initialized, add a `.gitignore` blocking the pattern and add a pre-commit or CI hygiene check. Never treat these files as content sources.
|
||||
|
||||
**No version control, no ignores file**
|
||||
- Issue: There is no `.git` directory and no `.gitignore` at the repo root. All work exists only on disk.
|
||||
- Files: repo root (`/home/C-Fu/araharah/`)
|
||||
- Impact: Any accidental delete loses the only copy of the mockups and design docs; no change history for iterating on screens; the Zone.Identifier debt described above has no automated guard.
|
||||
- Fix approach: `git init` as the very first implementation step, with a `.gitignore` covering `*:Zone.Identifier`, OS junk (`.DS_Store`, `Thumbs.db`), and future `node_modules/` / secrets.
|
||||
|
||||
**Four copies of the same ~5KB inline Tailwind theme config**
|
||||
- Issue: Each `code.html` embeds the full `tailwind.config={...}` design-token block (colors, fontSize, spacing, fontFamily) as a duplicate inline `<script id="tailwind-config">`. It is byte-for-byte identical across all four screens (tokens match `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md:2-148`), so ~20KB of the 94KB total is pure duplication.
|
||||
- Files: `stitch_minimalist_route_navigator/active_route_guidance/code.html`, `stitch_minimalist_route_navigator/community_incident_reporter/code.html`, `stitch_minimalist_route_navigator/navigate_map_overview/code.html`, `stitch_minimalist_route_navigator/telegram_live_traffic_feed/code.html`
|
||||
- Impact: Any token change (e.g., palette tweak) must be edited in four places; a single missed copy silently diverges the visual system between screens.
|
||||
- Fix approach: When prototype-grade tooling is introduced, extract the token block to a single shared config (Tailwind `.js` config or CSS custom properties) and reference it from a built stylesheet. Until then, enforce a note that these are throwaway artifacts not to be edited in place.
|
||||
|
||||
**Single-line minified HTML in mockups**
|
||||
- Issue: The `code.html` files are Stitch exports with entire documents collapsed onto one or two extremely long lines (e.g., head + body markup as a single line), only the `<style>` and comment blocks are broken out.
|
||||
- Files: all four `stitch_minimalist_route_navigator/*/code.html`
|
||||
- Impact: Impossible to diff meaningfully, painful to hand-edit, and grep context output is unusable (one "line" contains the whole document).
|
||||
- Fix approach: Treat these as generated, read-only reference artifacts. If they must be edited, run them through a formatter (Prettier) once and keep the formatted copy under version control going forward.
|
||||
|
||||
---
|
||||
|
||||
## Design-Source-of-Truth Conflicts (Fragile Areas)
|
||||
|
||||
**Two competing design systems in the same repo**
|
||||
- Issue: Root `DESIGN.md` specifies Helvetica Neue/Inter, 14px body / 18px headings / 24px titles, and a 5-color palette (`DESIGN.md:17-35`). Meanwhile `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md:59-148` specifies Space Grotesk + Geist, an entire Material-style token set (surface containers, fixed/variant colors), and the actual mockups implement the *latter* (their inline Tailwind config uses `Space Grotesk`/`Geist` and ~40 token colors, not Helvetica/Inter with 5 colors).
|
||||
- Files: `DESIGN.md`, `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`
|
||||
- Impact: A future implementer reading the top-level `DESIGN.md` will code against the wrong typography and palette. The repo's "canonical" design doc contradicts its own reference implementation.
|
||||
- Safe modification: Decide which doc wins (recommend promoting `telemetry_rams/DESIGN.md` to root design authority since the mockups match it), mark the loser as superseded or delete it, and state a single-file-of-truth rule before any UI phase.
|
||||
|
||||
**Mockups violate their own zero-roundedness / anti-flat-glow rules**
|
||||
- Issue: `telemetry_rams/DESIGN.md:206-208` mandates "absolute zero roundedness (0px corner radius)" and rejects blurs/frosted glass (`DESIGN.md:196`), yet the mockups contain `rounded-full`/rounded classes (e.g., avatar circles, chips in `active_route_guidance/code.html`, ~5 occurrences) and a `backdrop-blur-xl shadow-[0_1px_8px_rgba(0,0,0,0.04)]` header in `active_route_guidance/code.html`.
|
||||
- Files: `stitch_minimalist_route_navigator/active_route_guidance/code.html` (header, avatar), `stitch_minimalist_route_navigator/community_incident_reporter/code.html`
|
||||
- Impact: Screens are a compromised reference; copying markup into the real app would import non-Rams ornament that the design doc forbids.
|
||||
- Safe modification: When implementing, treat the *design doc* token rules as binding and the *mockup markup* as layout reference only; scrub rounded/blur utilities during implementation.
|
||||
|
||||
---
|
||||
|
||||
## Mockup Fragility / Runtime Dependencies
|
||||
|
||||
**Runtime Tailwind CDN + third-party CDN single points of failure**
|
||||
- Issue: Every screen loads Tailwind as an uncompiled runtime script from `https://cdn.tailwindcss.com` (officially "not for production"), plus Google Fonts (Geist, Space Grotesk), Material Symbols Outlined, and a `lh3.googleusercontent.com` logo image. There is no vendoring, no build step, and no `package.json`; the screens render correctly only with internet access to these CDNs.
|
||||
- Files: `<head>` of all four `stitch_minimalist_route_navigator/*/code.html`
|
||||
- Trigger: Open offline, or when the ephemeral Google-hosted logo URL expires.
|
||||
- Workaround: None in-repo. This is fine for mockups but disqualifies the files from production use as-is.
|
||||
- Fix approach: For the real app, use a compiled Tailwind build (this happens naturally once any framework/tooling phase runs). Download the logo asset locally if it is to be reused.
|
||||
|
||||
**Hardcoded mock data and dead-end interactions**
|
||||
- Issue: Navigation/route data, telemetry numbers, hazard cards, and traffic feed messages are hardcoded `const` arrays/objects inside each screen; handlers are inline `onclick` stubs (`confirmDispatch('CONGESTION')`, `toggleHazardCard('ACCIDENT')` in `navigate_map_overview/code.html`; `insertCommand('/hazard ')` and `alert('Reroute broadcast loaded.')` in `telegram_live_traffic_feed/code.html`). No fetch calls, no map tiles, no routing engine — the "map" is a static styled panel.
|
||||
- Files: all four `stitch_minimalist_route_navigator/*/code.html` (`<script>` block at end of each file)
|
||||
- Impact: The mockups give no signal about the hard part (OSRM routing, live Telegram feed, geographic event storage in PostGIS); estimating implementation effort from these screens alone will be badly optimistic.
|
||||
- Fix approach: Treat mock data shapes as informal UI contracts (the `const` structures are a reasonable starting point for real data models) but plan backend/integration phases before promising any of the flows in `DESIGN.md:69-73`.
|
||||
|
||||
**Shell-specific assumptions baked in**
|
||||
- Issue: The screens carry `<meta name="shell-type" content="mobile_stack">`, `user-scalable=no`, fixed `884px`-min-height bodies, and hidden scrollbars (`::-webkit-scrollbar{display:none}`) — targeting a specific mobile embed/stitch render shell rather than standalone browsers.
|
||||
- Files: `<head>`/`<style>` of all four `stitch_minimalist_route_navigator/*/code.html`
|
||||
- Impact: Accessibility regression (`user-scalable=no` blocks pinch zoom; contrast and zoom rules conflict), and layout breaks if opened directly on desktop or inside a nonstandard webview.
|
||||
- Fix approach: Strip `user-scalable=no` and shell-only metas when porting; these are mockup artifacts, not app requirements.
|
||||
|
||||
---
|
||||
|
||||
## Architecture / Roadmap Reality Gaps
|
||||
|
||||
**Heavyweight target stack vs. zero implemented code**
|
||||
- Issue: `IDEAS.md:55-73` specifies a full production architecture: Telegram Bot + PWA, Neon Postgres+PostGIS, OSRM with dynamic traffic weighting, Maptiler tiles, RabbitMQ queue, Cloudflare R2, Prometheus/Grafana, Resend email. Nothing in the repo implements even one of these components — there is no source code at all, no `package.json`, and no CI.
|
||||
- Files: `IDEAS.md`, repo root
|
||||
- Impact: Highest-value concern: the gap between the mockups (static UI shells) and the vision (distributed multi-service system) is the entire engineering project. Prioritizing infrastructure (RabbitMQ, Grafana, R2) before a walking-skeleton bot + OSRM round-trip would be premature.
|
||||
- Fix approach: Sequence phases as: git init → walking-skeleton Telegram bot echoing commands → OSRM route round-trip → PostGIS event storage → then queue/monitoring/storage. Treat unneeded services (RabbitMQ, Resend, Prometheus) as explicitly deferred, not part of an MVP.
|
||||
|
||||
**Undefined design ambiguity: "minimal single-file" vs. scalable app**
|
||||
- Issue: Nothing in the repo states what runtime the eventual product uses (plain web app?, PWA?, Telegram WebApp embed?). The mockups' inline CSS/JS monolith pattern will not scale: 4 screens already total ~98KB of duplicated tokens and copy-pasted utility classes; at 10–20 screens this pattern guarantees drift described in the Tailwind-duplication section.
|
||||
- Files: `IDEAS.md:57-58` ("Telegram-first: ... optional PWA"), `stitch_minimalist_route_navigator/*`
|
||||
- Impact: Blocks any implementation phase from starting correctly; the first framework decision will retroactively invalidate markup assumptions from all mockups.
|
||||
- Fix approach: Make the runtime/format decision (e.g., Next.js PWA served in Telegram WebApp, React + compiled Tailwind, shared token file) in a dedicated setup phase before porting any mockup.
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
**Leaked local path in committed metadata**
|
||||
- Risk: `*:Zone.Identifier` files record source download URLs; the one inspectable case contains `ReferrerUrl=X:\Donlod\...zip`, disclosing a filesystem path pattern.
|
||||
- Files: `stitch_minimalist_route_navigator/*/*:Zone.Identifier`
|
||||
- Current mitigation: None (no git repo, no CI, no scrubbing step).
|
||||
- Recommendations: Delete the files (see Tech Debt #1); if a git repo is initialized without cleaning, this path is forever in history.
|
||||
|
||||
**No secrets to leak — but no key management either**
|
||||
- Risk: Trivially low today (no code), but the target stack requires Telegram bot tokens, Maptiler keys, and Neon credentials with no designed home for them.
|
||||
- Files: none yet
|
||||
- Current mitigation: None.
|
||||
- Recommendations: Establish `.env` + `.env.example` + `secretlint` toggle in `.gitignore` during the first setup phase, *before* any real credentials exist.
|
||||
|
||||
**Nondeterministic third-party scripts running on every mockup open**
|
||||
- Risk: `cdn.tailwindcss.com` bundles and executes a JIT compiler in-page; any CDN compromise or the service's eventual shutdown changes/breaks behavior silently. Low stakes while these are mockups, but relevant the moment anyone shares them with stakeholders as "the product."
|
||||
- Files: all four `stitch_minimalist_route_navigator/*/code.html` `<head>`
|
||||
- Recommendations: Keep communicating they are mockups; for any public demo, pin/snapshot the CDN output locally first.
|
||||
|
||||
## Performance Bottlenecks
|
||||
|
||||
Not yet applicable — no runtime code exists. For the record: the mockups render fine despite the runtime-Tailwind approach, but that approach bleeds ~300KB of compiler JS before first paint, which would be a bottleneck in the real app and is eliminated by compiled Tailwind.
|
||||
|
||||
## Scaling Limits
|
||||
|
||||
**Mockup pattern scales to zero screens**
|
||||
- Problem: Per-file token duplication on 4 screens is already at the maintainability ceiling; the repo cannot accommodate 10+ screens without guaranteed divergence.
|
||||
- Cause: No shared stylesheet/config; Stitch exports are atomic single files.
|
||||
- Files: all four `stitch_minimalist_route_navigator/*/code.html`
|
||||
- Improvement path: Extract tokens and shared chrome into the real app's component/config layer during the first implementation phase.
|
||||
|
||||
## Dependencies at Risk
|
||||
|
||||
**`cdn.tailwindcss.com` (runtime CDN)**
|
||||
- Risk: Unpinned, production-discouraged, service availability not guaranteed; a change or outage breaks all four mockups at once.
|
||||
- Impact: Mockups stop rendering properly; no local fallback exists.
|
||||
- Migration plan: Compiled Tailwind via any JS tooling in the first build phase; for the repo's mockups, snapshot locally if they need to survive long-term.
|
||||
|
||||
**Google Fonts + `lh3.googleusercontent.com` assets**
|
||||
- Risk: Fonts load only online; the AI-generated logo URL is ephemeral and is referenced identically in all four files — if it dies, branding breaks everywhere simultaneously with no local replacement.
|
||||
- Files: `stitch_minimalist_route_navigator/active_route_guidance/code.html` and the three sibling `<head>`s
|
||||
- Migration plan: Download the logo into the repo asset tree; self-host fonts (or subset) in the real app.
|
||||
|
||||
## Missing Critical Features
|
||||
|
||||
**Everything is missing by design** — no code, no tests, no CI, no manifest, no git, no `README`. The notable early gaps to plan explicitly:
|
||||
- Problem: No `README.md` explaining the repo's purpose, no license, no git history, no developer tooling config (editor/lint/format), no `package.json` even for tooling.
|
||||
- Blocks: Onboarding anyone (or any future agent session) requires re-deriving context from `IDEAS.md`/`DESIGN.md` every time; the Zone.Identifier debt and doc conflicts above go unnoticed indefinitely.
|
||||
- Fix approach: Preface the first phase with "project setup": git init, README capturing the Rams design intent and pointing to the authoritative design doc, `.gitignore`, and license.
|
||||
|
||||
## Test Coverage Gaps
|
||||
|
||||
Not applicable — there is nothing to test yet. When the first real code lands, note that the repo has zero testing conventions to inherit from; `TESTING.md` will need to be generated fresh alongside the first implementation phase.
|
||||
|
||||
---
|
||||
|
||||
*Concerns audit: 2026-10-21*
|
||||
@@ -0,0 +1,133 @@
|
||||
# Coding Conventions
|
||||
|
||||
**Analysis Date:** 2026-10-21
|
||||
|
||||
> **Scope caveat:** This is a pre-implementation design repository. There is **no source code,
|
||||
> no package manifest, no linter/formatter config, and no build system** in the repo yet
|
||||
> (no `package.json`, `.eslintrc*`, `.prettierrc*`, `tsconfig.json`, or `.gitignore` exists).
|
||||
> The only code is static HTML/Tailwind mockups under
|
||||
> `stitch_minimalist_route_navigator/`. Conventions below are extracted from those mockups
|
||||
> and the design-system docs, and should be treated as the de-facto starting point for any
|
||||
> future implementation code.
|
||||
|
||||
## Established Document Conventions
|
||||
|
||||
**Design system declaration:**
|
||||
- The design system lives in `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`
|
||||
as a YAML frontmatter block (`name`, `colors`, `typography`, `spacing`) followed by
|
||||
prose sections (Brand & Style, Colors, Typography, Layout & Spacing, Elevation & Depth,
|
||||
Shapes, Components).
|
||||
- Core philosophy docs are plain prose at repository root: `DESIGN.md` (Rams principles,
|
||||
8px grid, color palette, component rules) and `IDEAS.md` (vision, architecture targets,
|
||||
gamification ideas). Both end with the motto line
|
||||
"Good design is as little design as possible." — Dieter Rams.
|
||||
|
||||
**Token vocabulary (use these names verbatim in any new code):**
|
||||
- Colors, kebab-case: `signal-orange` (#EB8008), `functional-red` (#ED3F1C),
|
||||
`olive-green` (#736B1E), `soft-beige` (#D9D2C6), `matte-black` (#1A1A1A),
|
||||
`chassis-subtle` (#CCC4B5), `surface-dark` (#121212), `pure-white` (#FFFFFF).
|
||||
Full Material-style surface/on-surface scale is declared in the frontmatter of
|
||||
`stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`.
|
||||
- Typography scale, kebab-case: `display-lg`, `headline-lg`, `headline-md`, `headline-sm`,
|
||||
`body-lg`, `body-md`, `body-sm`, `label-lg`, `label-md`, `label-sm`, `telemetry-num`.
|
||||
- Spacing, kebab-case: `gutter`, `gutter-desktop`, `margin`, `margin-desktop`,
|
||||
`space-xs` … `space-2xl`. All dimensions MUST be multiples of 4px/8px.
|
||||
|
||||
## Naming Patterns
|
||||
|
||||
**Directories:**
|
||||
- `snake_case`, name = the screen/feature being mocked up:
|
||||
`stitch_minimalist_route_navigator/active_route_guidance/`,
|
||||
`stitch_minimalist_route_navigator/navigate_map_overview/`,
|
||||
`stitch_minimalist_route_navigator/community_incident_reporter/`,
|
||||
`stitch_minimalist_route_navigator/telegram_live_traffic_feed/`.
|
||||
|
||||
**Files (fixed within every screen directory):**
|
||||
- `code.html` — the generated mockup markup for that screen.
|
||||
- `screen.png` — the rendered screenshot of the same screen. Never rename these;
|
||||
tooling and review flows key on the pair `<screen_dir>/code.html` + `<screen_dir>/screen.png`.
|
||||
- `DESIGN.md` (where present) — design-system doc for that screen group.
|
||||
|
||||
**Design tokens / classes:** kebab-case (`bg-matte-black`, `text-signal-orange`,
|
||||
`border-functional-red`). Do not introduce camelCase or snake_case class names.
|
||||
|
||||
## HTML Mockup Style (observed in `code.html` files)
|
||||
|
||||
**Structure:**
|
||||
- One self-contained HTML file per screen; first `<head>` line is a dense set of
|
||||
`<meta>`/preconnect/font links, incl. Google Fonts `Geist` + `Space Grotesk` and
|
||||
`Material Symbols Outlined`.
|
||||
- Tailwind is loaded via CDN (`https://cdn.tailwindcss.com`) with an inline
|
||||
`tailwind.config` script that extends `colors`, `borderRadius`, `spacing`, fonts.
|
||||
Every one of the four `code.html` files duplicates this exact config block — keep it
|
||||
in sync if tokens change.
|
||||
- Body uses semantic structure: `<header>` (fixed, h-16), `<main>` (flex-1), with content
|
||||
sections as `<section>` blocks; each major section preceded by an UPPER_SNAKE
|
||||
descriptive comment, e.g. `<!-- Turn-by-Turn Maneuver HUD (Matte Black Primary Chassis) -->`
|
||||
(`stitch_minimalist_route_navigator/active_route_guidance/code.html:10`,
|
||||
`<!-- Incident Telemetry Band -->` at line 44).
|
||||
- Fine-grained comments use PascalCase-ish descriptive style:
|
||||
`<!-- Lane Assignment Matrix -->`, `<!-- Position Puck (Dieter Rams Instrument Style) -->`.
|
||||
|
||||
**Visual rules enforced by the design system (from `telemetry_rams/DESIGN.md`):**
|
||||
- Zero border radius (`0px`) on all containers, buttons, cards, badges, inputs.
|
||||
- No shadows-with-blur, no frosted glass, no faux 3D; hierarchy via `1px`/`2px` solid
|
||||
`#1A1A1A` rules and background shifts (`soft-beige` → `chassis-subtle`).
|
||||
- Uppercase labels with expanded tracking (`tracking-wider`/`tracking-widest` on
|
||||
`label-*` classes); alphanumeric reference badges in the form `SEC-04 // SPEED`,
|
||||
`CH-08`, `NEXT MANEUVER // T-01`.
|
||||
- Icons: Material Symbols or inline `<svg>` with uniform stroke weights (2px standard,
|
||||
3–4px in HUD), `stroke-linecap="square"`, `stroke-linejoin="miter"`.
|
||||
- Color semantics are strict: orange = navigation/primary action, red = hazards/errors only,
|
||||
olive green = safe/confirmation, map imagery grayscale.
|
||||
|
||||
**Comment density:** section-level comments only — no per-element commentary. Keep this.
|
||||
|
||||
## JavaScript (inline in mockups only)
|
||||
|
||||
- Vanilla, no framework, small inline `<script>` block at end of body.
|
||||
- Functions are `camelCase`, verb-first, one per interaction:
|
||||
`initBraunConsole`, `updatePreview`
|
||||
(`stitch_minimalist_route_navigator/community_incident_reporter/code.html:159-177`);
|
||||
`toggleHazardCard`, `reportHazardModal`, `closeHazardDrawer`, `confirmDispatch`,
|
||||
`triggerQuickDispatch`, `pulseRecenter`, `toggleLayers`
|
||||
(`stitch_minimalist_route_navigator/navigate_map_overview/code.html:266-323`);
|
||||
`insertCommand` (`stitch_minimalist_route_navigator/telegram_live_traffic_feed/code.html:235`).
|
||||
- Interaction is triggered via inline `onclick="…"` on buttons (mockups are
|
||||
demonstration-only; do not carry this pattern into production code — use real event
|
||||
listeners/framework handlers when real code exists).
|
||||
|
||||
## Where Conventions Are NOT Yet Established
|
||||
|
||||
The following have no governance in the repo and must be decided/pinned when real code
|
||||
starts:
|
||||
|
||||
- **Languages/runtime:** no manifest declares TypeScript/JavaScript versions, Node, or
|
||||
package manager (no `package.json`, `go.mod`, `pyproject.toml` anywhere).
|
||||
- **Formatting & linting:** no Prettier/ESLint/Biome/editorconfig. HTML mockups are
|
||||
generated with minified head lines and expanded body lines; treat as generator output,
|
||||
not hand-formatted style.
|
||||
- **Module layout / imports:** no application code, no `src/`, no import graph.
|
||||
- **Error handling, logging, validation:** no code exists to define patterns for these.
|
||||
- **Git hygiene:** the workspace directory is not yet a git repository; when initialized,
|
||||
add a `.gitignore` and commit `DESIGN.md`, `IDEAS.md`, `stitch_minimalist_route_navigator/*`.
|
||||
- **Path casing:** any backend service (Telegram bot, OSRM, Neon/Postgres — the stack
|
||||
sketched in `IDEAS.md:55-73`) should follow the existing `snake_case` directory naming
|
||||
for consistency.
|
||||
|
||||
## Prescriptive Guidance for New Code
|
||||
|
||||
1. **New mockup screen:** create `stitch_minimalist_route_navigator/<new_screen_snake_case>/`
|
||||
with `code.html` and `screen.png`. State which design tokens it uses; do not invent
|
||||
new colors without adding them to the frontmatter of
|
||||
`stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md` first.
|
||||
2. **New design token:** update the YAML block in
|
||||
`stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`, then replicate the token
|
||||
into the inline `tailwind.config` of **all four** existing `code.html` files.
|
||||
3. **First real implementation code:** before writing it, codify the above — add a package
|
||||
manifest, formatter/linter config, and a source directory; mirror `camelCase` for
|
||||
functions, `kebab-case` for classes/CSS tokens, `snake_case` for directories.
|
||||
|
||||
---
|
||||
|
||||
*Convention analysis: 2026-10-21*
|
||||
@@ -0,0 +1,104 @@
|
||||
# External Integrations
|
||||
|
||||
**Analysis Date:** 2026-10-21
|
||||
|
||||
## Project Maturity Note
|
||||
|
||||
There is **no running integration code** in this repository yet — no backend, no SDK packages, no environment files. This document is based on what is *actually wired* in the static mockups plus the integration architecture explicitly declared in `IDEAS.md` ("Architecture Overview") and `DESIGN.md` ("Interaction Flows"). Items marked **[actual]** are live CDN dependencies; items marked **[planned]** are targets for the first implementation and should be verified/re-selected when that phase is planned.
|
||||
|
||||
## APIs & External Services
|
||||
|
||||
**Bot Transport (planned — the product's primary "frontend"):**
|
||||
- Telegram Bot API — commands and inline queries for incident reports and navigation (`IDEAS.md`: "Telegram-first")
|
||||
- SDK/Client: not chosen yet; no package installed
|
||||
- Auth: bot token (env var to be introduced; none exists)
|
||||
- Command surface from `DESIGN.md` / `IDEAS.md`: `/report accident|traffic|hazard` with location share, `/navigate origin → destination`, geohash-style broadcast of nearby events
|
||||
|
||||
**Routing (planned):**
|
||||
- OSRM — route computation with "dynamic traffic weighting" (`IDEAS.md`; also `DESIGN.md` flow: `/navigate origin → destination → OSRM route → text directions + map snapshot`)
|
||||
- SDK/Client: none; OSRM is a plain HTTP API
|
||||
- Auth: none required for self-hosted; hosting decision (self-host vs public server) not yet made
|
||||
|
||||
**Map Tiles (planned):**
|
||||
- Maptiler — map tiles for grayscale map snapshots (`IDEAS.md`, `DESIGN.md` "Map Snapshots: Grayscale tiles with accent overlays")
|
||||
- SDK/Client: none; HTTP tile API
|
||||
- Auth: API key (to be added to env config)
|
||||
|
||||
**CDN services actually referenced by the mockups [actual]:**
|
||||
- `cdn.tailwindcss.com` — Tailwind Play CDN script, in all four screens (`*`/`code.html`)
|
||||
- `fonts.googleapis.com` + `fonts.gstatic.com` — Geist, Space Grotesk, Material Symbols Outlined
|
||||
- `lh3.googleusercontent.com/aida/...` — placeholder screenshot URLs embedded in mockups (tool-generated assets, should be replaced by project-generated images before reuse)
|
||||
|
||||
**Email (planned, low priority):**
|
||||
- Resend — transactional email (`IDEAS.md`). Purpose is not specified further; may not be needed for the MVP.
|
||||
|
||||
## Data Storage
|
||||
|
||||
**Databases:**
|
||||
- Neon — serverless Postgres with PostGIS extension for spatial queries (`IDEAS.md`) [planned]
|
||||
- Connection: env var to be introduced (none exists)
|
||||
- Client/ORM: none chosen yet
|
||||
- Spatial needs: storing incident reports with coordinates + "broadcast nearby" radius queries (PostGIS ` geography` point search)
|
||||
|
||||
**File Storage:**
|
||||
- Cloudflare R2 — blob storage for map snapshots/UAV-style images (`IDEAS.md`) [planned]
|
||||
- Current mockup screens store images as static `screen.png` files locally; no storage integrated
|
||||
|
||||
**Caching:**
|
||||
- None integrated; none planned explicitly. Route/traffic data caching is implied if OSRM traffic weighting is implemented, but not documented.
|
||||
|
||||
## Authentication & Identity
|
||||
|
||||
**Auth Provider:**
|
||||
- None [actual]
|
||||
- Planned: Telegram identity is the implicit identity layer — the bot sees `chat_id`/`user_id` directly from Telegram (`IDEAS.md` gamification: points and leaderboards via Telegram bot). No separate auth system is documented; a first implementation should treat Telegram user IDs as the primary key and require no passwords.
|
||||
|
||||
## Monitoring & Observability
|
||||
|
||||
**Error Tracking:**
|
||||
- None [actual]
|
||||
|
||||
**Metrics (planned):**
|
||||
- Prometheus + Grafana — monitoring stack named in `IDEAS.md`; exporters/what-to-observe not yet defined.
|
||||
|
||||
**Logs:**
|
||||
- Not detected. No logging framework or convention exists yet.
|
||||
|
||||
## CI/CD & Deployment
|
||||
|
||||
**Hosting (planned):**
|
||||
- Cloudflare Pages — for the optional PWA (`IDEAS.md`). Backend bot hosting platform is **undecided** (no doc names one).
|
||||
|
||||
**CI Pipeline:**
|
||||
- None [actual]. No workflow/CI config files exist.
|
||||
|
||||
## Webhooks & Callbacks
|
||||
|
||||
**Incoming:**
|
||||
- None [actual]
|
||||
- Planned: Telegram webhook for bot updates (polling vs webhook not yet decided — choose during first backend phase)
|
||||
|
||||
**Outgoing:**
|
||||
- None [actual]
|
||||
- Planned: none required by design; bot notifications to users are bot API calls, not webhooks
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
**Required env vars (none exist yet — this is the target list for the first backend phase):**
|
||||
- Telegram bot token
|
||||
- Neon database URL (with `?sslmode=require` and PostGIS-enabled DB)
|
||||
- Maptiler API key
|
||||
- OSRM base URL (+ optional traffic-weighting config)
|
||||
- Cloudflare R2 credentials (account ID, access key, secret, bucket) — **only if** snapshot storage is implemented in R2
|
||||
- Resend API key (optional; likely defer avoid until email feature is justified)
|
||||
|
||||
**Secrets location:**
|
||||
- Nothing exists. `.env` files are not present and should **not** be committed when introduced; no `.gitignore` exists yet — create one before adding any secret to disk (the repo is not currently a git repository).
|
||||
|
||||
## Gamification (planned feature, needs platform choices)
|
||||
|
||||
- Points for validated reports + leaderboards served through the Telegram bot (`IDEAS.md`). Requires: user scoring tables in Neon Postgres; no external service implied beyond Telegram itself.
|
||||
|
||||
---
|
||||
|
||||
*Integration audit: 2026-10-21*
|
||||
@@ -0,0 +1,89 @@
|
||||
# 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 are hosted/lifted from Google-hosted sample assets (`lh3.googleusercontent.com/aida/...` URLs appear in some screens' `<img>`/`src` attributes) — placeholders from the Stitch tooling, not project data
|
||||
|
||||
**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*
|
||||
@@ -0,0 +1,116 @@
|
||||
# Codebase Structure
|
||||
|
||||
**Analysis Date:** 2026-10-21
|
||||
|
||||
## Directory Layout
|
||||
|
||||
```
|
||||
araharah/
|
||||
├── .planning/ # GSD planning artifacts (this analysis)
|
||||
│ └── codebase/ # Codebase map documents
|
||||
├── DESIGN.md # Design philosophy: palette, typography, iconography, flows
|
||||
├── IDEAS.md # Product vision, principles, implied target stack
|
||||
└── stitch_minimalist_route_navigator/ # UI mockup suite ("Telemetry Rams" screens)
|
||||
├── active_route_guidance/
|
||||
│ ├── code.html # Turn-by-turn navigation HUD mockup
|
||||
│ └── screen.png # Visual capture of the screen
|
||||
├── community_incident_reporter/
|
||||
│ ├── code.html # Incident report flow mockup
|
||||
│ └── screen.png # Visual capture
|
||||
├── navigate_map_overview/
|
||||
│ ├── code.html # Full-map navigation overview mockup
|
||||
│ └── screen.png # Visual capture
|
||||
├── telegram_live_traffic_feed/
|
||||
│ ├── code.html # Telegram bot traffic feed mockup
|
||||
│ └── screen.png # Visual capture
|
||||
├── telemetry_rams/
|
||||
│ └── DESIGN.md # Formal design system spec (tokens + component rules)
|
||||
│ # (no screen.png — this is the design system, not a screen)
|
||||
└── */:Zone.Identifier # Windows download metadata — ignore everywhere
|
||||
```
|
||||
|
||||
## Directory Purposes
|
||||
|
||||
**Root (`/`):**
|
||||
- Purpose: Planning documents for a not-yet-implemented product
|
||||
- Contains: `DESIGN.md` (85 lines, design philosophy) and `IDEAS.md` (95 lines, vision + implied target stack)
|
||||
- Key files: `DESIGN.md`, `IDEAS.md`
|
||||
|
||||
**`stitch_minimalist_route_navigator/`:**
|
||||
- Purpose: Self-contained static HTML mockups of the app's four key screens, generated with the "Telemetry Rams" design system (Rams-minimalist telemetry aesthetic)
|
||||
- Contains: One subdirectory per screen; each screen dir holds `code.html` + `screen.png`
|
||||
- Key files: `active_route_guidance/code.html` (189 lines), `navigate_map_overview/code.html` (344 lines), `telegram_live_traffic_feed/code.html` (302 lines), `community_incident_reporter/code.html` (274 lines)
|
||||
|
||||
**`stitch_minimalist_route_navigator/telemetry_rams/`:**
|
||||
- Purpose: Canonical design-system definition (YAML front matter with `colors`, `typography`, `spacing`; then component specs)
|
||||
- Contains: `DESIGN.md` (241 lines) — the only non-root, non-screen documentation
|
||||
- Key files: `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`
|
||||
|
||||
**`.planning/`:**
|
||||
- Purpose: GSD planning artifacts; hosts `.planning/codebase/` documents (written by this analysis)
|
||||
- Generated: Yes (GSD tooling)
|
||||
- Committed: Yes (treat as project documentation)
|
||||
|
||||
## Key File Locations
|
||||
|
||||
**Entry Points:**
|
||||
- `stitch_minimalist_route_navigator/{screen}/code.html`: Open directly in a browser; each is a standalone mockup. No build step required (Tailwind/fonts load from CDN).
|
||||
- No application entry points exist (`no src/`, no `index.*`, no `main.*`, no package manifest).
|
||||
|
||||
**Configuration:**
|
||||
- No config files exist (no `package.json`, `tsconfig.json`, `.eslintrc`, `.env*`, lockfile, or CI config detected).
|
||||
- Design configuration lives in prose/YAML: `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`.
|
||||
|
||||
**Core Logic (current):**
|
||||
- All interactivity is inline demo JS inside each `code.html` (e.g., `insertCommand('/hazard ...')`, `toggleLayers()`, `confirmDispatch()`, `closeHazardDrawer()`). See `navigate_map_overview/code.html` and `telegram_live_traffic_feed/code.html` for the richest handler sets.
|
||||
|
||||
**Testing:**
|
||||
- No test files or test framework present. Not applicable yet.
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
**Files:**
|
||||
- Screens use lowercase `snake_case` directory names naming the screen purpose: `active_route_guidance`, `navigate_map_overview`, `telegram_live_traffic_feed`, `community_incident_reporter`
|
||||
- Fixed per-screen filenames: `code.html` (mockup source) and `screen.png` (capture)
|
||||
- Top-level docs use `UPPER-SNAKE.md`: `DESIGN.md`, `IDEAS.md`
|
||||
|
||||
**Directories:**
|
||||
- `snake_case` throughout (`stitch_minimalist_route_navigator`, `telemetry_rams`, `.planning/codebase`)
|
||||
|
||||
**In-code naming (mockups):**
|
||||
- CSS utility classes map to design tokens: `signal-orange`, `matte-black`, `soft-beige`, `functional-red`, `olive-green`, `chassis-subtle`, `surface-*` variants
|
||||
- JS demo functions use camelCase: `insertCommand`, `toggleLayers`, `confirmDispatch`, `closeHazardDrawer`, `updatePreview`
|
||||
- Section reference badges follow an uppercase `SEC-XX // LABEL` convention (e.g., `SEC-STACK // EXEC`, `CH-08`)
|
||||
|
||||
## Where to Add New Code
|
||||
|
||||
**New mockup screen:**
|
||||
- Create `stitch_minimalist_route_navigator/<screen_name_snake_case>/` containing `code.html` (self-contained, Tailwind CDN + inline `tailwind.config` with the Telemetry Rams tokens + inline SVG glyphs) and a `screen.png` capture
|
||||
- Follow the register-band layout documented in `telemetry_rams/DESIGN.md` (top/center/lower registers, 8px grid, 0px radius)
|
||||
|
||||
**Applying design tokens:**
|
||||
- Copy token values from `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md` (colors, typography, spacing) into the new screen's inline `tailwind.config`; keep the five core colors verbatim (`signal-orange: #EB8008`, `functional-red: #ED3F1C`, `olive-green: #736B1E`, `soft-beige: #D9D2C6`, `matte-black: #1A1A1A`)
|
||||
|
||||
**Documentation:**
|
||||
- Product-level ideas/stack changes → `IDEAS.md` (root)
|
||||
- Design philosophy changes → `DESIGN.md` (root)
|
||||
- Formal token/component spec changes → `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`
|
||||
|
||||
**Future implementation code (when project leaves design phase):**
|
||||
- No conventional locations exist yet. The implied target stack in `IDEAS.md` (Telegram bot backend, Neon Postgres, OSRM, Cloudflare Pages/R2) will need a conventional `src/` or service layout to be established by the first planning phase.
|
||||
|
||||
## Special Directories
|
||||
|
||||
**`.planning/`:**
|
||||
- Purpose: GSD planning/orchestration artifacts
|
||||
- Generated: Yes, by GSD commands
|
||||
- Committed: Yes
|
||||
|
||||
**`*:Zone.Identifier` files:**
|
||||
- Purpose: None (Windows download metadata attached to every HTML/PNG/MD file)
|
||||
- Generated: Yes (OS artifact)
|
||||
- Committed: Accidentally present — should be excluded from version control and any future lint/build globbing (add to `.gitignore`: `*:Zone.Identifier`)
|
||||
|
||||
---
|
||||
|
||||
*Structure analysis: 2026-10-21*
|
||||
@@ -0,0 +1,108 @@
|
||||
# Testing Patterns
|
||||
|
||||
**Analysis Date:** 2026-10-21
|
||||
|
||||
> **Status: No tests exist yet.** There are no test files, no test runner configuration,
|
||||
> no package manifest, and no CI pipeline in this repository. This document records what
|
||||
> is verifiably absent today and prescribes the testing conventions the project should
|
||||
> adopt when real implementation code begins, based on the stack targets declared in
|
||||
> `IDEAS.md`.
|
||||
|
||||
## Test Framework
|
||||
|
||||
**Runner:**
|
||||
- None installed. No `package.json`, no `vitest.config.*` / `jest.config.*` /
|
||||
`playwright.config.*` exists anywhere in the repository.
|
||||
- Run commands: Not applicable — nothing to run.
|
||||
|
||||
**Assertion Library:** None.
|
||||
|
||||
**Application code under test:** None. The only executable artifacts are inline scripts
|
||||
inside the generated mockup files (`stitch_minimalist_route_navigator/*/code.html`),
|
||||
which are demonstration-only and not structured for testing.
|
||||
|
||||
## Test File Organization
|
||||
|
||||
**Current state:** Not established. No `tests/`, `__tests__/`, `*.test.*`, or `*.spec.*`
|
||||
files exist.
|
||||
|
||||
**Prescribed convention (for future code):**
|
||||
- Place tests adjacent to the code they cover (`*.test.ts` next to the module) once a
|
||||
source directory exists.
|
||||
- There are no `--paths` subtrees pinned yet; the whole repo is effectively design docs +
|
||||
mockups (`DESIGN.md`, `IDEAS.md`, `stitch_minimalist_route_navigator/`).
|
||||
|
||||
## Recommended Stack Mapping (targets from `IDEAS.md`)
|
||||
|
||||
The planned architecture in `IDEAS.md:55-73` implies these test layers when implemented:
|
||||
|
||||
| Planned component | Where it's described | Suggested test approach |
|
||||
|---|---|---|
|
||||
| Telegram bot commands (`/report`, `/navigate`, `/accident`) | `IDEAS.md:19-27`, `DESIGN.md:67-73` | Unit tests on command parsing/state machines; integration tests against a Telegram Bot API test token or a stubbed client |
|
||||
| OSRM route fetch + traffic weighting | `IDEAS.md:63`, `DESIGN.md:71` | Contract tests against a recorded/stubbed OSRM response; regenerate fixtures when branching logic changes |
|
||||
| Neon Postgres + PostGIS report storage & nearby broadcast | `IDEAS.md:61`, `DESIGN.md:69` | Integration tests against an ephemeral Postgres + PostGIS extension (e.g., testcontainers-style setup in CI) |
|
||||
| Map snapshot generation (Maptiler tiles, R2 storage) | `IDEAS.md:64-69` | Golden-image tests only if snapshots are rendered locally; otherwise HTTP-mock the tile/R2 clients |
|
||||
| RabbitMQ queue consumers | `IDEAS.md:67` | Unit-test handlers with in-memory queue; defer broker-level tests to a single CI integration job |
|
||||
|
||||
## Mocking
|
||||
|
||||
**Framework:** None (no tooling yet).
|
||||
|
||||
**Prescribed patterns for future code:**
|
||||
- Mock only true boundaries: Telegram Bot API client, OSRM HTTP client, Maptiler tile
|
||||
fetcher, RabbitMQ producer, R2 uploader. Do **not** mock internal handlers, parsers,
|
||||
or design-token usage.
|
||||
- Prefer injectable clients over module-level singletons so tests can pass fakes;
|
||||
when the bot entry point is created, keep a thin wiring layer and a pure core.
|
||||
|
||||
## Fixtures and Factories
|
||||
|
||||
**Test Data:** None exists.
|
||||
|
||||
**Prescribed convention:**
|
||||
- Create a `fixtures/` (or `test/fixtures/`) directory for recorded OSRM responses,
|
||||
Telegram update payloads, and tile responses. Store raw payloads, not hand-typed
|
||||
paraphrases, so contract drift is catchable.
|
||||
- Use small factory functions (e.g., `makeIncidentReport(overrides)`) over large literal
|
||||
blocks once domain types exist.
|
||||
|
||||
## Coverage
|
||||
|
||||
**Requirements:** None enforced (no runner, therefore no coverage tooling).
|
||||
|
||||
**View Coverage:** Not applicable until a runner is configured; when it is, wire coverage
|
||||
into the runner config rather than a separate tool.
|
||||
|
||||
## Manual Verification (what exists today)
|
||||
|
||||
Since there is no automated checking, the only "testing" currently possible is manual:
|
||||
|
||||
- **Visual review:** each mockup has a rendered screenshot pair
|
||||
(`stitch_minimalist_route_navigator/<screen>/code.html` + `<screen>/screen.png`) —
|
||||
four screens: `active_route_guidance`, `navigate_map_overview`,
|
||||
`community_incident_reporter`, `telegram_live_traffic_feed`. Compare `code.html`
|
||||
rendering against `screen.png` after any token or config edit (the inline
|
||||
`tailwind.config` block is duplicated across all four files and must stay in sync).
|
||||
- **Interactivity smoke check:** mockups contain small inline JS handlers — e.g.,
|
||||
`reportHazardModal`, `confirmDispatch`, `triggerQuickDispatch`
|
||||
(`stitch_minimalist_route_navigator/navigate_map_overview/code.html:288-314`) and
|
||||
`insertCommand`
|
||||
(`stitch_minimalist_route_navigator/telegram_live_traffic_feed/code.html:235`).
|
||||
These are demo-only; verifying them means opening the HTML in a browser and clicking
|
||||
through buttons. Do not invest in automated tests for these scripts; they will be
|
||||
replaced by real implementation code.
|
||||
|
||||
## Gaps That Should Become Early Phases
|
||||
|
||||
1. **Test scaffold phase:** first real-code phase should add a package manifest with a
|
||||
test runner + lint config in the same commit, before business logic.
|
||||
2. **CI job:** once a runner exists, add a minimal pipeline (install → lint → test) — no
|
||||
CI config exists today (`.github/workflows/`, etc. absent).
|
||||
3. **Design-token regression:** consider a lightweight check that the four `code.html`
|
||||
`tailwind.config` blocks match the token table in
|
||||
`stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md` (a snapshot/diff test is
|
||||
sufficient; heavy visual-diff tooling is disproportionate for a mockup repo).
|
||||
|
||||
---
|
||||
|
||||
*Testing analysis: 2026-10-21*
|
||||
Reference in New Issue
Block a user