Pointer page

Engineering Reference

Real technical reference material for how FLME's pipeline actually works, one subsystem at a time — built as each subsystem's own documentation gets surveyed and mirrored here, not all at once. This page defers to each source repo's own docs for exact commands, flags, and file formats — those stay canonical; what's below is a readable map over them, not a replacement.

One section built so far: UI Pipeline. Requirements Framework, Backend Architecture & Codegen, Privacy & Compliance, and Tooling are still on the Roadmap.

UI Pipeline: markup to deployment

Sourced directly from ux-template/docs/From_Markup_To_Deployment.md (Wren's own doc, current as of its own last edit — check there before relying on exact syntax). Three stages, one real thread of examples throughout: a client requirements folder called PAWS, built into an instance called pawsdemo, deployed as pawstop's web-ux service.

TL;DR

1. Design — design-ux-from-reqdoc-drafts turns a client's requirements markup into a confirmed ux-designs/<CLIENTTOKEN>/<token>.ux-design.json (plus a .ux-journey.json if it needs a real interactive flow). A human confirms what markup can't answer on its own; nothing downstream runs without this.
2. Build & test locally — build-ux-from-reqdoc-drafts instantiates that design into instances/<token>/ inside ux-template, run via npm run dev. Any hand-built journey/auth glue gets written and proven here, against a real backend, before it ever leaves this repo.
3. Deploy — package-ux-deployment packages the confirmed design as a real Docker service inside the paired backend's own docker-compose.yml, on its reserved UX port band. A hand-built journey layer still has to be ported across by hand today — not yet automated.

Stage 1 Design a UX from markup

Skill: design-ux-from-reqdoc-drafts (with bind-reqdoc-drafts-live-api as its live-API sub-step).

npm run studio:derive -- /Users/jakeyara/FLME/dktest/reqdoc-drafts PAWS pawstop-meadow

Seeds a draft design from the markup's own structural signals (screen roles, embedding, entry points), then a human confirms the handful of things markup genuinely can't answer — screen role for anything ambiguous, home/entry point, index composition, look-and-feel default, and whether the seeded screen set can actually deliver the package's own stated purpose end-to-end. This session also settles, up front, mock data (the default) vs. a real live API — live mode hands off to bind-reqdoc-drafts-live-api to fetch a schema snapshot and resolve real field bindings before anything else runs.

If the plain generated screens can't deliver the package's real purpose (the common case for anything beyond simple CRUD — e.g. PAWS's own Direct Purchase needs a real discover→select→confirm→commit flow no generated master-detail page offers), a guided journey interview runs: a genuinely different, deeper co-design session producing a separate .ux-journey.json — a real, hand-designed interactive flow, wired live against the real backend when the design is live-API.

Real example: ux-designs/PAWS/paws.ux-design.json (plain, mock-data) and ux-designs/PAWS/pawsdemo.ux-design.json + pawsdemo.ux-journey.json (a separate, later, live-API-bound design plus a real 12-stage journey against the real Direct Purchase workflow).

Stage 2 Build and test it locally, in `ux-template`

Skill: build-ux-from-reqdoc-drafts.

npx ts-node --project tsconfig.generator.json generator/cli-instantiate.ts pawsdemo
cd instances/pawsdemo && npm run dev

Writes the real generated screens — either into the single shared app, or, for an independent variant sharing a client token with an already-live build, an isolated instances/<instanceToken>/ with its own next dev process and port. Always pass --port explicitly if this instance needs to reach a real backend — the auto-assigned port has no relationship to any real deployment's own reserved band.

This is also where a journey artifact actually becomes runnable. The generated pipeline never wires one in on its own — a real journey needs four small hand-authored files (an AuthProvider-wrapped root layout, a RequireAuth gate, a real sign-in page, a callback re-export) plus a thin per-client adapter turning the artifact's apiCall-tagged edges into real backend calls. None of this is generated; it's written once per instance and survives future regenerates precisely because it lives outside the directories the emitter owns.

Iterate here until it's right — this is the fast loop, no Docker, no target repo involved yet.

Real example: instances/pawsdemo, live at http://localhost:13041 (Pawstop's own reserved 13040–13049 band, slot 41 — 13040 itself is pawstop's own persistent deployed service, see Stage 3).

Stage 3 Deploy it into `flme-deployments`

Skill: package-ux-deployment.

npx ts-node --project tsconfig.generator.json generator/cli-package-deploy.ts \
  PAWS /Users/jakeyara/FLME/flme-deployments/pawstop --service-name web-ux

One command: gates on the confirmed/current design, scaffolds a standalone Next.js package into the target's apps/<service-name>/, emits the client's real screens rooted at / (not nested — this is what makes it look like a real standalone production app), and attaches it to the target's own docker-compose.yml as a real service on the next free slot of its reserved UX port band, reading that band out of the target file itself rather than assuming literal values. Idempotent: re-run against an already-attached deployment and it refuses cleanly.

Real, current limitation: this command only ports the plain generated screens. A client with a real journey (Stage 2's own hand-built layer) is not carried across automatically — that has to be hand-ported the same way Stage 2 built it in the first place. See ux-template/docs/Running_A_Packaged_Deployment.md's "The journey layer" section for the real worked example and its own load-bearing gotcha: those hand-edits don't survive a re-run of this command.

Real example: flme-deployments/pawstop/apps/web-ux, live at http://localhost:13040 — currently running pawsdemo's design, the real first live-API instance this project has.

The thread, end to end

dktest/reqdoc-drafts/Clients/Pawstop Package-PAWS/   (markup)
        │  design-ux-from-reqdoc-drafts (+ journey interview)
        ▼
ux-designs/PAWS/pawsdemo.ux-design.json + pawsdemo.ux-journey.json   (Stage 1)
        │  build-ux-from-reqdoc-drafts + hand-wired auth/journey glue
        ▼
instances/pawsdemo/  →  http://localhost:13041   (Stage 2, local, ux-template)
        │  package-ux-deployment + hand-ported journey layer
        ▼
flme-deployments/pawstop/apps/web-ux  →  http://localhost:13040   (Stage 3, deployed)

For day-2 operation once a service is attached — starting the stack, rebuilding after a change, logging in, troubleshooting — see ux-template/docs/Running_A_Packaged_Deployment.md (not mirrored here; day-2 ops change too often to keep a wiki copy in sync).

Built 2026-09-06 by Sage, mirroring ux-template/docs/From_Markup_To_Deployment.md (Wren's own doc) into the wiki's Engineering Reference, at Jake's direct instruction. First real section of the Engineering Reference the Start Here roadmap has flagged since 2026-09-04; the other four (Requirements Framework, Backend Architecture & Codegen, Privacy & Compliance, Tooling) remain not built. Content is a close mirror of the source doc's own words, reformatted for the wiki rather than rewritten from scratch, so it doesn't drift from what Wren actually wrote — check the source file directly before citing exact commands or paths. Not committed.

UI Pipeline: markup to deployment

Stage 1 Design a UX from markup

Stage 2 Build and test it locally, in ux-template

Stage 3 Deploy it into flme-deployments

The thread, end to end

Stage 2 Build and test it locally, in `ux-template`

Stage 3 Deploy it into `flme-deployments`