# 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*