ai-cms architecture

The engine, ai-cms

Published to the GitLab package registry as @fivepaths/ai-cms, exposing a cms binary.

Sites pin an exact version. cms upgrade bumps it, regenerates the derived files, rebuilds, and runs the gate, so an engine change that would move a site's markup shows up as a reviewable diff before it ships.

cms is a dev dependency of each site, resolved from node_modules/.bin, not installed globally. A global binary would pin every site on a machine to one engine version and let CI drift from local, which is the failure the per-site pin exists to prevent.

A site, for example gtfs-media

Content, media, site-only CSS and components, prompt overrides, and the generated Claude Code files. Nothing about the engine is vendored in.

The engine reaches a site repo through three channels and no others: the package in node_modules, the prompt and hook files cms sync generates, and the component reference cms docs generates. Only the last two are committed, and both are text rather than code, so a git diff after an upgrade shows everything the engine changed about how this site behaves.

---
title: "Every rider screen, straight from your GTFS feeds"
description: gtfs.media turns your agency's GTFS feeds into live displays,
  vehicle maps, timetables, and JSON APIs.
layout: landing
---

:::hero
heading: Every rider screen, straight from your GTFS feeds.
lead: |
  gtfs.media turns the [GTFS](https://gtfs.org/) and
  [GTFS-Realtime](https://gtfs.org/documentation/overview/) feeds you already
  publish into live departure displays, vehicle maps, timetables, and clean
  JSON APIs.
ctas:
  - { label: Get in touch, href: "mailto:hello@gtfs.media", style: primary }
  - { label: For transit agencies, href: /agencies/, style: ghost }
:::

:::plain
body: |
  Transit agencies publish their timetables in a standard file. It is called
  GTFS. This software reads that file and turns it into things riders can use.
:::

:::cards
heading: One platform, three layers
lead: A structured data core, a realtime pipeline, and rider-facing surfaces.
items:
  - title: Data platform
    href: /developers/
    icon: database
    body: Import any GTFS feed into structured, fieldable, editable content.
:::

The block splitter runs before markdown parsing and takes :::type regions as raw text. That keeps YAML bodies out of the markdown parser entirely, which is what makes the format predictable instead of dependent on directive-syntax edge cases.

Templates

Layouts, partials, and component templates are Nunjucks HTML files. A component that needs computation gets an optional props.js beside its template: responsive image markup, nav state, anchor generation. A person can restyle a component by editing HTML; nothing forces them into JavaScript.

A site overrides a component by putting a file of the same name in src/components/. Site files win over engine files. The schema still comes from the engine unless the site ships one too, so an override changes the markup without silently changing the field contract.

The normalizer, and what "pristine" means concretely

After rendering, the HTML is parsed and re-serialized under fixed rules:

• Class allowlist. The engine parses base.css and the site's site.css and collects every class selector they define. Any class in the output that is not in that set fails the build. Markup can only use classes the CSS actually implements, and dead classes cannot accumulate.
• No inline styles, no colour literals. A style attribute or a hex value anywhere in output is a build failure. Colour comes from --fp-* tokens.
• Semantic element preference. A configurable rule set flags a div used where section, nav, figure, ul, or article fits.
• Deterministic formatting. Two-space indent, stable attribute order, fixed entity handling. The same commit always produces byte-identical output, so git diff on a rebuild shows only real changes and CI can assert the build is clean.

src/media/pylon-single.jpg
src/media/pylon-single.yml
  alt: Platform pylon display showing a route badge, a service alert, live
    departures, and route information
  focal: [0.5, 0.35]
  decorative: false
  contains_text: true      # triggers the WCAG 1.4.9 attestation

public/assets/img/pylon-single.<hash>-{480,768,1200,1800}.{avif,webp,jpg}

cms check is the single entry point. Claude Code runs it, the developer runs it, CI runs it, and nothing deploys without it.

1. Schema. Every block validates against its component schema.
2. Build. The site renders. Any render error fails here.
3. Markup. Class allowlist, no inline style or colour literal, semantic element rules, html-validate for structural validity.
4. Content rules. Heading order with no skipped levels and one h1 per page; link text meaningful in isolation; external links carrying the visually-hidden new-tab note; every image with alt or an explicit decorative flag; lang present and correct.
5. Automated accessibility. axe-core over every built page, in both colour schemes, at 320px, 768px, and 1280px, with the AA and AAA rule tags enabled.
6. Links. The internal link graph resolves. A broken internal link fails. External links are checked on a schedule instead, because they are flaky.
7. Budgets. Lighthouse mobile against the preview deployment, with per-page transfer and Core Web Vitals thresholds in .cms/budgets.json.
8. Conformance ledger. Every AAA criterion that cannot be automated has a current attestation. See ACCESSIBILITY.md.

cms check --page <file> --fast runs 1 through 4 for one page in well under a second, which is what the Claude Code hook uses on every write. The full run is for the pre-commit and CI paths.

engine   ai-cms/prompts/<slot>.md
site     .cms/prompts/<slot>.md      (frontmatter: mode: append | prepend | replace)

cms new page <route> --layout <layout>
cms move <route> <new-route>        rewrites inbound links, writes the redirect
cms rm <route>                      same, plus a 410 or a redirect
cms nav add|move|rm                 edits nav.yml, every page picks it up
cms media add <file>                import, sidecar, alt-text prompt
cms outline <route>                 numbered block list for addressing edits
cms block insert|move|rm <route> <n>
cms dev                             local server, live reload, fast check
cms build | check | sync | upgrade
cms docs                            regenerate the human component reference
cms explain <component>             print one component's reference
cms translate <route> --to <locale> draft a translation, field by field
cms import <html>                   one HTML file to blocks
cms ingest <url>                    a whole site to a site repo

Git is the store. Every accepted edit is a commit, so undo, blame, and review come from the tool the developers already use, and the agent's work reads as a diff.

Branches. Content work happens on a branch. Pushing opens a merge request in the self-hosted GitLab.

Pipeline.

• Merge request pipelines deploy a preview and post its URL back to the MR.
• The default branch deploys production.
• check gates deploy in both. A failing check means no deployment exists to look at, which is the intended pressure.

Cloudflare. Workers static assets, matching what gtfs-media and fivepaths-cdn already do. The default branch runs wrangler deploy; a branch pipeline runs wrangler versions upload, which returns a version preview URL the job posts back to the merge request. Preview URLs have to be enabled on the Worker for that to resolve, which is worth confirming against the existing Workers before the first branch pipeline runs.

CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID are masked, protected CI variables. The account is pinned in wrangler.jsonc the same way the existing repos pin it, because more than one Cloudflare account exists on these machines and an unpinned deploy has landed in the wrong one before.

Caches. The GitLab runner keeps the node module cache; generated image variants come from R2 by content hash.

The local loop

cms dev is where the work actually happens: a local server on src/, with incremental rebuild and live reload, and the fast check running on every save. A check failure appears in the terminal and as an overlay in the page, so a broken schema or a missing alt text is visible in the same second it is written, by the person and by the agent.

Two things are deliberately different in dev. Images are resized on demand from the originals and cached locally, skipping AVIF entirely, because waiting on an encode is the fastest way to make people stop running the dev server. And the full check, with axe across three widths and two schemes, runs on demand and at commit rather than on every keystroke.

The whole workflow is therefore: cms dev while working, commit, push, and the pipeline deploys. Nothing else to learn.

Overpass is the default, not a requirement. A site with its own brand face declares it, and the engine handles the rest.

The build subsets each face to the ranges the site's locales actually use, converts to woff2, writes the @font-face rules and the --fp-sans or --fp-mono override into the site's stylesheet, and emits the preload link for the one face first paint needs. A variable font is preferred, for the reason the shared sheet already uses two of them: one file covers every weight the design system asks for.

Four rules hold.

Self-hosted, always. A face is served from the site's origin or from cdn.fivepaths.com, never linked from a third-party font host. That is a privacy position and a performance one at the same time, and it keeps the head of every page pointing at origins the project controls.

A licence travels with the file. No licence record, no build. The OFL file sitting beside Overpass on the CDN is the pattern, and the check enforces it rather than trusting that someone looked.

Shared faces go to the CDN, site faces stay local. The same rule the component catalogue follows: a face appearing on a second site belongs in fivepaths-cdn, under a version path, so both sites get the same bytes and the same cache entry.

Fonts count against the budget. .cms/budgets.json caps font files and their total bytes per page. The shared sheet spends two files; a site adding two more has to be able to say why, and the number is in the check output rather than in anyone's memory.

The check also verifies the declared face actually loaded rather than falling back silently, which is the failure mode that survives review because the page still looks fine to whoever has the font installed locally.

src/generators/api-reference.js     exports (data, ctx) => [ {type, fields}, ... ]
src/data/openapi.yaml               its input

generated:
  /api/:
    generator: api-reference
    data: src/data/openapi.yaml

cms ingest <url> crawls a site of under fifty pages and produces a site repo in this format: markdown pages, nav and site data, imported media with sidecars, and a site.css that is as close to nothing but token overrides as the source allows. It ships as a skill, /ingest, because the mechanical stages belong in the CLI and the judgment stages belong to the agent.

Two parts of it matter to the architecture. Chrome is found by diffing the DOM across pages and becomes nav.yml and site.yml rather than markup, which is the same collapse the gtfs.media migration performs by hand. And the source site's colours are sampled, assigned to token roles, and repaired in OKLCH until every pairing clears 7:1, so a brand survives the move into an AAA palette while staying recognisable. .cms/budgets.json carries a line budget for the generated site.css, reported by cms check on every run.

The full design is in INGEST.md.

• Whether preview URLs are enabled on the existing Workers, which is what the branch pipeline needs to post a link back to a merge request.
• Whether a stale translation blocks the build or warns, per site. Both are defensible and the setting is explicit; the default is the question.
• Which locales gtfs.media actually needs. The pylon screens are already multilingual, so the site probably follows, and that set determines whether the design system needs a face beyond Overpass's coverage.