117 lines
6.6 KiB
Markdown
117 lines
6.6 KiB
Markdown
# 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*
|