How this site works

Everything that runs, in five lanes: people and agents, the edge, the API, the data, and the services outside. Pick a path and step through it. Each step shows the request it stands for. Click any box to see what it is. This is a map, not a live status board.

1 · Someone browsing → Next.js site
A browser asks for a page
The request reaches the Next.js site on Fly. The proxy sees an HTML Accept header, so it serves the page, and adds a Link header that points agents at the markdown twin and llms.txt.
```
GET /projects/bagman HTTP/1.1
Accept: text/html

# response headers
Vary: Accept
Link: <https://bokendell.com/projects/bagman.md>; rel="alternate"; type="text/markdown",
      <https://bokendell.com/llms.txt>; rel="describedby"
```
2 · Next.js site → MDX in the repo
The case study body is a file
The page imports content/projects/bagman.mdx. The words, diagrams and demos ship inside the build. They are not in the database.
```
import(`content/projects/${slug}.mdx`)
# meta (title, status, metric) + the body component
```
3 · Next.js site → Hono API
Lists and links come from the API
In parallel, the page asks the API for the project's row and the full list, through a typed oRPC client.
```
POST https://api.bokendell.com/api/rpc/v1/projects/getBySlug
{ "json": { "slug": "bagman" } }
```
4 · Hono API → Neon Postgres
The API reads Postgres
A domain service reads the row from Neon through Drizzle and maps it to the public shape. That row was written by swarm content sync from the MDX front matter.
```
select … from projects where slug = 'bagman'
# the same read backs REST: GET /api/v1/projects/bagman
```
5 · Someone browsing → Next.js site
HTML goes back
The page is regenerated at most once an hour, so most visitors never wait on the API, and a sleeping API machine is not woken for every view.
```
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
# export const revalidate = 3600 on the route
```

The long version is the this site case study.

How this site works

A browser asks for a page

The case study body is a file

Lists and links come from the API

The API reads Postgres

HTML goes back