Decisions behind this site
23 architecture decision records, as the repository keeps them: what prompted each decision, what was chosen and what it costs. When a later decision changes an earlier one, it amends the record instead of rewriting it.
ADR 0001
A React app rendered to static HTML at build time
Crawlers that never run JavaScript, and phones on slow networks, get the content in the first byte; the browser then hydrates the HTML instead of rendering from scratch.
Accepted 1 October 2026, revised 2 October 2026
ADR 0002
Static site on Cloud Storage behind an HTTPS load balancer, API on the same origin
The static site is served from a Cloud Storage bucket behind Google’s HTTPS load balancer, which also routes /api to Cloud Run, so the site and its API share one origin.
Accepted 1 October 2026
ADR 0003
Java 21 and Spring Boot 4 on Cloud Run, on virtual threads
The API is Spring Boot 4 on Java 21 with virtual threads, in a container on Cloud Run that scales to zero, with class data sharing to shorten cold starts.
Accepted 1 October 2026 · runtime amended by ADR 0009: Java 25 with an AOT cache
ADR 0004
No login wall for visitors
The site stays open: visits are attributed with tagged links and cookieless analytics, and visitors introduce themselves only if they choose to.
Accepted 1 October 2026 · a deeper question needs an account, see ADR 0023
ADR 0005
PostgreSQL on Neon for visits and introductions
Visits and introductions go to serverless PostgreSQL on Neon’s free tier, with Flyway migrations; moving to Cloud SQL is a connection-string change.
Accepted 1 October 2026, revised 25 October 2026 · built 2026-10-03 with plain SQL rather than Spring Data, see ADR 0012 · the assistant keeps nothing here, see ADR 0019 · accounts keep what their holders choose, see ADR 0023
ADR 0006
Public compute endpoints are protected like production APIs
Every public lab endpoint validates its input, rate-limits each client, admits one benchmark at a time and stops long runs at a deadline.
Accepted 1 October 2026
ADR 0007
Privacy first: no cookies, no third-party trackers, self-hosted fonts
Nothing to consent to: no cookie banner, no third-party script, fonts served by the site itself, and analytics, when they come, first-party and cookieless.
Accepted 1 October 2026, revised 25 October 2026 · the guide's voice goes through the browser's own speech, not this site · the session cookie covers signed-in visitors since ADR 0023
ADR 0008
Visual design: an instrument, not a magazine
The site is designed as a measuring instrument: monochrome chrome, colour only for measured data and status, one type family, and the live JVM as the first screen.
Accepted 1 October 2026 · colour and motion amended by ADR 0020: a brand, a colour for each area, motion that reveals
ADR 0009
Java 25 with an AOT cache, measured
The API moves to Java 25 with an AOT cache trained at build time: ready in 3.5 s instead of 4.2 s on one vCPU, for 47 MiB more memory at idle.
Accepted 3 October 2026 · amends ADR 0003
ADR 0010
The software bill of materials is public
The API serves its CycloneDX bill of materials at /api/sbom/application, the same list of dependencies the public repository already implies, so anyone can check what runs behind the site.
Accepted 3 October 2026
ADR 0011
The leak runs in a JVM of its own
The memory-leak experiment runs its workload in a second JVM inside the API's container, one at a time: a leak meant to end in OutOfMemoryError cannot run in the server's own heap.
Accepted 3 October 2026
ADR 0012
PostgreSQL through plain SQL, optional, migrated before a deploy
The API reaches PostgreSQL with plain SQL through JdbcClient, starts and serves everything else without a database, and migrates it in a deploy step, never during a cold start.
Accepted 3 October 2026
ADR 0013
The API reference, generated from the code in a test
The OpenAPI document is generated from the application in a test, completed with what the code enforces and with recorded responses, and rendered by the site. springdoc never ships.
Accepted 3 October 2026
ADR 0014
Visits counted without cookies
Each page view is counted on the site's own server with its path, a link's tag, the referring host, a screen class and a pseudonym that lasts a day; no cookie, no address, no third party.
Accepted 3 October 2026, revised 7 November 2026 · the guide's work counted beside, in numbers alone, and what it could not answer by topic
ADR 0015
Introductions, drafted then confirmed, behind a proof of work of the site's own
A visitor's introduction is drafted, shown back and confirmed, after a honeypot, content rules and an ALTCHA proof of work solved in the site's own worker; kept 180 days, read by the owner alone.
Accepted 3 October 2026, revised 7 November 2026 · a conversation with the guide may go with one, on the visitor's word
ADR 0016
The owner's admin, behind Google's sign-in, beside a public API that keeps no session
One owner signs in with Google to read visits and introductions; the admin has a session cookie and CSRF tokens, while the public API keeps none, and visitors still get no cookie.
Accepted 3 October 2026 · anyone may sign in since ADR 0023; the admin stays the owner's
ADR 0017
The fit check: a model drafts from a shortlist, every claim is checked, the owner publishes
A job posting becomes an unlisted page mapping each requirement to evidence on this site: shortlisted by code, matched by a model that may cite nothing else, checked, and published by the owner.
Accepted 4 October 2026
ADR 0018
The fit check for visitors: paid for by a proof of work and a daily budget, kept by no one
Once the owner turns it on, visitors check their own postings behind a rate limit, a proof of work and a daily budget; nothing is kept, and a claim nobody can vouch for is withheld.
Accepted 4 October 2026
ADR 0019
The assistant answers from the site's record, a sentence at a time, each one checked
Questions about Armen's work, answered only from what the site says: streamed a sentence at a time, each held to the sections it cites; pay and private life refused by rule.
Accepted 4 October 2026 · amended by ADR 0021: a guide that also shows, on Claude Haiku 5.5 with a cache, twelve questions a conversation and the whole of it kept · a question of one's own needs an account since ADR 0023
ADR 0020
Colour and motion: the instrument, lit
The chrome takes colour and motion: surfaces tinted blue, a violet-to-cyan brand, a colour for each area of expertise, and motion that reveals and responds, off under reduced motion.
Accepted 5 October 2026 · amends ADR 0008
ADR 0021
The guide shows what it says, with five tools made from the site's manifest
The assistant becomes the site's guide: it may open a page, point at something, run an experiment, start a tour or offer a next step, each call held to the site's manifest in code.
Accepted 25 October 2026 · amends ADR 0019
ADR 0022
Infrastructure as code: declared for what lasts, scripted for each release
The site's Google Cloud infrastructure is declared as code, planned before it changes and tested in CI on a mocked provider; scripts keep each release's image and files.
Accepted 7 November 2026
ADR 0023
Accounts for deeper questions
Everyone gets prepared answers; a deeper question needs an account: a sign-in, a second factor and a short form, and a conversation is kept only if its visitor asks.
Accepted 8 November 2026