# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. **This directory (`web3p1`) is a copy of `~/web2` with `/var/www/shtml/web3.1`'s design system merged in — read `DECISIONS.md` first.** Everything below this point was written for the original `~/web2` (still untouched, at that path) and is accurate for the architecture, data model, routing, and SEO/analytics wiring — none of that changed here. It is *not* accurate for anything DECISIONS.md documents as changed: fonts are EB Garamond + Commissioner now, not Alegreya/Noto Sans; `tokens.css` has a full space/radius/shadow/blur/motion/z-index scale now, not just color+type; the wayfinder is unhooked from every live page (code untouched, just not linked from `layout.php`/`home.php`); the homepage and CV page carry a Neural Thread scroll signature that didn't exist before. Where this file and `DECISIONS.md` disagree, `DECISIONS.md` is the newer, correct account. ## Repository state `PAGE.md` is the authoritative spec and takes precedence over anything below, which is only a summary — **read it in full before writing code.** The design token proposal (palette, type, breakpoint, wayfinder concept) was signed off before any implementation started; the confirmed values are recorded in this machine's Claude memory (`design-token-system`), not duplicated into this file. **The palette was revised 2026-07-05** (user feedback: the original read as too flat) — navy/oxblood/teal/brass, confirmed through a 3-round comparison artifact before touching any code; the memory file has the full rationale and exact hex values, `public/assets/css/tokens.css` has the implementation. Type/breakpoint/wayfinder-concept from the original sign-off are unaffected. Implementation has completed all five steps of PAGE.md's mandated build order: **shared data model**, **nav component**, **anatomical wayfinder**, **remaining page templates**, and **SEO/OG/sitemap/analytics wiring**. Every one of the 33 nav destinations plus every procedure/condition page resolves to a real, rendered page with real per-page SEO (title/description/canonical/hreflang/OG/Twitter/JSON-LD); `sitemap.xml`/`robots.txt` are generated from the same route list; GA4 is gated behind a real cookie-consent banner. What's left is everything PAGE.md explicitly stubbed rather than asking to be invented - see `Config` and the flagged pending-content pages below - plus real browser testing (no headless browser here, see below). Since the brief mandates no Composer and no Node.js, there is no package manifest or build step. Run the site locally with PHP's built-in server from the `public/` document root, **passing `public/index.php` as the router script**: ``` php -S localhost:8000 -t public public/index.php ``` The router-script argument matters and isn't optional now: without it, PHP's built-in server 404s `/sitemap.xml` and `/robots.txt` directly (it treats any path with a recognized extension as "should be a static file" and never invokes PHP for those specifically, unlike extensionless paths, which happen to fall through to `index.php` automatically even without a router argument - inconsistent, and only extension-based paths expose it). `index.php` has a `PHP_SAPI === 'cli-server'` guard at the top that hands static-file requests back to the built-in server once a router script is in play, so `/assets/...` keeps working too. That guard never runs under Apache/PHP-FPM (the real deployment target), which resolves static files and rewrites the rest to `index.php` via `public/.htaccess` on its own. Lint any PHP file with `php8.2 -l path/to/file.php` (not the bare `php -l` - this box's CLI `php` is 8.4, but the live PHP-FPM serving the Apache test deployment is 8.2; `php8.2` is also installed here and is what's actually being verified against. This distinction cost a real bug once already - see `Config.php`'s comment on typed constants - so keep using `php8.2` for this project, not just whatever `php` resolves to by default). Syntax-check a JS module with `node --input-type=module --check < path/to/file.js`, or a plain (non-module) script with `node --check < path/to/file.js` (Node is only used as a local linting tool here, never as a project dependency — no `package.json` in this repo). There is no test suite yet; the data model is self-checked instead — `DataStore::integrityErrors()` walks every cross-reference (symptom→anatomy, procedure→condition, nav parent ids, ...) at load time and returns human-readable errors for any dangling id, so a typo'd reference fails loudly rather than silently rendering a broken link. No headless browser is available in this environment (Playwright's Chromium needs system libraries — `libatk-1.0.so.0` etc. — that aren't installed, and installing them wasn't attempted since it needs root). Nav and wayfinder interaction (hover delay, accordion, Escape/focus handling, flyout clipping, roving tabindex, dialog drill-in) has been verified by careful code reading plus `curl`-based structural checks (ARIA attribute counts, correct locale resolution, JSON payload validity) — not by driving an actual browser. Treat that as unverified until someone opens it in a real browser; see the manual test checklists in the nav/wayfinder architecture sections below. ### Live test deployment on this box The app is also reachable through the real Apache + PHP-FPM 8.2 stack on this server (not just `php -S`), at **https://nyx.erns.eu/mweb/web2/** — set up specifically so a human can test with an actual browser, since no headless browser is available here. This is a symlink (`/var/www/shtml/mweb/web2` → `/home/evrokas/web2/public`) into the docroot of the existing `nyx.erns.eu` vhost (a shared box also hosting Nextcloud, the real `web.erns.eu`/`web3.erns.eu` production site, and unrelated tools) — not a dedicated vhost of its own, and not the production deployment target. No Apache config was touched or reloaded; only two filesystem changes were made: - `chmod o+x /home/evrokas` — the home directory was `750` (blocking traversal by any user outside the `evrokas` group, including `www-data`, the Apache/PHP-FPM worker); this adds execute-only ("can `cd` into a known path, can't list contents") for everyone else, the minimal fix for `www-data` to reach `web2/` at all. Nothing under `/home/evrokas/web2/` itself needed changes (already `755`). - `public/.htaccess` — a standard front-controller rewrite (`RewriteCond %{REQUEST_FILENAME} !-f/!-d` → `index.php`), needed regardless of *where* this is deployed, not specific to this test path. The app is otherwise **subpath-aware by design**, not hacked around for this one test: `public/index.php` computes `$basePath` from `dirname($_SERVER['SCRIPT_NAME'])` (empty string when mounted at a domain root, e.g. via `php -S` or PAGE.md's actual target — a dedicated vhost) and threads it through `Router::dispatch()`, every `DataStore` path-builder (`navPath()`/`procedurePath()`/`conditionPath()`/`wayfinderPayload()`, all taking an optional `$basePath = ''` parameter), and every template's asset/nav links. A root-mounted deployment is completely unaffected (empty-string prefix is a no-op); this isn't a special case bolted on for testing, it's the same mechanism a real subpath deployment would use. Unrelated: there's a pre-existing, unrelated `web2.erns.eu` vhost on this same box (`DocumentRoot /var/www/wordpress`) — a coincidental name collision with this project's local directory name, not connected to it in any way. ### Shared data model — architecture No Composer means no autoloader from `composer dump-autoload`; `src/autoload.php` hand-rolls a `spl_autoload_register` mapping `App\` to `src/`. Everything targets PHP 8.1+ syntax (enums, readonly properties, constructor promotion) — confirmed available via the local `php -v` (8.4.18), but don't reach for 8.4-only syntax (e.g. calling a method directly on `new Foo()` without wrapping parens) since production PHP version isn't confirmed. - `src/Model/` — typed value objects: `Locale`, `LocalizedText` (the GR/EN pair every bilingual field uses), `SpecialtyAxis` (the cranial/spine/pain enum that owns the axis→color-token mapping — nav, wayfinder, and content tags all read color from here, not from CSS or templates re-deciding it), `AnatomySystem`, `SeoFields`, `NavItem`, `AnatomyRegion`, `Symptom`, `Procedure`, `ConditionEntry`, `Clinic`, `PracticeProfile`. - `src/Data/` — one `*Data` class per entity, each a static `all()`/`tree()`/`profile()` returning hydrated model objects with real bilingual content (not lorem ipsum). `NavData` and `AnatomyData` are complete (full fixed nav taxonomy; full spine C1–S1 + 7 cranial regions — textbook nomenclature, not a clinical claim). `SymptomData`, `ProcedureData`, `ConditionData` started as an illustrative sample and were **confirmed by the user (2026-07-04) as the working roster** — 3 symptoms verbatim from PAGE.md, 8 procedures/6 conditions with full bilingual `body` essay content (standard textbook fact only: what it is, general approach, general candidacy/recovery notes — no outcome statistics or claims about Dr. Rokas's personal technique, since none of that was supplied). Expanding this roster further still needs the same sign-off PAGE.md asks for on clinical/specialty content. - `src/Data/DataStore.php` — the single load point. Entities declare only their own outbound ids (e.g. `Procedure::$anatomyIds`); `DataStore` derives every reverse index (anatomy→procedures, symptom→conditions, ...) at construction time so the two sides of a link can't drift out of sync by hand-editing only one file. Also resolves full nested nav paths (`navPath()`, joining ancestor slugs) and runs the integrity check above. - Content-entity ids (symptoms, anatomy, procedures, conditions) are a single ASCII clinical-term slug shared across both locale URL trees (e.g. `lumbar-disc-herniation` under both `/el/...` and `/en/...`) — only nav-section slugs are actually translated per locale. Flagged as a pragmatic default, not requested in PAGE.md. - Locale codes are ISO 639-1 (`el`, not `gr`) to match `hreflang`/`lang`/`og:locale` directly — PAGE.md's own "GR/EN" phrasing is colloquial, not the code to use in markup. - Contact fields (office phone, mobile phone, email) are real — supplied by the user 2026-07-04, on `PracticeProfile` and echoed into `PAGE.md`'s Practice context paragraph. `PracticeProfile::telHref()` turns the human-readable spaced form into a `tel:`-safe digits-only string for links; the display text always uses the as-given spaced form. ### Nav component — architecture - `src/Support/Router.php` + `Response.php` — a minimal `{param}`-pattern router and a plain response value object. `src/Support/View.php` is the "Twig-like" renderer CLAUDE.md's stack line asks for: plain PHP templates (no template language/parser, since there's no Composer to bring in Twig itself) with layout wrapping and partial includes. Templates live in `templates/`, not `src/`, and get `$view` injected automatically so they can call `$view->partial(...)`. `e()` (in `src/Support/helpers.php`) is the one escaping helper; PHP's `` already points at for the target locale (that tag has to exist for SEO anyway, so it's reused rather than duplicated as a second route map). - **Nav markup/behavior** (`templates/partials/nav.php`, `public/assets/css/nav.css`, `public/assets/js/nav.js`): every non-leaf nav item is a real link *and* gets an adjacent disclosure toggle button (split control) — PAGE.md asks explicitly to decide whether top-level items are landing pages or pure toggles; the call made here is "both, uniformly, at every depth" (not just top-level) since every nav node already resolves to a real path via `DataStore::navPath()`. Desktop open/close works via CSS `:hover`/`:focus-within` alone as a no-JS baseline (panels are always in the DOM); `nav.js` layers a JS-held `.is-open` class on top (additive in the same CSS rule) to implement the mouseleave-delay, Escape, and `aria-expanded` sync that CSS can't do alone. Mobile accordion state is JS-only. The two required delegated listeners (click, keydown) sit on the nav root per PAGE.md's explicit "event delegation, not one listener per item" for mobile; desktop's mouseenter/mouseleave are attached directly to the small, bounded set of items that actually have children (7, never all 33) because those events don't bubble and can't be delegated without hand-rolling hover semantics. - Fonts are self-hosted under `public/assets/fonts/` (woff2, Latin+Greek subsets already split by the design-token sign-off) rather than linked from Google Fonts' CDN — deliberate, not just convenient: this is a Greek/EU medical site already adding a cookie-consent banner for GA4, and a third-party font CDN leaks visitor IPs the same way a tracking pixel would. - No headless browser was available to drive real hover/focus/tap interaction (see note above) — this is the biggest gap in "test both before moving on." Before trusting this component, check in an actual browser: desktop hover-open with diagonal mouse movement into the panel, keyboard Tab through the whole nav with visible focus throughout, Escape closing one level at a time, the two nested flyouts (Πληροφορίες για ασθενείς, Συνεργαζόμενες κλινικές) actually flipping side when opened near the right edge of a narrow desktop window, mobile hamburger open/close, mobile recursive accordion (opening a sibling collapses the previous one, at every level), and the GR/EN toggle both visually and via `view-source` after toggling (confirm the URL bar updated too). ### Anatomical wayfinder — architecture - `src/Support/WayfinderLayout.php` — pure geometry, no rendering: turns the ordered `AnatomyRegion` list into SVG hotspot shapes. Spine is grouped by id prefix (`c`/`t`/`l`/`s`) and each group gets an independent half-sine curve that starts and ends at the center baseline (a schematic approximation of cervical/thoracic/lumbar curvature, continuous at every boundary by construction) - genuinely computed from the data, not a hand-typed coordinate table. Cranial's 7 lobes/regions have no linear-stack analog, so their relative position and per-lobe bump layout *is* a hand-tuned lookup table keyed by region id - the one deliberately-hardcoded set of parameters, flagged in that file's docblock. - **Cranial hotspot shapes redesigned 2026-07-08** from plain ellipses/rect (originally deliberate - "schematic, not a medical illustration" - but read as too generic once seen live) to organic gyrus-bump outlines, guided by a reference image the user supplied. First pass used a pure formula (`WayfinderLayout::gaussianBumpPath()`: a base radius plus a handful of named Gaussian bumps at chosen angles, sampled around a circle and splined) - the user judged that pass "not successful" and asked for a more precise trace, so the five most distinctive lobes (frontal, parietal, temporal, cerebellum, and occipital by reuse - see below) were replaced 2026-07-09 with **literal traced outlines**, not a formula: the reference image was masked by color per lobe (numpy/scipy, no CV library available - color-distance threshold, `binary_fill_holes`, largest-connected-component), each region's boundary extracted via matplotlib's marching-squares contouring, resampled to 40 evenly-spaced points, fit into that lobe's target box, and smoothed through a closed Catmull-Rom spline into a static `'d'` string baked directly into `cranialGeometry()` - genuinely the reference's own pixel outlines, not an approximation of them. `occipital-lobe` has no distinct region in the reference (fused into the same blue mass as temporal/brainstem there), so it reuses parietal's traced silhouette, mirrored and rescaled, rather than being invented from nothing. `brainstem` and `trigeminal-skull-base` still use the original `gaussianBumpPath()` formula, computed live at request time - the reference's equivalent area is a decorative spiral flourish, not a real brainstem shape, so there was nothing to trace there. Verification for this one had to go further than usual: the generated path data was rendered to a real PNG locally (ImageMagick) at every iteration and visually compared against the source image before being committed to PHP, then the *actual live-rendered* SVG output was pulled from the running dev server and rendered again to confirm the PHP port matched the verified prototype exactly - code reading alone can't catch "does this look like a brain," only a rendered image can. Colors are still unchanged from the first pass (axis-based - navy for Cranial, oxblood for the one Pain-axis trigeminal hotspot) - see the first-pass note below for why the reference's per-lobe rainbow coloring was deliberately not copied. `templates/partials/wayfinder.php`'s `$renderShape` closure gained a `'lobe'` branch (alongside the existing `ellipse`/`rect`/`trapezoid` ones) that emits the pre-built path string as-is - `wayfinder.js`, the embedded JSON payload, and hover/focus/active behavior are all unaffected, since hotspot geometry was already opaque to the JS (it only ever reads the `` wrapper's classes/data attributes, never the child shape). - **A background brain silhouette added 2026-07-16**, because the individually-traced lobes above - each one correct on its own - still read as scattered separate pieces once actually seen together, with no overall "this is a brain" cue (visible gaps, cerebellum floating disconnected from the rest). `WayfinderLayout::cranialOutlinePath()` is a new static method returning one more traced path, built the same way as the five lobe shapes but from the *union* of all four color-masked regions instead of one at a time - the four regions don't touch at the pixel level in the source art (each lobe is a separately-outlined shape), so a generous dilate/fill-holes/erode pass bridges the small gaps between them before the union gets contoured - still literally the reference's own overall outline, not hand-drawn. Rendered in `wayfinder.php` as one `