c-fu/arah2
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d2e9ecfcd1d7404c49fbbfbbc66d75eb79c462ef
arah2/.planning/codebase/CONCERNS.md
T

15 KiB
Raw Blame History

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

Reference in New Issue View Git Blame Copy Permalink