From idea to running app: the fromSpec workflow

The best way to understand fromSpec is to follow one app through the whole pipeline. The stages are fixed (chat, spec, architecture, preview, code, then ship), and each one produces a concrete artifact you can inspect before the next begins. We'll use a running example: an internal time-off tool, Tempo, where employees request leave and managers approve it.

Stage 0: describe it

You start in conversation. You tell fromSpec what you want in plain English:

"Build an internal tool where employees request time off and managers approve it."

This isn't the generation step. It's requirement-gathering. The model asks clarifying questions and structures what you say into candidate entities, use cases, and flows. The output of this stage isn't code or even a finished spec. It's a structured first draft you're about to take control of. Nothing is committed yet.

Stage 1: the spec

This is the center of gravity. fromSpec turns the conversation into a structured specification, spec.json, containing:

• Entities and fields. Employee, LeaveRequest, Approval, Balance, each with typed fields.
• Use cases. "Request time off," "Approve or decline requests," "Track leave balances."
• Flows. The screens and navigation those use cases imply.
• Branding. Name, palette, typography.

Everything here is AI-suggested and human-edited. You rename an entity, add a field, drop a use case, adjust a flow. This is where you do your thinking, because it's the cheapest place to be wrong: editing a spec costs seconds, editing generated code costs hours.

When it's right, you approve it. Approval matters: the spec moves from a draft you're shaping to a locked version that becomes the single input to everything downstream. The spec is versioned, so you keep a real history of how the product was defined, not a chat log. Nothing is derived from the spec until you've signed off on it.

Stage 2: architecture

With the spec locked, fromSpec derives the architecture from it: the data model, entity relationships, and the API surface. For Tempo that means tables and relations for employees, leave requests, approvals, and balances, the endpoints that serve them, and the ER diagram that ties them together. You can inspect all of it (the models, the routes, the relationships) in-app before any application code is written.

Doing architecture before the preview is deliberate. The data model and API contracts are the skeleton. Deriving them first means the preview you're about to see is built on a real structure, not arbitrary UI. You're reviewing the how while it's still cheap to change.

Stage 3: preview

Now fromSpec generates an interactive preview from the locked spec and architecture: a working HTML prototype with real screens, navigation, and forms. You don't read a description of the app, you click through it. The request form, the approvals queue, the balance view, the team calendar, they're all there, wired to the flows you defined.

Because the preview is generated from the same entities and routes the code will use, it's a faithful proxy for the real thing rather than a throwaway mockup. This is the second hard checkpoint: you interact with the prototype, confirm the experience is what you want, and approve it. Only then does code generation run. If the preview is wrong, you go back and adjust the spec, long before any application code exists.

Stage 4: code

With an approved spec, architecture, and preview, fromSpec generates the project in your chosen stack: FastAPI, React (Vite), and PostgreSQL, or Next.js. You get:

• Backend. Data models and API routes derived from the architecture.
• Frontend. Pages and components for each flow.
• Capability modules. Auth, payments, and email wired in where your spec called for them, rather than stubbed.
• Docs and ops. Architecture, ER, and API references alongside the code, plus Docker and CI/CD scaffolding.

The code is a compiled artifact of the spec, not an independent thing that happens to resemble it. Every model traces to an entity, every route to a flow, every screen to a use case you approved.

Ship it

From here you're in normal-codebase territory. Run it locally with docker compose up. Push the generated project straight to your own GitHub repo, personal or org. Deploy it on your own infrastructure or a host of your choice. There's no runtime dependency on fromSpec: the app is yours, it runs on your terms, and it keeps running whether or not you keep using the tool.

Iterating

Products change, and the workflow is built for that. You don't re-prompt and hope. You go back to the spec, make the change (add a Holiday entity, a half-day-request flow, a capability), and regenerate from the updated, re-approved spec. Because the spec is versioned, every iteration has a clear before-and-after at the level of what the product is, not a tangle of code diffs. The same discipline that got you the first version keeps the second one honest.

What's fixed, and what you control

Fixed: the sequence. Spec always precedes architecture, architecture always precedes preview, preview always precedes code, and the two approval points (spec and preview) always gate what follows. You can't skip ahead to code from a half-formed idea, by design. That discipline is the feature. It's what keeps generation scoped and reviewable.

Yours: almost everything else. You shape the spec (entities, fields, use cases, flows, branding) and nothing is generated from it until you say so. You choose the stack (FastAPI and React, or Next.js) and which capability modules (auth, payments, email) are wired in. You choose the provider behind each step. And once the code exists, it's an ordinary project: you edit it, extend it, and run it like any other codebase.

So the pipeline is strict about order and loose about content. The structure is what the model can't wander off of. The content is entirely yours to direct. That balance, a fixed process around fully editable artifacts, is what makes the output both predictable and actually yours.

The shape of the whole thing

Step back and the pattern is simple: lock what (spec), derive how (architecture), see it (preview), build it (code), own it (ship). Each stage narrows the space the next one works in, and each transition that could go wrong is gated by a human looking at a concrete artifact. There's no twenty-minute autonomous run that hands you a surprise, and no opaque diff to reverse-engineer. There's a spec you wrote, an architecture you read, a preview you clicked through, and a codebase that matches all three.

chat          describe it
spec       ✓  you approve
architecture  data model · API
preview    ✓  you approve
code          your stack
ship          you own it

That's the entire pitch, made literal: you don't prompt your way to an app and hope. You spec it, you see it, you ship it.