karting-tools-notes

Design documentation and UI screenshots for Kart Data, a local-first, mobile-first trackside recorder for karting, and its Track Map Notebook feature module.

中文说明

This repository contains no application code. The application is karting-data-recording-website, which deploys from main to https://karting-data-recording-website.vercel.app. The Track Map Notebook module lives there under components/track-map/.

This repo exists so the design work and reference screenshots are backed up and reviewable in one place, independently of the app repository and of local machines.

The PF International reference map, and the built-in circuit picker. Captured 2026-09-10; the full set is listed below.

These are mirrored from an Obsidian vault, which remains the source of truth. See Keeping the docs in sync.

Why these live here and not in the application repository. The architecture note describes a feature module inside Kart Data, so it could reasonably sit beside that code. The idea backlog could not: it spans twelve separate tool concepts, most of which are not Kart Data, plus adjacent non-karting tools. That is portfolio-level planning, not application documentation. The two notes are also a linked pair, and separating them would break the wikilinks in both directions. Both therefore stay here, and this repository is the design and planning archive for the karting tools generally rather than for Kart Data alone.

Filed by capture date rather than overwritten. An image carries no date of its own, and an old screenshot of a changed interface is indistinguishable from a current one.

Captured 2026-09-10 from the live site at a 390x844 mobile viewport, dark theme, at 2x device pixel ratio. The files are therefore 780x1688.

Captured 14-15 August 2026, when the MVP shipped. These are a record, not documentation of the current app. Between the two sets the app gained four more circuits, corner numbering, a Simplified Chinese interface and a rebuilt PF International map.

These were taken at 1x, so the mobile ones are 390x844 rather than the 780x1688 of the current set. track-map-session-mobile.png is taller because the page scrolled, and pfi-default-map.png is a 1280x722 desktop capture rather than a phone one.

The Track Map Notebook MVP shipped on 2026-08-15 and the module has been developed since. As of the 2026-08-31 code it has five built-in circuits (PF International, Whilton Mill International, Kart Silverstone Grand Prix, Buckmore Park and Clay Pigeon Raceway), corner numbering derived from the map geometry, a marker taxonomy of corner phases and pedal inputs, a full Simplified Chinese interface, zoom and pan including pinch, session overlays, offline persistence, and backup/restore with map images.

Next Run focus was dropped rather than deferred: TrackVisit carries no focusMarkerIds and MarkerObservation has neither runId nor promoteToReference. Run-specific observations, racing lines, GPS and telemetry overlays remain unbuilt.

The architecture note here is a historical record, not current documentation. It describes the design as confirmed on 2026-08-15 and the implementation has since moved on, most visibly in the marker types, which were replaced outright. The living design document is DESIGN.md in the application repository, which carries its own change log. Where the two disagree, that document is correct. The note is kept for the reasoning behind the original decisions, and its storage design is still accurate.

The Obsidian vault is the source of truth. The copies in docs/ are byte-identical mirrors, and .gitattributes pins *.md to LF so core.autocrlf cannot rewrite them to CRLF on checkout and break that.

After editing the notes in Obsidian, copy them across before committing:

.\scripts\sync-docs.ps1

To check whether docs/ has gone stale without changing anything (exits 1 if it has, so it works as a pre-commit check):

.\scripts\sync-docs.ps1 -Check

The script only ever copies vault → repo, never the reverse, and never commits. If the vault moves, pass the new location with -VaultPath '<folder>'.

Exit codes: 0 up to date, 1 stale, 2 vault not found.

A tracked pre-commit hook in .githooks/pre-commit runs that check and refuses the commit while docs/ is behind the vault, so the mirror cannot drift by being forgotten. Enable it once per clone:

git config core.hooksPath .githooks

The hook only blocks on exit code 1. If the check cannot run at all — no vault on this machine, no PowerShell, script missing — it is skipped with a warning and the commit proceeds, because a check that is merely unavailable should never wedge the repository. To bypass it deliberately:

git commit --no-verify

Screenshots here are filed by capture date and move when a new set is taken, and each one is referenced from a table in both READMEs. A moved file breaks its row silently: GitHub renders a dead link without complaint. scripts/check-readme.ps1 catches that, and the same pre-commit hook runs it:

.\scripts\check-readme.ps1

It asserts that every relative link and image source in both READMEs resolves to a file that exists, that every file under screenshots/ is referenced by each README, and that the two reference the same set, so the Chinese copy cannot quietly fall behind the English one. External URLs and in-page anchors are left alone.

Exit codes: 0 all clear, 1 a problem was found, listed by file. Unlike the vault check this one needs nothing outside the repository, so it never legitimately skips. Both checks run on every commit even when the first fails, so one attempt reports everything rather than one problem at a time.

Because the notes are mirrored verbatim, Obsidian wikilinks such as [[Karting Tools - Idea Backlog]] render as literal text on GitHub rather than as links. That is deliberate: it keeps the two copies identical and the sync a plain file copy.

© 2026 Alex Liao. Everything in this repository — the design notes, the screenshots and the two helper scripts — is released under Creative Commons Attribution 4.0 International (CC BY 4.0). Reuse it however you like, with credit.

The PF International screenshots show a map whose geometry is derived from OpenStreetMap, which is © OpenStreetMap contributors under the Open Database License 1.0. That attribution is carried in the images themselves.