Architecture

Stimpunks.World is a directory of static files that Netlify serves as they are, deployed by a push to main. The CB’s functions and one storage area are the only parts that run on a server. This page is the code and the hosting; How this site is made is the why. Last updated 2026-10-04.

At a glance

Hosting and deploy

Netlify serves the repository root as it is, and a push to main is a deploy: live in a minute or two, with no staging step and no review. There is no build command, no bundler and no fingerprinting. The HTML in the repository is what you are reading.

• Domain. stimpunks.world since 2026-09-23. stimpunks.love (2026-09-19 to 2026-09-23) and stimpunks-love.netlify.app stay registered and send you here, path for path, with a 301.
• Functions. Netlify bundles netlify/functions/*.mjs on deploy and installs the one dependency in package.json, @netlify/blobs. Nothing else is installed or built.
• Storage. One Netlify Blobs store named cb, opened with strong consistency. It is the only thing the site keeps on a server.
• Rate limits. Each function declares Netlify’s own limiter in its config. The limiter counts addresses itself, so no IP address ever reaches our code or our storage.

Caching. The HTML, love.css, love.js and love-embed.js are checked again on every request (max-age=0, must-revalidate), because nothing is fingerprinted and a stale stylesheet against new markup is an unstyled room. Typefaces, audio/, raven/ and oracle/ are cached for a year; share cards and icons for a week; feed.xml, sitemap.xml and robots.txt for ten minutes.

Security headers. nosniff, Referrer-Policy: strict-origin-when-cross-origin, HSTS for two years, and X-Frame-Options: SAMEORIGIN with frame-ancestors 'self', because the laptop in the Solarpunk Hermitage frames this site inside itself. connect-src is 'self'. Permissions-Policy gives the players’ features to youtube-nocookie.com, the camera, microphone and screen to 8x8.vc only, and denies everything else.

Secrets live in Netlify’s environment, never in the repository. By name only:

The local server is not the site. npx serve sends no headers, so a policy failure only shows on the live host. It drops a query string on its clean-URL redirect, which Netlify does not. It runs no functions, so /cb/* answers 404 there; the CB runs under netlify dev after npm install, or live.

The front end

Every page is a hand-written HTML file at the repository root, complete before any script arrives, styled by one shared stylesheet and plain scripts with no framework and no dependencies. There is deliberately no design system: each room is its own visual world, and the code is arranged so that stays true.

A page. Its <body> class names the room, and that class is the hook for the room’s section of love.css and for its share card. The <head> carries, in order:

1. the pre-paint snippet, the same on every page byte for byte, which sets the dial from localStorage or prefers-reduced-motion before first paint; its sha256 is in the security policy;
2. the canonical address, the description and the Open Graph tags, with the share card written by make-og.py;
3. structured data from tools/structured.py, built from the page’s own title, description and address;
4. love.js, plus whatever scripts that room needs, all deferred.

love.css is one file in numbered sections. §1 is the self-hosted typefaces, with fonts/_sources.json recording where each came from. §2 is ground rules: every colour as a custom property on :root, and a global rule that keeps a hidden thing hidden. §3 is the intensity dial. §4 is shared furniture that is layout and never colour: the back link, the sign-off, the press-to-play plate, the job marker. Then each room, area or piece of street furniture gets a self-contained section, duplicating ideas in its own clothes on purpose. Small screens and print close the file. check-classes.py refuses a class claimed by two rooms, a custom property declared twice, and a section number out of order.

The dial. Gentle, Regular and MAX change motion and sparkle only, never content. §3’s reset carries !important, and rooms scope their own tilts with :where() so the reset can win. check-gentle.py measures every page at all three settings.

Press to play. A play button is a <button class="facade"> that names the thing and how long it runs. Nothing reaches a third party until it is pressed. Then love-embed.js checks the address against its list and swaps the button for a youtube-nocookie.com frame, or another origin on the list. A room styles the pressed state on the container, because the button’s classes do not survive the swap.

What your browser keeps. Only localStorage, and only in your browser: love-intensity (the dial), love-cb (your CB pass and handle), love-cb-guest (the guest panel left open), love-quests (the Guild’s list), love-rescues (animals you rescued) and love-breezy (Stay Breezy’s usual fans). Privacy says the same. Every read and write is wrapped so a private window still works.

Machine-readable files, all generated: sitemap.xml, llms.txt, feed.xml (from the changelog), cb-rooms.json, search-index.json, /.well-known/security.txt, /.well-known/api-catalog and the agent skill under /.well-known/agent-skills/.

Data and generators

The pages are hand-written, but any part of a page that restates a list, a credit or a fact held somewhere else is generated from a JSON file by a Python script, so the two cannot drift. The scripts are local tools in tools/; none of them runs on a server. The usual path is data/<room>.json to tools/make-<room>.py to the room’s page, between markers, and usually to the liner notes as credits too.

Marker regions. A generator only ever rewrites text between a pair of comments such as <!-- jukebox:begin --> and <!-- jukebox:end -->. Everything outside the markers is hand-written. Every page has at least the sign-off and the structured data between markers. A room somebody built with their own AI and brought in through Your Room sits between import:<slug> markers.

Generators refuse rather than guess. Each one checks its data against the promises its room makes before writing: a runtime on every track, a credit on every quotation, a consent record on every photograph, an allowed origin on every player. A refusal stops the build and nothing after it runs.

A generated file or region is never edited by hand. That covers feed.xml, sitemap.xml, llms.txt, cb-rooms.json, search-index.json, everything in og/, data/og-prints.json, the policy line and anything between markers. On a merge conflict in one of them, take either side, fix the source and run the build again.

Share cards. make-og.py drives headless Chrome to photograph a scrap of markup on the page’s own body class with love.css attached, and lifts the page’s heading word for word. There is a card design per room and no template. It keeps the committed picture when nothing that decides it has changed, because two Macs draw the soft edges of letters differently.

Checks

tools/check-all.sh is the build and the test suite in one. It runs every generator and every checker in the one order that works, stops at the first refusal, and changes nothing on a clean tree. It runs before every commit; Netlify does not run it.

1. The Node tests. netlify/cb/lib.test.mjs races writers against each other and fails if any write that was told it worked is missing. tools/fractal.test.mjs counts flashes in what the fractal window paints.
2. Images, before anything refers to one.
3. The room builders, each from its own data file.
4. The things that read the rooms: Now Playing, the map, sign-offs, structured data, the sitemap, the search index, the feed, the policy line, the agent files, share cards, icons and security.txt.
5. The checkers, against what was just written.

Left out of the build on purpose: anything that needs the network. check-jukebox.py asks YouTube’s watch page whether every play button’s video still plays and still embeds, and it is run by hand. A gate that fails on a train is a gate people learn to skip.

When a tool refuses, the cause gets fixed. Loosening a check, or adding an exemption to quiet it, is the one change the repository’s rules forbid outright.

Server side: the CB

The CB, a chat channel patterned after citizens band radio, is the only server-side code on the site: Netlify Functions in netlify/functions/ sharing one library, netlify/cb/lib.mjs, and one Netlify Blobs store. Every promise on Privacy is kept in that library.

How it runs. Each function is a JavaScript module whose config gives its address and a Netlify rate limit. A request carries the pass from the browser, readPass() checks it, and a change is written only if the stored copy has not changed since it was read, so people writing at once never lose a message. One scheduled function, cb-midnight, runs every hour and sweeps whatever has expired. It runs hourly because midnight in Colorado moves between 06:00 and 07:00 UTC.

The radio only asks while it is open and in front. One function in cb.js decides; folded, or in a background tab, the radio sends nothing. Open, it listens every four seconds. Tuned to World it says nothing about where it is; tuned to a room it names that room.

Never stored: an IP address (Netlify’s limiter counts them and never hands them over), anything a person types in a log line, an email address, or a list of who is on.

Roles. CB_MODS says which handles hold which roles, and it is read on every request. The server decides who may enter each private room in the Town Hall, in one function. A page that hides its radio from the wrong person is only keeping quiet; it is not the lock.

Calls are 8x8’s Jitsi as a Service. The CB signs a token with CB_JAAS_KEY for one room, and nobody joins without one. Guests get a token, never a moderator’s, only for the rooms Cavendish Coworking keeps open to the world. love-embed.js builds the call’s frame, and 8x8 is the only origin given the camera, microphone and screen.

Scheduled jobs

The rooms that show other sites’ feeds are snapshots refreshed by Ryan’s laptop each morning, not live pages. None of those hosts lets a page read its feed from another site, and the alternatives were a proxy we do not run or a third-party reader. Each room prints when it was last set, so a missed morning leaves an honest page rather than a wrong one.

The task. A Claude Code scheduled task, arrivals-board-daily, runs at 06:10 local time on Ryan’s machine. Its instructions are tracked in .claude/scheduled-tasks/arrivals-board-daily/SKILL.md, and tools/install-scheduled-task.sh installs that copy and reports drift. The schedule itself lives in the scheduler, not the repository.

Each script does the same five things. It refuses unless the tree is on main and its own files are clean. It pulls, which is the only network step; redraws its room; runs the fast offline checkers as a gate; then commits only its own files under a fixed subject and pushes. A failed push is left for a person. The scripts never rebase or force.

They run in that order, each whatever the last one returned, so one failing feed leaves the others filled. Every push deploys, so the morning makes a run of deploys. The commit subjects matter: the tool that writes Ryan’s weekly changelog skips exactly these.

Consequences. Before editing any of those files in the morning, pull first. If the laptop is asleep, the boards keep yesterday’s date. The build never pulls anything; the network tools run by hand are check-jukebox.py, pull-club.py and pull-foundry.py. The only job on Netlify’s side is the CB’s hourly sweep.

Third parties

A page load contacts nobody but stimpunks.world. The security policy makes that a property of the site rather than a habit: default-src, script-src, font-src, img-src and connect-src are all 'self', so there is no analytics, no CDN and no third-party script to remove. Every outside origin below is reached only after somebody presses something.

Adding an origin is one edit. It goes in a list in love-embed.js, then make-csp.py runs. The policy line in _headers is never edited by hand: the next run puts it back, and the local server sends no headers, so the mistake only shows on the live site.

Playing is not the same permission as embedding. A service can refuse to be framed (stoat.chat, music.apple.com) or publish no player at all (Qobuz), and a video can have embedding switched off or be age-gated. Those become links shaped like doors, never frames, and check-jukebox.py asks YouTube for every play button whether it may still be embedded.

Other outside traffic, none of it from your browser:

• Netlify hosts everything, runs the functions and holds the store.
• 8x8 calls /cb/call-events and /cb/call-settings as webhooks, and both are signature-checked.
• Ryan’s laptop reads YouTube’s channel feeds and watch pages and our sibling sites’ RSS each morning, and pull-foundry.py reads Google Fonts’ public repository when it is run.

Working on it

Ryan Boren and Helen Edgar both commit straight to main, one at a time, each working through their own Claude, and they agree outside the repository whose turn it is. A push is a deploy and nothing reviews it, so the routine is the safeguard:

1. Pull before touching anything; the morning task will have pushed.
2. Run tools/check-all.sh before every commit. Files it changes are generated files catching up with a source, and they go in with the change that caused them.
3. Commit and push when you stop. Uncommitted work blocks the other person and the morning task, which refuses to run over anybody’s edits.
4. Never hand-merge a generated file. Take either side, fix the source and run the build again.
5. A new changelog entry goes at the top with its own id, because the id is the feed item’s permanent address.

Where decisions are written. CLAUDE.md holds the rules sessions get wrong and why. DECISIONS.md lists what is open and what is settled. The changelog is the public record and feeds feed.xml. Privacy is the CB’s promise to the people on it. The liner notes hold every credit. SECURITY.md and /.well-known/security.txt say how to report a vulnerability privately.

Licence. Our words, markup and design are CC BY-SA 4.0. Photographs, recorded voices, songs and borrowed names keep their own terms, typefaces keep their own OFL or Apache 2.0 licences, and nothing musical is hosted here. The licence file says which is which.

Sources

Read from the repository on 2026-10-04: README.md, netlify.toml, _headers, _redirects, package.json, love.js, love-embed.js, the section headings of love.css, netlify/cb/lib.mjs and the config of every file in netlify/functions, tools/check-all.sh and the head of every checker, tools/daily-arrivals.sh, and the morning task’s instructions. When any of those changes in a way this page describes, this page changes with it, and the changelog says so.