From afce46ccf875d1a7b7f24d7d30b6780006a16fb4 Mon Sep 17 00:00:00 2001 From: Andras Schmelczer Date: Sun, 31 May 2026 10:49:26 +0100 Subject: [PATCH] docs: add CLAUDE.md agent guide, drop legacy design/API specs, refresh READMEs --- CLAUDE.md | 291 +++++++++++++++++ README.md | 14 +- docs/DESIGN.md | 795 --------------------------------------------- docs/api-spec.md | 127 -------- frontend/README.md | 62 +--- 5 files changed, 307 insertions(+), 982 deletions(-) create mode 100644 CLAUDE.md delete mode 100644 docs/DESIGN.md delete mode 100644 docs/api-spec.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..091d70c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,291 @@ +# Life Towers — agent notes + +This file captures the load-bearing things to know about this codebase. Read it before making non-trivial changes. + +## What this is + +A personal-productivity TODO app where each user has multiple **pages**, each page holds several **towers** (vertical task columns), and each tower has **blocks** (atomic tasks). Pending blocks live in a **tasks accordion** at the top of the tower; completed ones fall into the tower as colored squares (the "falling animation" is the defining visual). Date-range slider filters which done blocks are visible. + +This is a port/modernisation of a legacy Angular 7 app. **Design parity with the legacy is a hard requirement** — the user cares deeply about the original aesthetic. The legacy source lives at `_legacy_reference/` (gitignored) and is the source of truth for any visual question. A detailed style guide is at `docs/DESIGN.md`. + +## Repo layout + +``` +backend/ # FastAPI + SQLite (WAL) + src/life_towers/ + main.py # ASGI app, lifespan, static mount + SPA fallback + api.py # Routes (/api/v1/{health,register,data}) + auth.py # Bearer UUIDv4 → user_id + db.py # sqlite3 factory + migration runner + limits.py # slowapi limiter + payload-size middleware + models.py # pydantic v2 schemas + logging.py # structlog JSON + migrations/ # 001_initial.sql consolidated schema + tests/test_api.py # pytest + httpx AsyncClient + pyproject.toml # uv-managed +frontend/ # Angular 21+ standalone, signals, zoneless + src/app/ + components/ + pages/ # Top-level: page selector + Settings button + page/ # Tower row + slider + trash zone + confirm-delete + tower/ # White tower card: tasks accordion + add-block + falling stack + name input + block/ # Colored square (1/6 tower width) + tasks/ # Pending-blocks accordion with tickbox + welcome/ # Zero-state intro modal + "Try an example" + modal/ # Generic backdrop shell + sub-modals (block-edit carousel, settings, tower-settings) + shared/ # select-add, toggle, double-slider, color-picker, icon + services/ + api.service.ts # HttpClient wrapper, exact API contract + store.service.ts # signal-based store, debounced PUT, retry, loadExample + modal-state.service.ts # global open-modal counter (drag locking) + models/index.ts # Page / Tower / Block / HslColor TS interfaces + utils/{color,hash}.ts + library/ # Legacy SCSS dropped in verbatim — DO NOT REFACTOR + public/assets/ # SVG icons (arrow, pen, plus-sign, trash, x-sign) + src/assets/fonts/ # Self-hosted woff2 (Open Sans Condensed, Raleway, …) + e2e/ # Playwright (smoke + visuals) +docs/ + api-spec.md # Single source of truth for the HTTP API contract + DESIGN.md # Legacy visual spec (verbatim SCSS quotes) +_legacy_reference/ # Original Angular 7 source — read-only, gitignored +Dockerfile # Multi-stage: node:22-alpine build → python:3.13-slim runtime +docker-compose.yml # Production single-container +docker-compose.dev.yml # Ephemeral volume for Playwright runs +.forgejo/workflows/ # CI + deploy +``` + +## Tech stack quickrefs + +- **Frontend**: Angular 21+, **standalone components** (no NgModule), `signal()` / `computed()` / `effect()` / `linkedSignal()`, **zoneless change detection** (`provideZonelessChangeDetection`), `@if`/`@for` control flow, **OnPush** everywhere, esbuild builder (`@angular/build:application`), Reactive Forms, Angular Service Worker (PWA), Angular CDK (drag-drop, A11yModule for focus trap) +- **Backend**: FastAPI, pydantic v2, slowapi (rate limiting), structlog, **sqlite3 with WAL + foreign_keys ON** every connection, uv-managed deps +- **Runtime topology**: single Docker container — FastAPI process serves both `/api/v1/*` JSON endpoints AND the built Angular SPA as static files with SPA fallback. Behind nginx; uvicorn launched with `--proxy-headers --forwarded-allow-ips=*` +- **Storage**: SQLite at `/data/life-towers.db` on a named Docker volume. Tree-replace semantics (PUT replaces user's full tree atomically inside `BEGIN IMMEDIATE`) + +## Build / dev / test / deploy + +```bash +# Full local stack (ephemeral data) +docker compose -f docker-compose.dev.yml up --build -d # http://localhost:8000 +docker compose -f docker-compose.dev.yml down -v # teardown + +# Frontend dev (with backend proxied via proxy.conf.json) +cd frontend && npm start # ng serve on :4200, /api → :8000 +cd frontend && npm run build # production bundle to dist/frontend/browser/ +cd frontend && npm test # vitest (--run already in the script) +cd frontend && npm run test:e2e # Playwright + +# Backend dev +cd backend && uv sync +cd backend && uv run pytest -v +cd backend && uv run uvicorn life_towers.main:app --reload # :8000 + +# E2E in the sandbox: host-to-container port forwarding is broken here. +# Run Playwright INSIDE a container on the docker network instead: +docker run --rm \ + --network life-towers_default \ + -v "$(pwd)/frontend:/work" -w /work \ + -e PLAYWRIGHT_BASE_URL=http://life-towers:8000 \ + mcr.microsoft.com/playwright:v1.60.0-noble \ + npx playwright test +``` + +## Design system — the legacy is the source of truth + +`docs/DESIGN.md` is the comprehensive spec. Key tokens: + +```scss +// _legacy_reference/frontend/src/library/common-variables.scss +$accent-color: #a2666f; // rose +$text-color: #5d576b; // muted purple-grey (also iOS theme-color) +$light-color: #ffffff; +$background-gradient: linear-gradient(90deg, #fff9e07f 0, #ffd6d67f 100%); // 50% alpha — modal backdrop +$background-gradient-opaque: linear-gradient(90deg, #fffcf0 0, #ffebeb 100%); // body background +$shadow: 0 0 1.5px 1.5px rgba(0,0,0,0.1), 0 0 3px 2px rgba(0,0,0,0.05); +$shadow-border: 0 0 0 0.75px rgba(0,0,0,0.1); // hairline +$normal-font: 'Open Sans Condensed', sans-serif; +$title-font: 'Raleway', serif; +$mobile-width: 520px; +``` + +Spacing tokens (`library/main.scss`): +```scss +:root { + --large-padding: 30px; // 20px on mobile + --medium-padding: 15px; + --small-padding: 10px; // 7.5px on mobile + --border-radius: 5px; // 3px on mobile +} +``` + +Font sizes (`library/text.scss`): `--larger/large/medium/small-font-size` = `22/18/16/11` desktop, `20/16/14/10` mobile. + +**Animation timings**: +- `$long-animation-time: 200ms` — opacity, hover transforms, modal entry +- `$short-animation-time: 100ms` — tighter transitions (red trash-highlight overlay) +- **Falling animation**: `transform 1.5s cubic-bezier(0.5, 0, 1, 0)` (gravity ease-in) +- **Modal opacity entry/exit**: `300ms` + +## Architectural conventions to follow + +### Components + +- Every component is **standalone**, **OnPush**, with `signal()`-based local state. No NgModule. +- Templates use **`@if` / `@for` / `@switch`** — never `*ngIf`/`*ngFor`. +- Inline templates + inline styles in `@Component({ template: \`...\`, styles: \`...\` })` is the norm. Larger components use templateUrl + styleUrl (only `pages.component`, `page.component`). +- SCSS inside `styles:` template literal — **`//` comments are fine inside SCSS but watch for backticks**; `// `display: contents`` inside a template literal closes it early. Use `/* */` if you need to mention CSS strings in comments. +- Library files (`library/*.scss`) are dropped from the legacy verbatim. Don't refactor them. Components `@import '../../../library/main'` (or similar relative depth). + +### State + +- `StoreService` is the single source of truth (signal-based). +- Mutations update the signal immediately (**optimistic**) and call `scheduleSave()` which debounces 750ms and PUTs the full tree. +- Failure mode: exponential backoff up to 5 attempts (1s, 2s, 4s, 8s, 16s). +- LocalStorage cache key: `life-towers.cache.v4`. Token: `life-towers.token.v4`. +- `init()` flow: stored token? Use it. No token? Mint via `uuidV4()` → register → GET data. On 401: re-register the SAME token (idempotent server-side), never silently mint a fresh one (would orphan data). + +### Reactivity caveats with zoneless + +- Plain field mutations in event handlers (`(click)="x = true"`) still trigger CD because Angular's event manager marks the view dirty — even with zoneless. But any async mutation outside an Angular event (setTimeout, raw addEventListener, MutationObserver) **will not** trigger CD; use signals there. +- `effect()` running on `signal()` reads triggers re-runs; wrap writes in `untracked()` to avoid loops. +- For input-driven derived state that the user can also override (e.g. `tasks.expanded` seeded from `initiallyOpen` but also clickable), use either `linkedSignal` or `effect()` + a flag (the codebase uses the latter for `tasks.component`). + +### Sync model + +- **Tree-replace**: `PUT /api/v1/data` sends the entire user hierarchy atomically. Backend wraps in `BEGIN IMMEDIATE`, deletes existing pages (cascading to towers + blocks via FK), inserts new rows. `position` columns track ordering. +- **No granular endpoints** for individual entity CRUD. Keep it tree-replace. +- Spec is in `docs/api-spec.md`. Backend pydantic models match it. Frontend `models/index.ts` matches it. Field names are **snake_case** on both sides. + +### Backend + +- All endpoints are inside `APIRouter(prefix="/api/v1")`. Spec drives behavior — if you change a limit, update both spec and code. +- Migrations: package data under `src/life_towers/migrations/`, loaded via `importlib.resources.files("life_towers").joinpath("migrations")`. The runner tracks applied state in a `schema_migrations(filename TEXT PRIMARY KEY, applied_at INTEGER)` table. +- All sqlite connections must do `PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000`. The `get_connection()` factory does this. +- Errors → JSON `{"error": code, "detail": str}` via a single `HTTPException` handler in `main.py`. Stack traces never leak (logged server-side). +- Rate limits via slowapi: `/register` 30/hour/IP, `GET /data` 60/min/token, `PUT /data` 30/min/token. + +## Visual + interaction details that bit me + +### Falling animation (tower.component) + +The `.block-container` has `transform: scaleY(-1)` so blocks visually fall from the TOP into the bottom of the tower. Each block default-positions at `translateY(500%)` via a `*` rule; the inline `[style.transform]="b._transform"` binding overrides per-block. + +When exactly **one** new done block is added, the `reconcile()` method: +1. Sets the new block's `_transform: 'translateY(500%)'` and `_opacity: '0'` (off-screen) +2. Calls `requestAnimationFrame` → `requestAnimationFrame` to let the browser paint the initial state +3. Sets `_anim: 'descend'`, `_transform: 'translateY(0)'`, `_opacity: '1'` — the CSS transition fires + +**Critical**: `grewByOne` detection is position-independent (set-difference). When a tickbox flips a pending block to done, the new entry inserts at its original `tower.blocks` index, not appended. Use the new ID, not `styled[length-1]`. + +The **date range** slider asymmetry: blocks below `range.from` are removed from `visibleBlocks` entirely (instant shuffle, no gap), blocks above `range.to` get `_anim: 'ascend'` and stay in the list flying up. `prevDoneIds` tracks the full `allDone` array — not the filtered styled list — so range expansions don't mis-fire as "new block". + +### Block-edit carousel (modal/block-edit.component) + +- Lives at `position: fixed; z-index: 10001` to escape the modal dialog wrapper and cover the viewport +- Two placeholder cards flank the real cards so the active card can fully center via `scroll-snap-align: center` +- `.mask` overlay on non-active cards has three tiers: `active opacity 0`, `near-active 0.55`, default `1`. Card opacity also tiered (1 / 0.85 / 0.6) mimicking the legacy `1.33*(1-t/2)` curve +- Backdrop click (anywhere not a non-placeholder card) closes the modal +- Delete on an existing card **does not** close the modal — it stays open and the card re-renders out of the list +- Auto-save on tag/toggle change; description deferred to blur + +### Select-add (shared/select-add) + +- Has a `.top` chip and a `.bottom` slide-down panel. `:has(.bottom.open) .top, .background { border-radius: var(--border-radius) var(--border-radius) 0 0 }` squares the bottom corners when open so the chip and panel read as one card +- Shadow seam between chip + panel solved with `clip-path: inset(...)`: `.background.active` clips bottom (`inset(-6px -6px 0 -6px)`), `.bottom.open` clips top (`inset(0 -6px -6px -6px)`). 6px > the total $shadow spread (5px) so neither edge bleeds across the seam +- Closing animation requires a two-transition setup: default state has `transition: ... visibility 0s $long-animation-time` (visibility delays on close), `.open` overrides with `visibility 0s 0s` (instant on open) + +### Modal shell (modal/modal.component) + +- `:host { display: contents }` — critical. Without this, the `lt-modal` host element takes a flex slot in `pages.component`'s `inner-spacing` layout, pushing the Settings button up when the modal mounts +- `section.modal` is `position: fixed; z-index: 10000` with `transition: opacity 300ms`. The component flips `active = true` in `ngAfterViewInit` via `setTimeout(0)` so the opacity 0 → 1 transition runs +- `ModalStateService.open()` / `.close()` are called in `AfterViewInit`/`OnDestroy`. `page.component` reads `modalState.anyOpen` and binds it to every tower's `[cdkDragDisabled]` so users can't drag towers behind an open modal + +### Carousel card date format + +```ts +formatDate(ts: number): string { + return new Date(ts * 1000).toLocaleString(undefined, { + year: 'numeric', month: 'short', day: 'numeric', + hour: '2-digit', minute: '2-digit', + }); // "May 28, 2026, 14:32" +} +``` + +### Double-slider relative-time labels + +`page.component.ts` formats with `Intl.RelativeTimeFormat(undefined, { numeric: 'auto', style: 'short' })`. Buckets: `<45s` second, `<45min` minute, `<22h` hour, `<26d` day, `<320d` month, else year. Labels are **deduped** by string (multiple distinct timestamps that round to the same "5 hr ago" appear once). + +When `values.length` grows (new block added), the slider snaps the **higher** of `oneValue`/`otherValue` to `MAX - 1` so the newest entry is always visible; the lower thumb (the user's left edge) stays put. + +### Color picker (shared/color-picker) + +- Row of 12 preset color swatches + a rainbow hue slider + a big preview swatch +- Saturation and lightness are FIXED at 0.7 / 0.55. Only hue varies +- Preset hues `[0, 15, 30, 45, 195, 215, 235, 255, 280, 310, 335, 355]` — skips the green/yellow zone (60°–180°) which muddies with the rose accent palette + +### Tickbox (tasks/tasks.component) + +- `✓` glyph is hidden at rest (`opacity: 0`) and only revealed on interaction: `0.85` (hover/focus-visible), `1` (active). It fades via the `opacity` transition +- The tickbox is a `