# Tech Stack — ForgeAI Studio > Owner: Anthony Kautz · Updated: 2026-08-04 --- ## Overview ForgeAI Studio is intentionally low-infrastructure. There is no build system, no package manager, and generation itself has no backend server. The entire generation toolchain runs on three layers: a small multi-page HTML/JS/CSS app (four hand-authored pages sharing one app shell, no bundler), a Markdown-based artifact system, and the Anthropic API. One deliberate exception: `persona-library-server/` (see below) is a small local backend + database for *storing and retrieving* persona packs after they've been run through the pipeline — generation, red-team, and eval logic remain entirely client-side. --- ## App Shell — `index.html`, `pipeline.html`, `library.html`, `docs.html` Four pages (Landing, Pipeline, Persona Library, Docs) sharing a persistent top bar + left nav sidebar. `app-shell.js` renders that nav into each page's `#shell-topbar`/`#shell-sidebar` mount points; `shell.css` holds the design tokens and all component styles used across the four pages. This pair is the one deliberate shared-file exception — every other structural/behavioral decision stays self-contained in that page's own `.html` file, per `context/coding-standards.md`. On `pipeline.html`, the outer nav sidebar collapses to an icon-only rail (`.shell-sidebar.icon-collapsed`) so it doesn't compete with the pipeline's own internal 8-stage sidebar. "Load into Pipeline" from `library.html` hands a persona off to `pipeline.html` via a one-shot `localStorage` key (`orion_library_handoff`) rather than a shared in-page JS state, since the two are now separate page loads. | Concern | Technology | |---|---| | Runtime | Browser — vanilla HTML5, CSS3, ES2022 | | JavaScript | Vanilla JS (no framework, no bundler) | | Styling | CSS custom properties (design tokens); no preprocessor | | Fonts | JetBrains Mono (labels, code, output) · Inter (body copy) — loaded via Google Fonts CDN | | Build step | None — plain `.html`/`.css`/`.js` files, open directly in any modern browser | | State management | In-memory JS object (`pd`) per page — no persistence, except the one-shot library→pipeline handoff above | | API calls | `fetch()` → Anthropic Messages API (`https://api.anthropic.com/v1/messages`) from `pipeline.html`; `fetch()` → `persona-library-server/` from `library.html` and `pipeline.html`'s Save-to-Library modal | | Auth | Anthropic API key from `window.ANTHROPIC_API_KEY`, set either via `pipeline.html`'s own header API key control (pasted key, held in `sessionStorage` for that tab only) or a local `config.local.js` (gitignored, copied from `config.local.js.example`) — the header control takes precedence when both are present | | Clipboard | `navigator.clipboard` API for copy-to-clipboard | | File download | `Blob` + `URL.createObjectURL` for `.md` downloads | | Design standard | Vercel-style dark UI — true black base, stepped surfaces, `#00ff9d` accent | --- ## LLM APIs | Provider | Models used | Purpose | |---|---|---| | **Anthropic** | `claude-sonnet-5` | Persona pack generation, system prompt derivation, red-team, eval pack, judge prompt | | **OpenAI** | `gpt-4o` | Not a provider this tool calls, by design — `gpt-4o` is a Stage 01 Target Model option describing the *delivered persona's* deployment target, distinct from what Orion itself runs on (see `context/features/archive/multi-model-provider-support-feature.md`) | API calls are made directly from the browser (client-side). No backend proxy. The API key comes from `pipeline.html`'s own header API key control or a local, gitignored `config.local.js` (see App Shell table above) — never sent anywhere but directly to Anthropic. **Default generation parameters:** | Parameter | Default | Notes | |---|---|---| | Model | `claude-sonnet-5` | Hardcoded at every call site — not a UI setting. (Stage 01's Target Model dropdown describes the *persona being designed*'s intended deployment model, a separate concept from what Orion itself runs on.) | | Temperature | Not set — no calls send a `temperature` parameter | `claude-sonnet-5` rejects it outright ("deprecated for this model"); there is no API knob for determinism on any call, including the Judge/Eval calls, which instead rely on prompt instruction plus a hard-gate pass/fail computed in code from the resulting scores | | Max tokens | 1024 | Configurable per persona | --- ## Artifact System All pipeline artifacts are plain Markdown files with a structured schema — no database, no CMS. | Artifact type | Format | Versioning | |---|---|---| | Persona Pack | `.md` | `name@MAJOR.MINOR.PATCH.md` | | Eval Pack | `.md` | `name-eval-pack@MAJOR.MINOR.PATCH.md` | | Judge Prompt | `.md` | `judge-name@MAJOR.MINOR.PATCH.md` | | Registry entries | `.md` | Date-stamped filenames | **Schema standard:** ForgeAI PersonaForge draft-07 (custom schema; not JSON Schema — Markdown-native) Every artifact carries a mandatory tag block: ``` `name@version` | eval-status | temp | max_tokens | red-team state | bias facet | eval-pack state ``` --- ## Persona Library Backend — `persona-library-server/` The one backend/database in the repo — added to let a persona pack (and later pipeline-stage output) survive past the browser session as a queryable store, separate from the git-committed Markdown artifacts above. See `context/features/persona-storage-feature.md` for the full spec. | Concern | Technology | |---|---| | Runtime | Node.js ≥22.5 | | HTTP framework | Express | | Database | `node:sqlite` (Node's built-in `DatabaseSync`) — no native dependency, no `better-sqlite3` | | Data file | `persona-library-server/data/personas.db` — local, gitignored | | Start | `npm install && npm start` in `persona-library-server/` — runs on `http://localhost:4100` | | CORS | Wide open (`Access-Control-Allow-Origin: *`) — the pipeline UI is a `file://` page with no fixed origin | **API**: `POST/GET /personas`, `GET /personas/{name}`, `GET /personas/{name}/{version}`, `DELETE /personas/{name}/{version}`. Re-saving an existing `name@version` returns `409` — versions are immutable once stored, matching this repo's semver convention (see Artifact System above). **Relationship to the Markdown artifact system**: saving to the library never reads, writes, or deletes anything under `personas/`, `eval-packs/`, `judge-prompts/`, or `registry/`. It's an additional working/staging index — including drafts that never get promoted — not a replacement for the git-reviewed artifacts. `pipeline.html`'s **💾 Save to Library** action (Stage 02 Persona Pack, System Prompt, and Judge Prompt panels) POSTs to it; `library.html` — a full page reachable from the top-level nav, not an in-pipeline modal — browses/filters/loads/downloads/deletes from it. **Real Stage 06/07 run persistence**: `persona_versions` also carries `eval_results_json`/`eval_axis_scores_json`/`eval_ran_at`/`judge_verdict_json`/`judge_ran_at`, populated whenever a Save to Library happens after a real "Run Eval"/"Run Judge" pass. Loading that version back into the pipeline (from `library.html` or the cross-page handoff) restores those results into the running session, so a completed run can be reviewed again without re-paying for it. See `context/features/archive/eval-run-resilience-feature.md`. --- ## Hosting Two independent deployments, kept deliberately separate rather than combined onto one platform: | Piece | Platform | Cost | |---|---|---| | Static frontend (`index.html`, `pipeline.html`, `library.html`, `docs.html`, `shell.css`, `app-shell.js`, and the Markdown files `docs.html` links to) | Cloudflare Pages | $0 — free tier, works with a private GitHub repo | | `persona-library-server/` (Express + `node:sqlite`) | Fly.io | ~$2–4/mo (smallest machine, scales to zero when idle) — pay-as-you-go, no flat free tier | **Why two platforms instead of one**: Railway was the original plan (one flat $5/mo bill for both pieces combined), but was dropped after Railway's October 21, 2026 security incident, in which an attacker reportedly accessed decrypted customer environment variables. Cloudflare Pages needs no backend secrets at all (pure static hosting), and Fly.io has no equivalent recent incident — splitting the two avoids putting this project's only server-side credentials on a platform with an open, unresolved breach. **Frontend (Cloudflare Pages)**: deploys from `_site/`, built by `npm run build:pages` (`scripts/build-pages-site.js`), which copies only the files the four HTML pages actually reference. This is deliberate, not incidental — a static host publishes whatever lands in its output directory, so pointing Cloudflare at the repo root as-is would make `context/`, `.claude/`, `tests/`, and `persona-library-server/`'s source all publicly fetchable by URL despite this being a private repo. Cloudflare's own GitHub integration rebuilds and redeploys automatically on every push — no GitHub Actions workflow needed for this half. **Backend (Fly.io)**: `persona-library-server/Dockerfile` + `fly.toml` (`node:22-slim`, smallest `shared-cpu-1x`/256MB machine, `min_machines_running = 0` so it scales to zero between requests rather than billing 24/7). `personas.db` lives on a mounted Fly volume (`DATA_DIR` env var, see `persona-library-server/db.js`) so it survives redeploys — without that mount it would live on the container's ephemeral disk and be wiped on every deploy. `.github/workflows/fly-deploy.yml` runs `flyctl deploy` on every push to `main` that touches `persona-library-server/`, gated on a `FLY_API_TOKEN` repository secret (set once, manually, after `fly launch`). **Wiring the two together**: `app-shell.js`'s `PERSONA_LIBRARY_API` resolves to `http://localhost:4100` when the page is opened via `file://` or served from `localhost`/`127.0.0.1` (matching local dev and the `tests/` suite's `static-server.js` + `persona-library-server` split), and to the deployed Fly.io URL otherwise. That URL is a placeholder (`orion-persona-library.fly.dev`) until the real one `fly launch` assigns is substituted in. --- ## Test Suite — `tests/` The second deliberate Node exception in the repo (after `persona-library-server/`) — a committed, re-runnable Playwright E2E suite, added because every prior feature's "verified end-to-end" claim was a throwaway script, written once and never committed, leaving nothing to catch a later feature silently regressing an earlier one. See `context/features/archive/e2e-testing-feature.md`. | Concern | Technology | |---|---| | Runtime | Node.js, Playwright (`@playwright/test`) | | Scope | E2E only, against a real rendered browser page — no unit tests. This repo's functions live inside one `