This is a large and active repository that appears maintained and developed with the assistance of claude.ai and is likely functional and likely defends some common concerns in its field of design. I found the below file in the repository which seems potentially elucidating: # CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## What this repo is demist is a **design-phase** project. The normative artifact is the protocol specification at [docs/specification.md](docs/specification.md) (~165 KB, versioned). The PWA client under [app/htdocs/](app/htdocs/) is a UI prototype. A Go consensus node lives under [smith/](smith/) — it implements the **current specification end to end** (WoT, the unified voting publication with its seven voting types — referendum, election setup and candidacy, governance, koinon amendments, fraudulent-citizen and sybil-area challenges — over Triptych anonymous ballots, all rewards, VRF lottery consensus, disk-backed persistence); see the "Implemented and remaining" section of [smith/README.md](smith/README.md) for the genuinely open node-side items (peer discovery, scale-time optimizations). When spec and `smith/` disagree, the spec wins. A minimal **PHP/MySQL app server** lives under [app/htdocs/server/](app/htdocs/server/) (`identity.php`) — it stores each user's AES-encrypted identity blob keyed by their Ed25519 public key, with signature-authenticated writes. See [app/INSTALL.md](app/INSTALL.md) for setup. This is a sync/backup service, not the consensus node. When the user asks about behavior, **treat the spec as the source of truth**, not the client code. The client is intentionally ahead of / divergent from the spec in places because it's exploring the UI. A reference **document signature service** lives under [agora/](agora/README.md) (PHP/MariaDB): citizens sign in by QR with their citizen key pair, upload documents, and collect signatures — including the §16.5.1 support signatures a voting publication must carry. It implements three off-chain companion specifications and holds no secrets; `agora/test/voting_id_test.php` pins its §16.4 id derivation against the smith's, which is the one place the two implementations must agree byte for byte. The project's **main web site** (demist.net) lives under [www/](www/README.md): one static page whose every visible string lives in `www/htdocs/i18n/<code>.json` (English included, like the app), no build step. It presents the project and sends visitors to the app; it is marketing, never a source of truth about the protocol. The **production network** is defined under [production/](production/README.md): the release consensus parameters (the specification §19 values, unmodified, `bootstrap-citizen-count` included), the remote self-sovereign genesis-ceremony procedure targeting twenty founders (three of them smiths; the target is an aim, the §10 floor of five/three the requirement), and the node-operation scripts; its `genesis.json` and `smiths.txt` are committed once the ceremony completes. All **testing** lives under [tests/](tests/README.md): the three test-network definitions (`automated/`, `manual/`, `alpha/` — one `parameters.json` each, the single source of truth for a network's consensus parameters), the shared 128-identity pool (`identities/`), the network launcher and WoT keepalive (`lib/`), the smith functional scenarios (`api/`, run by CI), and the Playwright browser scenario (`automated/`). The `manual/` network is the whole service constellation run locally on the 11xx ports (app 1110 with `/server` same-origin, www 1109, agora 1108, koinon 1107, verify 1106, market 1105, ai 1104, indexer 1121) with the alpha consensus parameters; the app recognizes it by its own origin, `localhost:1110`. `smith/run-test-network.sh` is a thin wrapper around `tests/lib/network.sh`. A network with a shortened certification validity halts when the genesis certifications expire together unless `tests/lib/keepalive.sh` runs beside it. A `snapshot` step in the browser scenario saves the whole stack — chain and the app, indexer and agora databases — under `tests/automated/snapshot/<name>/`, and `tests/automated/restore.sh <name>` starts a run from one instead of from the forge. Because the protocol's durations are in the saved chain, the restored stack runs with `DEMIST_CLOCK_OFFSET_MICROSECONDS` set to hold every part of it — smiths, app server, agora, runner, browsers — at the instant the snapshot was taken. Unset, which is every ordinary run and every deployment, nothing reads it. Companion docs in [docs/](docs/): `motivation.md`, `strategy.md` (deployment), `socioeconomic.md`, `extensions.md` (deferred features), and the three off-chain web APIs — `citizen-sign-in.md`, `document-signature.md`, `voting-support.md`. ## Branches and deployment Development happens on `main`; there is no separate release branch. A forgejo webhook automatically deploys `main` to production: the client at https://app.demist.net and the app server at https://app.demist.net/server. Because the client is a PWA, pushed changes only reach already-installed clients once the service worker cache version is bumped (see "Running the client locally" and "Service worker caveat"). ## No build, no package manager There is no `package.json`, no bundler, no test runner, no linter config beyond a one-line `.htmlhintrc` in `app/htdocs/templates/` (it turns off `doctype-first`, since templates are fragments rather than documents). The client is plain ES modules served as static files. Browser-side dependencies (Leaflet, `@noble/curves`, `@noble/hashes`, `@scure/bip39`) are loaded at runtime from `esm.sh` / `unpkg` via dynamic `import()` — do not "install" them or add a bundler unless the user asks. The two client tests are [app/test/election_outcome_test.mjs](app/test/election_outcome_test.mjs) and [app/test/anonymous_vote_decoding_test.mjs](app/test/anonymous_vote_decoding_test.mjs), each run as `node app/test/<name>.mjs` — no runner and no dependencies, like the agora's and the indexer's plain PHP test scripts. Both cover a piece of protocol arithmetic the client performs alone: the §16.6.2 winner rules, which no chain state depends on so neither the smith nor the indexer computes them and no cross-implementation vectors exist; and the §9 / §8.1 / §16.9 block walk the Vote page's ballot status does to find the citizen's own ballot by its §16.8 key image, where a misread offset silently finds nothing and "nothing" is exactly what an uncounted ballot looks like. UI behavior stays untested; this is arithmetic a citizen is asked to trust. ## Running the client locally Open the workspace in VSCode and start the Live Server extension — it's pre-configured by [.vscode/settings.json](.vscode/settings.json) and [app/.vscode/settings.json](app/.vscode/settings.json) to serve `app/htdocs` on `localhost:5500`. Service workers require an HTTP origin, so opening `index.html` via `file://` won't work. The `BaseComponent` (see below) detects `localhost`/`127.0.0.1` and appends `?v=<timestamp>` to template and stylesheet fetches to bypass cache — that's why edits show up immediately on the dev server but you must bump the service worker cache version for production. ## Client architecture: convention-driven Web Components All UI is built on [app/htdocs/components/base.js](app/htdocs/components/base.js). The convention is load-bearing: - A component class sets `this.componentName = 'foo-bar'` (the custom element tag name). - `BaseComponent.connectedCallback` then auto-fetches `./templates/foo-bar.html` and `./styles/foo-bar.css` and renders them into shadow DOM. - Override `setupEventListeners()` (called after render) instead of `connectedCallback` for wiring. - **Never define a method named `render()` in a subclass**: `render()` is the base hook that writes the template into the shadow root, and overriding it leaves the component permanently empty while its listeners run normally. Name your own DOM-updating methods `display…` (see `network-banner.js`, `vote-panel.js`). - Use `this.$(sel)` / `this.$$(sel)` to query inside the shadow root. **Implication when adding a component**: create three files with matching basenames (`components/x.js`, `templates/x.html`, `styles/x.css`) and import the JS from a parent component. Forgetting the template causes a visible "Template not found" placeholder. The shell is `<demist-app>` → `<tab-bar>` (top-level sections) → `<tab-panel>` (sub-tabs) → `<tab-panel-item>`. Tabs are declared in [templates/demist-app.html](app/htdocs/templates/demist-app.html) using `<tab-bar-item label="..." icon="...">` — `icon` resolves to `./images/<name>.svg`. The icon set is served from `images/`, **not** `icons/`, and must stay that way: Apache ships a stock `Alias /icons/ "/usr/share/apache2/icons/"` for its directory-listing decorations, which shadows `/icons/` for any site served from a document root. Because the client is deployed at the root of `app.demist.net`, naming the directory `icons/` makes every icon 404 in production while working fine under Live Server. Every page has its own URL: each `<tab-panel-item>` carries a `page="<name>"` attribute, and [navigation.js](app/htdocs/navigation.js) maps it to `?page=<name>` — recording tab changes and page-internal navigation into the browser history, and restoring them on load and on back/forward. A page component may add page parameters to that URL by implementing `urlParameters()` (its current state) and `applyUrlParameters(parameters)` (restore it) — see `koinon-browser.js` (`area`, `citizen`) and `results-panel.js`, `vote-panel.js`, `explore-panel.js` (`area`, `voting`, `election`). Light DOM children of `<tab-bar>` / `<tab-panel>` are NOT slotted — they're toggled in/out via a `.active` class watched by a `MutationObserver` in each item's shadow DOM (see `tab-bar-item.js`, `tab-panel-item.js`). Don't try to fix this with `<slot>`; it's deliberate. ## Coding conventions - **American English only — no British spellings.** Everything written in this repo — code, comments, identifiers, JSON keys, documentation, UI strings, commit messages — uses American English: `behavior` not `behaviour`, `color` not `colour`, `canceled` not `cancelled`, `serialize` not `serialise`, `analyze` not `analyse`, `neighbor` not `neighbour`, `meter` not `metre`, `license` not `licence`. The only exceptions are externally defined names that must match byte-for-byte (the HTML `aria-labelledby` attribute, the OSM Nominatim `licence` response field in stored API data) and non-English text (the French translations in `i18n/fr.json`, the French BIP-39 recovery phrases in the test identity pool). - **No abbreviations in names — everywhere, no exceptions.** Spell identifiers out in full: `button` not `btn`, `registration-form` not `rf`, `number` not `num`, `camera-button` not `cam-btn`, `simulation` not `sim`, `engine` not `eng`, `block` not `blk`, `latency` not `lat`, `callback` not `fn`. This is a hard rule that applies to **every language and every artifact in this repo** — not just the client — including Python, Go, shell, JSON keys, CSS classes, element `id`s, variables, functions, methods, types, **directory names, and file names**. Also keep word order natural English (`camera-button`, not `button-camera`). The only admissible short names are single letters that reproduce a symbol used in [docs/specification.md](docs/specification.md) itself (e.g. `N` for a count, `beta` for the VRF output), and even then only in code that implements or validates that exact formula; when you use one, say so in a comment. If you catch yourself shortening a word to save keystrokes, don't. - **Clean design built on Web Components.** Keep the UI as small, self-contained custom elements following the `BaseComponent` three-file convention (`components/x.js` + `templates/x.html` + `styles/x.css`). Prefer semantic HTML (`<button>`, `<dialog>`, `<section>`, `<header>`, `<footer>`) over generic `<div>`s with utility classes, and put shared element-level rules in one place (e.g. `styles/buttons.css`) rather than duplicating them per component. - **Design principles, in tension — resolve them with judgment, not dogma.** - **KISS** (Keep It Simple) — make it as simple as the problem allows; the simplest thing that fully works beats a clever one. - **DRY** (Don't Repeat Yourself) — every piece of logic or knowledge has one source of truth; don't copy-paste behavior or restate a fact in two places. - **YAGNI** (You Aren't Gonna Need It) — build for the present requirement only. Don't add abstraction, configurability, parameters, or generality for hypothetical futures; add them when a real, present need arrives. - **AHA** (Avoid Hasty Abstractions) — prefer a little duplication over the wrong abstraction. Wait until the shape of the repetition is obvious before extracting it, and don't force loosely-related call sites to share code just because they look similar today. - When these pull against each other, prefer the change that a future reader will find easiest to understand and safest to modify. ## Identity / registration form [components/registration-form.js](app/htdocs/components/registration-form.js) is the only non-trivial component and the place where the spec actually touches code. It: - Resolves the user's "deme" by reverse-geocoding the picked map point through OSM Nominatim and walking `ADMIN_KEYS` (smallest → largest administrative boundary). The `deme` ID stored is the OSM relation ID. This is the client-side mirror of the spec's deme-anchored identity (§5). - Generates a BIP-39 12-word mnemonic (128-bit), derives an Ed25519 identity key via SLIP-10 path `m/44'/999'/0'/0'/0'` (coin type `999` = DRACHMA), and a separate Ristretto voting key at `m/44'/999'/0'/1'/0'`. - **Storage model** (no plaintext identity in `localStorage`): - The identity record (public data) is AES-256-GCM encrypted with a key derived from the seed via HKDF-SHA256 (`IDENTITY_AES_INFO`), then uploaded to the app server keyed by the public key. Writes are signed with the Ed25519 key and verified server-side. - The seed is cached in the `localStorage` `identity_profiles` map (`PROFILES_KEY`, keyed by identity public key — several identities coexist on one device) — by default unprotected, for a prompt-free unlock; when the user enables PIN/biometric authentication in Settings/Account (per-profile `biometric-authentication` setting, `'true'` to opt in), it is instead encrypted with a key from a **WebAuthn passkey's PRF extension** (`PRF_SALT`) for biometric unlock (Windows Hello / Touch ID). Each tab remembers its identity in the sessionStorage `active_profile` key, so different tabs can run different identities; sign-out removes only the active profile. A session with no such pin — a fresh tab, and every launch of the installed app, which ends the session when quit — lands on the registration form, which offers an **Unlock** button per stored profile (running that profile's passkey prompt) beside the recovery-phrase sign-in; the one exception is a device holding a **single unprotected profile**, which the tab opens automatically (its Unlock button would open on the press with no question asked anyway). Per-identity preferences (theme, language, indexer node) live in each profile's `settings` object (`profile-store.js`), falling back to device-level localStorage for the pre-sign-in screens. The indexer choice additionally rides in the encrypted server record (`record.settings`), so it follows the identity to any machine; the local profile copy is the synchronous cache, refreshed at unlock. The smith is **not** chosen or stored — it is discovered from the selected indexer, whose `status.php` advertises the one smith it mirrors (`selectedSmithUrl()` in `indexer-client.js`, cached under the `smith-node` key); a legacy stored `smith_node` is ignored. - Signing in on a new device: enter the 12-word phrase → derive public key + AES key → fetch the encrypted record from the server → decrypt. If you touch this file, keep `PROFILES_KEY`, `PRF_SALT`, `IDENTITY_AES_INFO`, and the SLIP-10 / HKDF derivation parameters stable — changing any of them silently locks existing users out of their stored identity (both locally and on the server). ## Service worker caveat [service-worker.js](app/htdocs/service-worker.js) precaches a `STATIC_FILES` list. `cache.addAll()` rejects atomically if any URL 404s, which silently breaks offline support — so the list must contain only files that exist (icons are excluded; they're served on first use by the cache-first strategy). Bump `CACHE_NAME` / `STATIC_CACHE_NAME` / `DYNAMIC_CACHE_NAME` versions whenever cached assets change so clients re-fetch. The worker only does caching: it has no push, notification, or background-sync handlers — if you add push notifications, write those handlers from scratch (and give them icon files that actually exist). ## Editing the specification The spec is the actual deliverable. Hard constraints from the project memory: - **Determinism is non-negotiable**: integer arithmetic only, exact fractions, OSM-dump anchoring. Reject changes that introduce floating point in consensus-relevant calculations. - **Personal data on-chain** (names, photos) is a deliberate design choice with known regulatory tension — not a bug to "fix" unilaterally. - Cross-section references use `§N.M` style. When renumbering or reorganizing, search for stale `§` references. - Tautologies and redundancies should be avoided (DRY). The design should be as simple as possible (KISS).