c-fu/arah2
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: generate + verify project documentation — canonical docs, per-package READMEs, verified fix pass

Browse Source 
- New: docs/ARCHITECTURE.md, docs/GETTING-STARTED.md, docs/DEVELOPMENT.md,
  docs/TESTING.md, docs/CONFIGURATION.md (colored mermaid diagrams, quoted labels)
- Regenerated README.md (arah² / arah2bot naming, canonical clone URL)
- New per-package READMEs: theme/, bot/, web/
- Verified 13 docs against the live codebase (2 fix iterations + 2 residual
  corrections); corrected 56 stale claims across AGENTS/DESIGN/IDEAS/GSD_FIX
This commit is contained in:
araharah-executor
2026-10-23 20:56:40 +08:00
parent af3edefbc6
commit 91ad0c9d93
12 changed files with 103 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+28 -25
View File
@@ -7,12 +7,14 @@ A privacy-respecting GPS navigation app delivered through Telegram: a waze-like
route navigator, but Telegram-first instead of an app store install, built on
OpenStreetMap data, and designed to Dieter Rams' principle of "less, but better".
Users search a destination (e.g. "KLCC") with the bot, tap into a Telegram Mini
App (webview hosted on Cloudflare Pages), and receive live route guidance while
App (webview served as Cloudflare Workers static assets (Workers superseded Pages — see bot/wrangler.jsonc)), and receive live route guidance while
driving. First users are in the Kuala Lumpur metro area.
Reference design docs: `DESIGN.md` (design philosophy), `IDEAS.md` (vision +
stack), `stitch_minimalist_route_navigator/` (4 UI mockup screens), and
`.planning/codebase/` (codebase map; current state is design-only, no app code).
`.planning/codebase/` (codebase map; the repo has substantial app code: `bot/`
(grammY TypeScript worker), `web/` (Vite MapLibre Mini App), `theme/` (Tailwind v4
token package)).
**Core Value:** A user finds a local destination via Telegram and gets there with reliable
turn-by-turn guidance — tracked by nothing beyond what they explicitly opted in
@@ -40,20 +42,20 @@ to.
## Project Maturity
- 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)
- Static HTML UI mockup screens (one `code.html` + `screen.png` per screen) — legacy design reference; the executable code is the `bot/`, `web/`, and `theme/` workspaces
- Planning outputs: `.planning/` — not product code; it holds phase plans for the code that now exists
## Languages
- 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)
- HTML 5 — the mockup screens under `stitch_minimalist_route_navigator/*/code.html` are legacy reference; the active UI entry points are `web/` and `theme/gallery.html`
- TypeScript — the bot Worker (`bot/src/`) and the Vite Mini App (`web/src/`)
- Markdown — design docs (`DESIGN.md`, `IDEAS.md`, `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`)
- A backend language/runtime for the Telegram bot (not yet chosen in any doc; nothing in the repo constrains it)
## Runtime
- None installed. No `package.json`, no `requirements.txt`, no lockfile, no `.nvmrc`, no CI config, no test config anywhere in the repo.
- Installed: root `package.json` with npm workspaces `theme`, `bot`, `web`, plus `package-lock.json`. Test config lives in custom harnesses (`bot/test/runner.mjs`, `web/test/runner.mjs`, `theme/scripts/audit.test.mjs`). No `.nvmrc` and no CI config yet.
- Mockups run by opening `code.html` directly in a browser (CDN-based dependencies, no local dev server required).
## Frameworks
- 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.
- Not detected. No test framework, no test files.
- Not detected. No bundler, no formatter, no linter config. Mockups are standalone static files.
- Not detected. No third-party test framework; tests use custom `node:test`-style harnesses in `bot/test/` and `web/test/` (`runner.mjs` + `*.test.mjs` suites) plus `theme/scripts/audit.test.mjs`.
- Bundler: Vite (`web/vite.config.ts`). Theme has a token audit tool (`npm run audit -w theme`). No formatter or linter config.
- 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
- `cdn.tailwindcss.com` — theming engine for all screens
@@ -61,18 +63,18 @@ to.
- 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
- 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`)
- Routing engine: Valhalla + Photon are the validated stack per the project constraints; the OSRM references in older docs (`IDEAS.md`, `DESIGN.md`) are superseded
- 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`)
- Cloudflare Workers with static assets — hosts the Mini App (`bot/wrangler.jsonc` binds `../web/dist`); Cloudflare Pages is superseded. 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
- 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.
- `bot/.dev.vars.example` is the template (the real `bot/.dev.vars` is gitignored local secrets), plus `bot/wrangler.jsonc` and `bot/src/config.ts` (the typed `Env` contract). See `docs/CONFIGURATION.md` for the full variable list.
- 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
- Any modern browser to view the mockups; any text editor. No Node/Python runtime is required by current code.
- 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.
- Any modern browser to view the UI; any text editor. Node/npm are required (workspaces, Vite, wrangler); `python3` only for the theme gallery preview server (`npm run gallery` → `python3 -m http.server 8123`).
- Settled runtime: TypeScript + grammY on Cloudflare Workers with KV (`chat_sessions`). Neon Postgres, OSRM, RabbitMQ, and Resend are future/aspirational and are not deployed.
## Design-System Constraints (binding for future code)
- 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
@@ -111,9 +113,9 @@ to.
## Where Conventions Are NOT Yet Established
- **Languages/runtime:** no manifest declares TypeScript/JavaScript versions, Node, or
- **Formatting & linting:** no Prettier/ESLint/Biome/editorconfig. HTML mockups are
- **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,
- **Module layout / imports:** three `src/` trees with a full import graph: `theme/src/`, `web/src/`, `bot/src/`.
- **Error handling, logging, validation:** patterns exist — `bot/src/webhook.ts` secret validation + error handling, `bot/src/security/initdata.ts` HMAC validation, `web/test/no-storage.test.mjs` storage guard.
- **Git hygiene:** the workspace is a git repository (branch `main`); see the `.gitignore` rules for generated output and local secrets.
- **Path casing:** any backend service (Telegram bot, OSRM, Neon/Postgres — the stack
## Prescriptive Guidance for New Code
<!-- GSD:conventions-end -->
@@ -129,7 +131,7 @@ to.
|-----------|----------------|------|
| `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` |
| `telegram_live_traffic_feed/` | Telegram-bot-styled traffic feed mockup: inline commands (`/traffic`, `/hazard`, `/status`, `/clear`) via `insertCommand` handlers only — the dispatch-confirm interaction lives in `navigate_map_overview/code.html` (`confirmDispatch`) | `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` |
@@ -139,15 +141,16 @@ to.
- 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.
- The mockups remain inline-`onclick` demo stubs with no state management, but the real app interactivity lives in `web/` (Vite/TypeScript Mini App) and the `bot/` command handlers.
## 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)
- Frontend: Telegram Bot interface + optional PWA hosted on Cloudflare Pages
- Frontend: Telegram Bot interface + Mini App served by the Cloudflare Worker's static assets (Pages superseded); optional PWA remains future
- 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
- Routing: not wired yet — Valhalla + Photon is the validated target stack (OSRM references superseded)
- Services: RabbitMQ for event queueing; Resend for email
- Data: Neon (Postgres + PostGIS) for event/route storage; Cloudflare R2 for map snapshot storage; Tiles: OpenFreeMap today (`theme/basemap/liberty-rams.json`); Maptiler was the original idea
- Observability: Prometheus + Grafana
## Data Flow
### Mockup Screen Flow (current)
@@ -158,10 +161,10 @@ to.
- 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)
- Each screen is one directory holding exactly `code.html` (the mockup) and `screen.png` (a visual capture)
- Each of the four mockup screen directories holds exactly `code.html` (the mockup) and `screen.png` (a visual capture); `telemetry_rams/` holds only its `DESIGN.md`
- Examples: all four screen directories under `stitch_minimalist_route_navigator/`
- 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')`)
- Examples: `stitch_minimalist_route_navigator/telegram_live_traffic_feed/code.html` (its actual handlers are `insertCommand('/traffic ')` / `insertCommand('/hazard ')` / `insertCommand('/status ')` / `insertCommand('/clear ')` plus a single `alert('Reroute broadcast loaded.')`; no `confirmDispatch` exists)
## Entry Points
- 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)
@@ -171,7 +174,7 @@ to.
- **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.
- **Windows Zone.Identifier files:** no `*:Zone.Identifier` files exist anymore; the `.gitignore` rule for them remains as hygiene.
## Anti-Patterns (recommendations for the target codebase)
### Per-file Tailwind config duplication
### Inline onclick demo handlers