# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## What this is
`bes.is` — a Blazor Server app (single ASP.NET Core project, no test project) hosting a
collection of small, mostly self-contained JS/HTML experiments/tools (RPN calculator,
QR code scan/generate, a Netflix→Letterboxd converter, a JSON query playground, BRP
lookup, etc.), each on its own route.
## Commands
Run from the repo root or `Blog/`:
```
dotnet build # build
dotnet run --project Blog # run locally (http://localhost:5296)
dotnet watch --project Blog # run with hot reload
```
There is no test project in the solution — don't invent `dotnet test` commands or test
files unless asked to add a test project first.
Publishing is done via the Rider run configuration "Publish Blog to custom server" (self-contained
`linux-x64`, Release, ReadyToRun) — not part of normal dev workflow.
## Architecture
**One project, one layout, many independent page-features.** `Blog/Components/Pages/*.razor`
are the routes (`@page "/Xyz"`), each linked from `SiteFooter.razor`. Most pages are a
`.razor` file paired with a `.razor.js` file of the same name — this is the pattern to
follow for any new interactive page.
### The `.razor` + `.razor.js` pairing
There is **no Blazor client runtime**. Every page is statically server-rendered and its JS is
loaded as a plain ES module:
```razor
```
`.razor.js` files colocated with a component are static web assets, so `@Assets[...]` resolves
them to a fingerprinted URL and `` in `App.razor` maps the bare `/common.module.js`
style imports onto their fingerprinted files too. Never hand-write the plain path — go through
`@Assets` or the module ships uncached.
The module body *is* the page's setup code: it runs once, at top level, after the DOM is parsed
(`type="module"` is deferred). There are no `onLoad`/`onUpdate`/`onDispose` hooks, because
navigation is a real page load — the browser tears down listeners, timers and module state for
you. Page logic is vanilla JS DOM manipulation, not Blazor data binding: grab elements with
`getById` at top level and wire up listeners directly.
If you ever reintroduce interactivity or enhanced navigation, this stops being true — module
state would then outlive the DOM it points at, and every page script would need teardown again.
`Log.razor`, `Panel.razor`, and the `StackOp*.razor` components live in `Components/_Shared/`
and are reused across pages (e.g. `Log` renders a debug/error log panel that JS writes into via
`writeDebug`/`writeError`; `Panel` is a bordered fieldset-with-legend used for docs/credits/
grouped controls).
### `wwwroot/common.module.js`
Shared JS helpers imported by page scripts:
- `h(tag, attrs?, children?)` / `t(text)` — a small hyperscript-style DOM builder (no
framework, just `document.createElement`/`appendChild`). Prefer this over manual DOM
building or template strings in new page scripts.
- `getById(id)` — like `document.getElementById` but throws instead of returning null.
- `writeError` / `writeInfo` / `writeDebug` / `resetLog` — write into the `#log` element
that `Log.razor` renders.
- `debounce(fn, wait)`.
Other `wwwroot/*.js` files (`dactal.js`, `qrcode.js`, `lz-string.module.js`, `jsonql-js/`)
are third-party or semi-vendored libraries used by specific pages (e.g. `Query.razor.js`
uses both `dactal.js` and `jsonql-js` to run two query languages against the same mock
BRP dataset in `wwwroot/brp.json`).
### rvrb feature (stats read off another BEAM node)
`Rvrb.razor`/`.razor.cs`/`.razor.js` (route `/rvrb`) shows the status and stats of the
rvrb Elixir bot (`~/Developer/elixir/rvrb`), which runs on the same server. `Services/RvrbService.cs`
gets them by joining the bot's Erlang cluster: [BeamSharp](https://github.com/Besselking/BeamSharp)
(referenced as a project from the sibling checkout, it is not on NuGet yet) makes this site a
hidden Erlang node and calls `Rvrb.Stats.snapshot/0` on the bot the way any BEAM node would —
no HTTP endpoint on the Elixir side.
The node is started on the *first request* rather than at boot, and a failure is a value
(`RvrbStatus.Unreachable`) rather than an exception: the site must not fail to start, or a page
fail to render, because EPMD is down or the bot was deployed without distribution. `Models/RvrbSnapshot.cs`
holds the shapes and `Services/RvrbSnapshotReader.cs` decodes the Erlang term into them by hand —
the term is an Elixir map written by Elixir, not a serialized C# type.
Configuration lives under `Rvrb` (`RvrbOptions`): `Node`, `LocalNode`, `CallTimeout`, `CacheFor`
in `appsettings.json`, and `Cookie` — the shared Erlang cookie — from user secrets in development
(`dotnet user-secrets set "Rvrb:Cookie" ...`) or `Rvrb__Cookie` in the environment. The bot's own
side of this (enabling distribution on its release) is documented in the rvrb repo's README.
### BRP feature (an external API behind a page)
`BRP.razor`/`.razor.cs` and `BrpTestData.razor` are backed by `Services/BrpService.cs`,
which calls an external "Haal Centraal BRP" lookup API (base address configured in
`Program.cs` as `https://brp.bes.is/`) and caches responses via `HybridCache`
(`Microsoft.Extensions.Caching.Hybrid`). `Models/BRPEntry.cs` and
`Models/RaadpleegMetBurgerservicenummer.cs` model the request/response shapes. Test/mock
data lives in `Resources/test-data.json` and `wwwroot/brp.json`.
### Warframe drops feature (`/Warframe`)
`Warframe.razor`/`.razor.cs`/`.razor.js` searches Digital Extremes' published drop tables: given a
part it shows where it drops sorted by chance, and for prime parts the relics holding it plus the
best places to farm those relics.
`Services/DropTableParser.cs` turns into
`Models/WarframeDrops.cs`. The source is 4 MB of machine-generated HTML: twenty `` sections
of one flat table each, no classes or ids on the rows. It walks rows with regexes instead of an HTML
parser, using three row grammars (two-column reward tables, three-column bounty tables, three-column
"by source" tables) that cover all twenty sections. Rows matching no grammar are skipped rather than
thrown over. Current output: 3,481 items, about 200 ms to parse.
`Services/WarframeDropService.cs` holds one parsed copy in a field behind a `SemaphoreSlim`, not in
`HybridCache` like the rest of the site, because HybridCache serializes what it stores. This depends
on the service being registered as a **singleton**: a typed `AddHttpClient()`
registration makes it transient and re-parses 4 MB per request, so it takes `IHttpClientFactory` and
a named client instead. A failed refresh keeps the copy it already had.
Configuration lives under `Warframe` (`WarframeOptions`): `DropTablesUrl`, `CacheFor` (12 h),
`Timeout`.
The page is server-rendered and driven by the query string (`?q=` search, `?item=` selection), so
results are linkable and work without JS. `Warframe.razor.js` only fills the search box's
`