| 1 |
# CLAUDE.md |
| 2 |
|
| 3 |
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 |
|
| 5 |
## What this is |
| 6 |
|
| 7 |
`bes.is` — a Blazor Server app (single ASP.NET Core project, no test project) hosting a |
| 8 |
collection of small, mostly self-contained JS/HTML experiments/tools (RPN calculator, |
| 9 |
QR code scan/generate, a Netflix→Letterboxd converter, a JSON query playground, BRP |
| 10 |
lookup, etc.), each on its own route. |
| 11 |
|
| 12 |
## Commands |
| 13 |
|
| 14 |
Run from the repo root or `Blog/`: |
| 15 |
|
| 16 |
``` |
| 17 |
dotnet build # build |
| 18 |
dotnet run --project Blog # run locally (http://localhost:5296) |
| 19 |
dotnet watch --project Blog # run with hot reload |
| 20 |
``` |
| 21 |
|
| 22 |
There is no test project in the solution — don't invent `dotnet test` commands or test |
| 23 |
files unless asked to add a test project first. |
| 24 |
|
| 25 |
Publishing is done via the Rider run configuration "Publish Blog to custom server" (self-contained |
| 26 |
`linux-x64`, Release, ReadyToRun) — not part of normal dev workflow. It has two before-run tasks, |
| 27 |
both Rider External Tools (which live in Rider's own config, not in this repo): "update droptables" |
| 28 |
runs `scripts/update-droptables.sh`, then "restore linux" restores for the target runtime. |
| 29 |
|
| 30 |
## Architecture |
| 31 |
|
| 32 |
**One project, one layout, many independent page-features.** `Blog/Components/Pages/*.razor` |
| 33 |
are the routes (`@page "/Xyz"`), each linked from `SiteFooter.razor`. Most pages are a |
| 34 |
`.razor` file paired with a `.razor.js` file of the same name — this is the pattern to |
| 35 |
follow for any new interactive page. |
| 36 |
|
| 37 |
### The `.razor` + `.razor.js` pairing |
| 38 |
|
| 39 |
There is **no Blazor client runtime**. Every page is statically server-rendered and its JS is |
| 40 |
loaded as a plain ES module: |
| 41 |
|
| 42 |
```razor |
| 43 |
<script type="module" src="@Assets["Components/Pages/Foo.razor.js"]"></script> |
| 44 |
``` |
| 45 |
|
| 46 |
`.razor.js` files colocated with a component are static web assets, so `@Assets[...]` resolves |
| 47 |
them to a fingerprinted URL and `<ImportMap/>` in `App.razor` maps the bare `/common.module.js` |
| 48 |
style imports onto their fingerprinted files too. Never hand-write the plain path — go through |
| 49 |
`@Assets` or the module ships uncached. |
| 50 |
|
| 51 |
The module body *is* the page's setup code: it runs once, at top level, after the DOM is parsed |
| 52 |
(`type="module"` is deferred). There are no `onLoad`/`onUpdate`/`onDispose` hooks, because |
| 53 |
navigation is a real page load — the browser tears down listeners, timers and module state for |
| 54 |
you. Page logic is vanilla JS DOM manipulation, not Blazor data binding: grab elements with |
| 55 |
`getById` at top level and wire up listeners directly. |
| 56 |
|
| 57 |
If you ever reintroduce interactivity or enhanced navigation, this stops being true — module |
| 58 |
state would then outlive the DOM it points at, and every page script would need teardown again. |
| 59 |
|
| 60 |
`Log.razor`, `Panel.razor`, and the `StackOp*.razor` components live in `Components/_Shared/` |
| 61 |
and are reused across pages (e.g. `Log` renders a debug/error log panel that JS writes into via |
| 62 |
`writeDebug`/`writeError`; `Panel` is a bordered fieldset-with-legend used for docs/credits/ |
| 63 |
grouped controls). |
| 64 |
|
| 65 |
### `wwwroot/common.module.js` |
| 66 |
|
| 67 |
Shared JS helpers imported by page scripts: |
| 68 |
- `h(tag, attrs?, children?)` / `t(text)` — a small hyperscript-style DOM builder (no |
| 69 |
framework, just `document.createElement`/`appendChild`). Prefer this over manual DOM |
| 70 |
building or template strings in new page scripts. |
| 71 |
- `getById(id)` — like `document.getElementById` but throws instead of returning null. |
| 72 |
- `writeError` / `writeInfo` / `writeDebug` / `resetLog` — write into the `#log` element |
| 73 |
that `Log.razor` renders. |
| 74 |
- `debounce(fn, wait)`. |
| 75 |
|
| 76 |
Other `wwwroot/*.js` files (`dactal.js`, `qrcode.js`, `lz-string.module.js`, `jsonql-js/`) |
| 77 |
are third-party or semi-vendored libraries used by specific pages (e.g. `Query.razor.js` |
| 78 |
uses both `dactal.js` and `jsonql-js` to run two query languages against the same mock |
| 79 |
BRP dataset in `wwwroot/brp.json`). |
| 80 |
|
| 81 |
### rvrb feature (stats read off another BEAM node) |
| 82 |
|
| 83 |
`Rvrb.razor`/`.razor.cs`/`.razor.js` (route `/rvrb`) shows the status and stats of the |
| 84 |
rvrb Elixir bot (`~/Developer/elixir/rvrb`), which runs on the same server. `Services/RvrbService.cs` |
| 85 |
gets them by joining the bot's Erlang cluster: [BeamSharp](https://github.com/Besselking/BeamSharp) |
| 86 |
(referenced as a project from the sibling checkout, it is not on NuGet yet) makes this site a |
| 87 |
hidden Erlang node and calls `Rvrb.Stats.snapshot/0` on the bot the way any BEAM node would — |
| 88 |
no HTTP endpoint on the Elixir side. |
| 89 |
|
| 90 |
The node is started on the *first request* rather than at boot, and a failure is a value |
| 91 |
(`RvrbStatus.Unreachable`) rather than an exception: the site must not fail to start, or a page |
| 92 |
fail to render, because EPMD is down or the bot was deployed without distribution. `Models/RvrbSnapshot.cs` |
| 93 |
holds the shapes and `Services/RvrbSnapshotReader.cs` decodes the Erlang term into them by hand — |
| 94 |
the term is an Elixir map written by Elixir, not a serialized C# type. |
| 95 |
|
| 96 |
Configuration lives under `Rvrb` (`RvrbOptions`): `Node`, `LocalNode`, `CallTimeout`, `CacheFor` |
| 97 |
in `appsettings.json`, and `Cookie` — the shared Erlang cookie — from user secrets in development |
| 98 |
(`dotnet user-secrets set "Rvrb:Cookie" ...`) or `Rvrb__Cookie` in the environment. The bot's own |
| 99 |
side of this (enabling distribution on its release) is documented in the rvrb repo's README. |
| 100 |
|
| 101 |
### BRP feature (an external API behind a page) |
| 102 |
|
| 103 |
`BRP.razor`/`.razor.cs` and `BrpTestData.razor` are backed by `Services/BrpService.cs`, |
| 104 |
which calls an external "Haal Centraal BRP" lookup API (base address configured in |
| 105 |
`Program.cs` as `https://brp.bes.is/`) and caches responses via `HybridCache` |
| 106 |
(`Microsoft.Extensions.Caching.Hybrid`). `Models/BRPEntry.cs` and |
| 107 |
`Models/RaadpleegMetBurgerservicenummer.cs` model the request/response shapes. Test/mock |
| 108 |
data lives in `Resources/test-data.json` and `wwwroot/brp.json`. |
| 109 |
|
| 110 |
### Warframe drops feature (`/Warframe`) |
| 111 |
|
| 112 |
`Warframe.razor`/`.razor.cs`/`.razor.js` searches Digital Extremes' published drop tables: given a |
| 113 |
part it shows where it drops sorted by chance, and for prime parts the relics holding it plus the |
| 114 |
best places to farm those relics. |
| 115 |
|
| 116 |
**The drop table page is vendored, not fetched.** warframe.com blocks requests from the server, so |
| 117 |
`Blog/Resources/droptables.html` is committed and read from disk; nothing about this page talks to |
| 118 |
the network at runtime. `scripts/update-droptables.sh` refreshes that file, and the Rider publish |
| 119 |
configuration runs it as a before-run task so every deploy ships current data — commit the result. |
| 120 |
The script refuses a download that isn't the drop table page (an error page, a truncated body), and |
| 121 |
treats a failed refresh as a warning so an outage at DE can't block an unrelated deploy. |
| 122 |
|
| 123 |
Two things that are easy to get wrong here, both of which break only the *deployed* site: |
| 124 |
|
| 125 |
- The Web SDK's default content glob covers `wwwroot/**`, `**/*.config` and `**/*.json` only, which |
| 126 |
is why `Resources/test-data.json` publishes for free and the `.html` does not. `Blog.csproj` names |
| 127 |
it explicitly with `CopyToPublishDirectory`. |
| 128 |
- The path resolves against `AppContext.BaseDirectory`, not `ContentRootPath` or the working |
| 129 |
directory. Those two follow wherever the process was started, so a unit file without a |
| 130 |
`WorkingDirectory` sends it looking in `/`. |
| 131 |
|
| 132 |
`Services/DropTableParser.cs` turns that page into `Models/WarframeDrops.cs`. The source is 4 MB of |
| 133 |
machine-generated HTML: twenty `<h3 id>` sections of one flat table each, no classes or ids on the |
| 134 |
rows. It walks rows with regexes instead of an HTML parser, using three row grammars (two-column |
| 135 |
reward tables, three-column bounty tables, three-column "by source" tables) that cover all twenty |
| 136 |
sections. Rows matching no grammar are skipped rather than thrown over. Current output: 3,481 items, |
| 137 |
about 200 ms to parse. |
| 138 |
|
| 139 |
`Services/WarframeDropService.cs` holds one parsed copy in a field behind a `SemaphoreSlim`, not in |
| 140 |
`HybridCache` like the rest of the site, because HybridCache serializes what it stores. This depends |
| 141 |
on the service being registered as a **singleton**, or it would re-parse 4 MB per request. The copy |
| 142 |
is keyed on the file's last write time, so `dotnet watch` picks up a refresh without a restart. |
| 143 |
|
| 144 |
Configuration lives under `Warframe` (`WarframeOptions`): `FilePath`. |
| 145 |
|
| 146 |
The page is server-rendered and driven by the query string (`?q=` search, `?item=` selection), so |
| 147 |
results are linkable and work without JS. `Warframe.razor.js` only fills the search box's |
| 148 |
`<datalist>` from `/api/warframe/names` (mapped in `Program.cs`). It does *not* import |
| 149 |
`/common.module.js`: that module binds to a `#log` element this page doesn't have. |
| 150 |
|
| 151 |
### Styling |
| 152 |
|
| 153 |
`wwwroot/app.css` is one hand-maintained stylesheet (no CSS framework, no build step), |
| 154 |
organized into numbered sections (Tokens → Reset/base → Typography → Layout → Controls → |
| 155 |
Components → Media) with CSS custom properties as the single source of design tokens |
| 156 |
(colors, spacing scale, fonts). It uses `light-dark()` and `color-scheme` for automatic |
| 157 |
dark mode — don't hardcode light/dark colors, extend the token set in section 1 instead. |
| 158 |
There are no scoped `.razor.css` stylesheets, so `App.razor` links `app.css` only; adding one |
| 159 |
means adding the `Blog.styles.css` bundle link back. |