Architecture
The code map: the direction registry, the toolchain as the single source and fork rescoping, the componentized instruments, the mirror.
How Prototemplate is put together, and the rules that keep its
twenty-seven directions coherent. Read DESIGN.md for the visual laws;
this file is the code map.
The shape of the app
src/
app/
page.tsx the index: the design lab (GalleryViewer), the
anatomy wall and the capabilities ledger
layout.tsx the root layout and the pre-boot theme script
d/<slug>/ one route per direction (src/lib/directions.ts)
d/toolchain/ THE SSOT: sections, diagrams, styles other forks import
d/_v0/ shared v0 sections (TranslateWindow, StackTower,
Locadex, FullStack, Deploy) used by the
singularity-* homes and the shipped site
d/production/ generaltranslation.com as it shipped, rebuilt
page for page, with the plate pages
directions/ /directions/<slug>: each direction as a book
page, with its live frame (DirectionFrame)
archive/[slug]/ the retired directions, kept as captures
(src/lib/archive.ts)
compare/ /compare: two directions in synced frames
present/ the presenter deck (intro, prototypes, scoreboard)
brand/ /brand: the brand book
docs/ /docs: the docs site, fumadocs' notebook layout
outside the viewer shell; layout.tsx, the one
page route [[...slug]] over content/docs (MDX,
read through src/lib/source.ts and
source.config.ts) and docs.css, the adapters
to the site's tokens
handbook/ registry.ts, the handbook's registry: its own
documents and the canon, which the docs pages
under /docs/handbook show
md/, llms.txt/, the agent files: the Markdown twins of every
llms-full.txt/, docs page, the handbook's included (reached at
AGENTS.md/ a page's address plus .md), /llms.txt,
/llms-full.txt and /AGENTS.md, generated from
the registries
api/search/ the docs site's static search index
craft/ the build log after docs/LIBRARIES.md on
/docs/handbook/libraries: laws, auditors and
live library plates (libraries.ts); /craft
redirects there
skills/ /skills, /skills/<slug> and the raw skill files
marks/ /marks: the mark explorations
blog/ the docs-redesign posts (content/blog) rendered with
the landing site's MDX components
graphics/ the illustration catalogue, read from
graphics/build/manifest.json
motion/ /motion and /motion/<slug>, from src/lib/motion.ts
api/try/fetch/ the one runtime function, behind the shipped /try
prototemplate.css the pt grammar (index + craft chrome)
globals.css the four color tokens
components/
viewer/ the viewer shell every route except /deck,
/present, /blog, /docs and /d runs on: ViewerShell,
Sidebar, Toolbar, Sheet, BookView, GridView,
IndexPanel, Search, PreviewLayer, tokens.css
shared/ cross-page instruments: EverySentence, StudioField,
PrismaticField, HeroFieldSwitcher, TcMobileNav,
diagrams/ (DoubledLine and the older line-art
set); FeatureBento, StorySection and
LanguageWheel are unmounted references
blog/ the blog's MDX components (PostAuthors, PostCover,
Carousel, AuthorSpotlight and the figures)
try/ the report card the shipped /try page mounts
book/ book.tsx (reads a repository file on the
server), model.ts (the handbook's addresses),
markdown.tsx and links.ts (the renderer the
skills and motion pages use, and where a
repository path opens on the site)
docs/ the docs site's parts: the sidebar footer, the
theme button, the page actions, the sidebar
motion copied from gt-cloud, pages.ts (the
pages outside the handbook as the hub's
registries list them) and demos/, the live
plates the Components pages and the handbook
mount, each loaded through demos/lazy.tsx
blog-globe/ the blog globe figures on /docs/components/blog-globe, each
a frame of its round's route under
src/app/d/blog-globe
shell/ Bento primitives (Rails / BentoRow / BentoCell)
plate/ the dashboard's sign-in and onboarding system
(frame, field, pages, fixtures) with its state
console, served under /d/production/{signin,
onboarding,consent,device,cli}
lib/ the registries: surfaces.ts, search-index.ts,
shell-data.ts, directions.ts (the direction
registry), archive.ts, marks.ts, page-names.ts
(each page's plain name); the engines: dither.ts,
studio-field.ts, glyph-field.ts, horizon-field.ts,
prismatic-field.ts; try/ (the report card's
checks); and the generated skills.ts, motion.ts
and updated.ts (build/updated.mjs; server modules
only) with page-updated.ts (its type); the hooks:
use-mount-effect.ts and use-layout-work.ts
(dependency layout effects with useGSAP's timing,
without GSAP)
scripts/ pnpm names are the interface; every entry point
takes --help
lib/root.mjs the repository root every script resolves from
lib/site-pages.mjs page discovery, the theme door, PT_BASE and the
Chrome the browser scripts share
lib/help.mjs --help: prints a script's opening comment
build/deck.mjs deck/ to public/brand-deck.html and
public/shots/deck (pnpm build:deck); next.config.ts
rewrites /deck to the built file
build/thumbs.mjs the 640x360 previews in public/shots/thumb, cut
from the captures under public/shots
build/skills.mjs skills/ to src/lib/skills.ts and skills/README.md,
with the skill contract and lint (pnpm
build:skills; --check is pnpm lint:skills)
build/updated.mjs git to src/lib/updated.ts, the day each book page
last changed for its head's Updated row
(pnpm build:updated; --check is pnpm
lint:updated, in the build), with its tests
build/speed-marks.mjs the speed marks under public/marks
build/subset-inter.py the Inter roman and italic to unicode-range
subsets in public/fonts/inter, their faces in
src/app/inter-subsets.css and the latin range in
src/lib/fonts.ts (pnpm build:inter)
build/motion.mjs motion/ to src/lib/motion.ts and public/motion,
run only when the Videos session hands a film over
check/capture-pages.mjs the 1440x900 page captures in public/shots/pages
that build/thumbs.mjs cuts
check/gallery-shoot.mjs the anatomy wall's tiles (see "The gallery
pipeline")
check/pagecheck/ the page check: every page at ten viewports in
both themes, layout shifts, interactions, a
report (pnpm check:pages; its README explains)
lint/lines.mjs the line auditor (see docs/SHIP-LOOP.md)
lint/practices.mjs the practices ratchet (+ baseline JSON)
lint/type.mjs the type lint: one Inter through the tokens,
static (lint:type, in the build) and --live
(lint:type:live), with its ratchet baseline
type.baseline.json and its tests
lint/radius.mjs the radius lint: rounded controls, square shells,
every corner through the six --pt-radius-<role>
tokens, static (lint:radius, in the build) and
--live (lint:radius:live), with its tests
lint/heads.mjs the book page lint: one head, one band, one
divider grammar on every book, static
(lint:heads, in the build) and --live
(lint:heads:live), with its tests
lint/pictures.mjs the artifact picture standard
(docs/ARTIFACT-PICTURES.md), in the build
lint/shell.mjs token discipline for the shell layer
lint/registries.mjs registry drift: headings, route lists, first
slugs, the skill contract (pnpm lint:registries)
lint/oxlint-plugins/ the gt-ui rules pnpm lint:code runs
media/mood-tone/ the artifact picture cutter and standard.json
skills/install.mjs links or copies skills/<slug> into a project's
.claude/skills and .agents/skills (pnpm
skills:install; its tests: install.test.mjs,
pnpm test:skills)
docs/
handbook/ how Kevin runs GT work, served at /docs/handbook:
the operating principles, the quality bar, the
multi-session playbook, the product map, the
glossary and the decisions log, with README.md
research/, reference/, reference-shots/, composites/
the exploration archive the skills cite;
nothing here is served
archive/ finished round specs kept as history, with a
README naming each one; nothing here is served
deck/ the deck source: parts/, slides/, fonts/, shots/
graphics/ the blog-illustration toolchain (docs/GRAPHICS.md)
content/ the three docs-redesign posts and their authors
public/ what the site serves: brand-deck.html, shots/
(captures, thumbnails, the gallery tiles), brand/,
marks/, media/ and motion/ (films), static/
(blog images and avatars), fonts/, logos/
skills/ the curated skills, one folder per skill
(SKILL.md, references/, scripts/); the canonical
copy, published on /skills
.claude/skills/, .agents/skills/
relative links to skills/<slug>, made by
pnpm skills:install --project .
motion/ the films, untracked, owned by the Videos session
AGENTS.md the agent entry point (CLAUDE.md imports it);
served at /docs/handbook/agents and raw at
/AGENTS.md
content/docs/ the docs site's MDX pages, one folder per tab,
each with its meta.json: (guide)/ with
handbook/ (a page per handbook and canon file),
components/ (the live component library),
craft/, engineering/ and (internals)/; a folder
group (name) adds no URL segmentThe direction registry
src/lib/directions.ts is the single source of truth for what exists:
twenty-seven directions, four of them full site pairs (site: true):
singularity-dossier, singularity-orbit, singularity-signal and
production, the shipped site. singularity-dossier is the completed
concept; signal and orbit keep their own heroes and carry the
previous-generation sections the dossier retired, as exploration
showcases. The index and the sitemap map over DIRECTIONS, and the
presenter walks its first 16 without Signal
(src/app/present/directions.ts), so adding or removing a direction there
updates all three. When a direction is deleted, also sweep
scripts/lint/practices.baseline.json for its paths, record it in
src/lib/archive.ts, and re-check stated counts (index funnel, layout
description, craft intro).
The SSOT rule
src/app/d/toolchain/ is the single source of truth for the tc-*
vocabulary. The fork homes (chroma-flow, dither-field, aurora-paper,
glyph-rain, prism-light, lens-gate, paper-foundry, terminus-board,
wide-rule, event-horizon, hourglass, singularity and the rest) import
toolchain's sections and diagrams directly and re-skin by root-class
rescoping: each fork carries a root class (.lensgate-root,
.terminusboard-root, and so on) and copies only the CSS it must
re-scope.
- Never edit toolchain's files as part of fork work; change the SSOT only when the change is meant for every consumer.
- The frozen local copies of toolchain sections that aurora-paper and
chroma-flow carried were deleted on 2026-10-08, since nothing imported
them. Fork copies that remain are imported (
glyph-rain/diagrams/lang/*among them). Before adding a new copy, import the SSOT and rescope CSS instead. - The singularity-* homes are toolchain-based (
toolchain-root sgXh-root) and pull shared v0 sections fromsrc/app/d/_v0/; their/enterprisepages are singularity-based. Never edit toolchain's TopNav for one site.
Componentized instruments
The signature pieces live as libraries, outside page code. Each has a live
plate and an API snippet in the build log on /docs/handbook/libraries
(src/app/craft/libraries.ts):
| module | what it is |
|---|---|
src/lib/horizon-field.ts | WebGL lensing black hole |
src/lib/glyph-field.ts | canvas glyph rain (drift, copy modes, matter-conserving morphs) |
src/components/shared/PrismaticField.tsx | the chroma wash |
src/lib/dither.ts | CPU 1-bit Bayer field renderer + field factories |
src/lib/studio-field.ts | GPU Bayer family, the BAYER_PRESETS roster |
src/app/d/toolchain/diagrams/iso.ts | the isometric kit (boxes, prisms, plane, markPath) |
src/app/d/toolchain/diagrams/DitheredMark.tsx | masked logo + Bayer shimmer |
src/components/shared/diagrams/DoubledLine.tsx | the two-thread stroke (two-tone capable) |
src/app/d/toolchain/diagrams/EdgeGlobe.tsx | the delivery globe |
src/app/d/toolchain/components/LocaleTag.tsx | the locale pill |
src/app/d/toolchain/sections/RevealSeam.tsx | the slide-to-reveal seam |
src/components/shared/EverySentence.tsx | the sentence-rewriting morph |
When a page needs one of these behaviors, mount the component and do not re-implement it locally. When an engine gains an option, update its build log entry (body and snippet) in the same round.
The gallery pipeline
The index's anatomy wall is fed by one shooter, and the file names are the contract between the two ends:
- The shooter (
scripts/check/gallery-shoot.mjs) shoots the flagship home section by section across desktop and mobile cuts and both themes. It takes element screenshots anchored on each section's own landmark selector, never scroll depths, so side-by-side pairs align at any viewport. AnaddInitScriptwriteslocalStorage['gt-theme']before first paint, which the root inline script applies, and one full scroll pass settles every lazy section before the first shot. A selector that misses is reported and skipped. - The manifest: the shooter writes
manifest.jsonbeside the tiles,{ flagship, generatedFor, sections: [{ key, label, cut, theme, file }] }. Nothing reads it today; it records what the last run shot. - The tile names are what the anatomy wall (
src/app/AnatomyWall.tsx) reads:sec-<key>-<cut>-<theme>.jpgunderpublic/shots/gallery/(key is hero, customers, story, developer, locadex, context, global, deploy or footer; cut is desk or mob; theme is light or dark). The wall accepts a.pngunder the same stem, and a missing tile leaves hatched ground. Thevar-*tiles still in the folder are the retired directions' last dark captures; nothing renders them. /compareputs two directions side by side as synced same-origin iframes. Same origin is what lets the route drive both frames' scroll and theme together.src/app/SiteCompare.tsxis the still-image version: two captures under the house seam, the cut held in one CSS variable.
Skills and docs
AGENTS.md: the entry point for an agent, here or in a project that imported the hub (served at /docs/handbook/agents;CLAUDE.mdimports it).BRAND.md: the identity canon (the brand book the agency reads; served at /docs/handbook/brand and /brand).DESIGN.md: the visual canon (this repo's law book).docs/SHIP-LOOP.md: the verify/ship procedure every round runs.docs/LIBRARIES.md: the library index (defers to the build log after it on/docs/handbook/librariesfor depth).docs/GRAPHICS.md: the graphics pipeline: how the blog illustrations are made withgraphics/, and the rules that came out of review.docs/handbook/: the handbook, what spans the skills (principles, the quality bar, the multi-session playbook, the product map, the glossary, the decisions log).src/app/handbook/registry.tslists it with the canon after it (AGENTS.md,BRAND.md,DESIGN.md, this file, the ship loop, the tools, the libraries, the graphics pipeline and the artifact pictures), and/docs/handbookshows each file on a docs page of its own (content/docs/(guide)/handbook/, through fumadocs-mdx's include tag;src/lib/remark-handbook.tsdrops the file's h1 and prints raw HTML as text). A relative link in any shown document resolves the way GitHub resolves it (src/components/book/links.ts): a shown document opens its page, a skill its page, any other file GitHub./handbookand every/handbook/<slug>answer 308 with the page under/docs/handbook.content/docs/: the docs site, rendered at/docsby fumadocs (source.config.ts,src/lib/source.ts,src/app/docs,src/components/docs) in five tabs, each a folder whosemeta.jsonsets"root": true: the Guide ((guide)/, with the handbook), the Components (components/, every instrument live with its controls, props and reduced-motion still, and the blog globe figure with all three rounds live), Craft (craft/), Engineering (engineering/) and Internals ((internals)/). A folder named in parentheses groups pages in the sidebar and adds no URL segment./docs/templateexplains how to lift it into another project and how a page picks its tab and folder.src/lib/seo/: the SEO system. Every route's head comes from oneseoRoute()call under the policy inpolicy.ts;/docs/seoexplains it.skills/<slug>/is the one copy of each curated skill: SKILL.md with its frontmatter contract (name, description with "Use when", metadata title, areas, updated and origin), its references and scripts.scripts/build/skills.mjsvalidates the set and writessrc/lib/skills.tsand the folder's index,skills/README.md;/skillsand/skills/<slug>render it, the pages read each body from the folder on the server, andsrc/app/skills/[slug]/[...path]/route.tsserves the raw files.scripts/skills/install.mjslinks or copies the set into any project (--project <dir>,--user,--into <dir>, with--dry-run). This repository's.claude/skillsand.agents/skillsare its relative links (--project .); README.md's Skills section has the rules.
The mirror
Prototemplate main has been the only copy of this code since
2026-09-08, when gt-cloud's apps/redesign stopped being one, so nothing
is copied or rsynced into it from another tree (docs/SHIP-LOOP.md
section 7).