Architecture · Forge v0.4

Forge.

The engineering page for Forge. What it is, what it refuses to be, what's actually shipped.

The honest history

An earlier Forge shipped a polished wizard backed by /api/forge/* endpoints that returned 404 in production. The wizard could be completed, but the export could not. That deploy was torn down alongside the marketing copy that promised a browser-only product the code did not implement.

v0.4 is the rebuild after 3 iterations in public: v0.1 manifesto + role picker · v0.2 24 templates + first builder + single-HTML export · v0.3 portal-based full-screen takeover, taste-bar locked · v0.4 3-pane Webflow-style builder, 35 templates, full palette editor, 5 font pairs, device toggle, glowing F-icon.

Operating principles · non-negotiable

No server — Every byte is generated in the browser. Zero /api/* endpoints. Verifiable in DevTools — zero outbound network after the bundle and Google Fonts load. This is what makes Forge structurally free to operate.
No account, no telemetry — State lives in React useState while the tab is open. No password to forget. No email to verify. No analytics. The only thing leaving your machine is the HTML file when you click Download.
Receipt-enforced — Every project requires a verifiable proof URL. Failing items render as italic [no proof] in the output — visible to recruiters, not hidden. Validation is shallow URL parsing today; CORS HEAD checks are a v0.5 target.
Deterministic — renderTemplate(state) is a pure function. Same input → byte-identical HTML output. The live preview and the downloaded file use the same renderer; what you see is what ships.
One file out the door — The export is a single self-contained .html file. Inline CSS, Google Fonts via CDN link. Drop on any static host or your own server. No build step. No npm install. ~8 KB.

Exported a file and not sure where it goes? Deploy it to your own domain in two minutes →

What ships in v0.4 · live

Verifiable at /forge right now:

35 templates across 10 role categories — Software/IT, Design, Writing, Beauty, Arts, Trades, Healthcare, Finance, Education, Sales. Each template = palette + typography + skeleton layout.
3-pane builder UI — Left nav (sections) + huge center preview + right inspector. Webflow / Figma / Framer pattern. Cmd+1..5 keyboard shortcuts.
Full palette editor — 10 curated preset palettes + 6 editable color slots (bg, surface, ink, mute, accent, rule). Native color picker + hex input.
5 font pairs — Modern (Inter Tight), Editorial (Fraunces + Inter Tight), Geometric (Space Grotesk), Pure Serif (Fraunces), Terminal (all Geist Mono).
Device toggle — Mobile (390px with frame) and desktop preview. The exported HTML is responsive either way.
Single-file HTML export — Terminal Dossier template exports today. Pure-fn renderer; deterministic; byte-equivalent to the live preview.

Roadmap · honest about state

v0.4 · shipped — 35 templates, 3-pane builder, full palette + fonts + device toggle, Terminal Dossier exports.
v0.5 · next — More template renderers ship exports (not just Terminal Dossier). localStorage persistence so refresh stops losing work. CORS HEAD checks on every proof URL.
later · maybe — PDF resume export, LinkedIn About snippet, social header generation. No promises on dates — they only ship when the architecture is honest about how.

For engineers · actual architecture

What's actually running in production:

React 19 + TanStack Start — The Forge surface lives at /forge/* inside the same TanStack Start app that hosts the rest of zacgibson.work.
Templates registry — TypeScript array — TEMPLATES: TemplateMeta[] in src/lib/forge/templates.ts. Each entry: slug, role, palette, typography, skeleton, shippable flag. 35 entries today.
Pure-fn renderer — renderTemplate(state) → string in src/lib/forge/render.ts. Switches on the skeleton type, emits inline-CSS HTML. Same fn for live preview and download — byte-equivalent.
Single-file export (no jszip) — downloadPortfolio(state) wraps the rendered body in a complete HTML doc with <link> to Google Fonts, creates a Blob, triggers a browser download. No ZIP. No Astro build. One file.
Builder state — React useState — No Zustand, no Redux. useState<PortfolioState> with action functions. Lives in memory while the tab is open.
Full-screen takeover via React Portal — The builder portals to document.body to escape the <main> stacking context. CSS hides .paper-bg when body.forge-builder-active.
Keyboard navigation — Cmd/Ctrl + 1..5 switches inspector sections. Not a cmdk palette — just a global keydown listener.
HD pass — SVG noise + multi-stop gradients — Banding mitigation via feTurbulence data-URI overlay at ~4.5% opacity, mix-blend-mode overlay. Same technique Apple/Linear/Stripe use.