Guides

Blueprint Versioning

As your product evolves, your blueprint should evolve with it. Blueprint versioning (Agency plan) lets you track how your specification changes over time, maintain clean version history, and generate fresh exports at every stage.

When to create a new version

Create a new blueprint version when:

• Scope changes — Screens added, removed, or significantly redesigned
• Major feature additions — A new user role is introduced, a new flow is added
• Post-launch iteration — V2 development begins with lessons from V1
• Client approval milestones — Freezing a version for client sign-off before development begins

You don't need a new version for minor spec corrections — use the visual logic map editor to update specs inline.

Version naming convention

Recommended naming pattern: v[major].[minor] — [brief description]

Examples:

• v1.0 — Initial MVP spec
• v1.1 — Added admin role and moderation screens
• v2.0 — Mobile redesign

Clear version names help when looking back months later or handing off to a new team member.

What's preserved in each version

Each saved version captures:

• Complete screen inventory at that point in time
• All screen specifications
• Navigation graph
• Database schema
• API contracts
• Auth model
• Design system rules
• Per-screen prompt exports (if generated)

Diffing between versions

The versioning interface shows what changed between any two versions:

• Added screens — New screens introduced
• Removed screens — Screens no longer in scope
• Modified screens — Specs that changed (component additions, state changes, new API calls)
• Schema changes — Tables or fields added or modified
• API changes — New or modified endpoints

Use diffs in developer handoffs to communicate what's changed without requiring a full re-read of the spec.

For agencies: client-facing versioning

If you're using oneStrukt to blueprint client projects, versioning supports a clean approval workflow:

1. Generate v1.0 after your discovery session
2. Share the PRD export with the client for review
3. Collect feedback and update in the visual editor
4. Save v1.1 after revisions
5. Get sign-off on the final version before development begins
6. Lock v1.0-approved as the development reference

This creates an auditable record of what was agreed before development started — protecting both you and the client if scope disputes arise later.

Archiving old versions

Old versions are preserved indefinitely on the Agency plan. You can export any historical version at any time in all available formats (Markdown PRD, JSON, PDF, per-screen prompts). This is useful for:

• Auditing what was originally specified vs. what was built
• Referencing a previous architecture if a new approach isn't working
• Documenting the product's evolution for new team members

Team Workflows with oneStrukt

A oneStrukt blueprint isn't just a document — it's a shared source of truth that keeps every role on the same page from kickoff to launch. Here's how different team members use it.

For product managers

The blueprint replaces the partial spec. Instead of writing scattered tickets, a product manager can:

Before development:

• Use the screen inventory as the basis for your sprint backlog (one ticket per screen)
• Share the navigation map in kickoff to align on scope before a line is written
• Use the Out of Scope section to prevent scope creep conversations before they start

During development:

• Reference screen specs when developers have implementation questions
• Use the blueprint as acceptance criteria — a screen is done when it matches its spec
• Track completion against the screen inventory as a natural progress indicator

During QA:

• Use edge case definitions as your test cases
• Check navigation targets — every button should go where the spec says

For founders

If you're a solo founder working with contractors or an AI builder:

• Send the PRD export before any work begins — it sets professional expectations and reduces back-and-forth
• Use the screen inventory to scope and price work (contractors can estimate per screen)
• Use the per-screen prompts to build alongside contractors — you handle some screens, they handle others
• Use the JSON export if you integrate with any project management tools

For development teams

Lead developer:

• Review the database schema and API contracts before the first sprint — flag any concerns early
• Use the auth model to set up middleware and route protection before building any screens
• Establish shared component conventions using the design system section

Frontend developers:

• Work from per-screen prompts as implementation specs
• Check navigation targets before submitting a screen for review
• Use the edge case section as a QA checklist

Backend developers:

• Implement API endpoints in the order the frontend will need them (follow the navigation order)
• Use API contracts as the interface agreement between frontend and backend — changes to contracts require agreement from both sides

Dividing screens across a team

With multiple developers, you can divide the screen inventory by feature area:

Each developer works from the same blueprint, so shared components, navigation, and data shapes stay consistent — even without constant sync meetings.

Keeping the blueprint up to date

As development progresses, requirements evolve. When they do:

1. Update the blueprint in oneStrukt (Professional/Agency plans)
2. Re-export the relevant sections
3. Distribute the updated spec and note what changed

Treating the blueprint as a living document — rather than a one-time artifact — keeps your team aligned through the full lifecycle of the build.

Sharing Blueprints with Developers

A oneStrukt blueprint gives developers something they rarely receive: a complete, unambiguous specification. Here's how to hand one off effectively.

What developers will find in your blueprint

Before the handoff conversation, understand what your blueprint gives them so you can speak to it confidently:

• Screen inventory — Every screen they need to build, named and numbered
• Screen specs — Exact components, states, actions, and API calls for each screen
• Navigation map — How every screen connects, so they understand the full user journey
• Database schema — Tables, fields, types, and relationships ready to implement
• API contracts — Endpoint definitions with request/response shapes
• Auth model — Authentication method, roles, and permissions
• Design system — Visual rules for consistency across screens

This is more detail than most developers receive from a product team. Set that expectation in your handoff.

Recommended handoff format

Send three things:

1. The PRD (Markdown or PDF) — For reading and reference during development
2. The JSON export — For programmatic use, integration with their tooling, or import into project management tools
3. The visual logic map link (if on Professional/Agency plan) — For exploring the navigation interactively

Include a short note:

"This is a complete system blueprint generated by oneStrukt. It covers every screen, the full navigation graph, database schema, API contracts, and auth model. The PRD is the human-readable version. The JSON has the same data in structured format. Let me know if anything is unclear or if you see gaps — but there should be very few."

What to discuss in the kickoff

Go through the navigation map together. Walk the primary user journey screen by screen. Ask the developer:

• Does the flow make sense?
• Do any screen specs feel underspecified?
• Are there any database relationships that seem wrong?
• Does the auth model match your hosting/backend plan?

A 30-minute walkthrough catches 90% of potential misunderstandings before a line of code is written.

Agreeing on what's in scope

Your blueprint explicitly includes an Out of Scope section. Review this with your developer. Scope creep most often happens when a developer sees something missing from the spec and builds it anyway — with the right intent but unexpected cost.

Reference the Out of Scope section during kickoff: "These are explicitly not in scope for this version. If you see something missing that you think is critical, flag it — but don't build it without discussing it first."

During development

Your blueprint serves as the ongoing reference. When questions come up:

• "How should this work?" → Check the screen spec
• "What does this API return?" → Check the API contracts
• "Who can access this screen?" → Check the auth model and role definitions
• "What happens when there's no data?" → Check the empty state definitions

If the answer isn't in the blueprint, that's a gap to fill together — not a decision to make unilaterally during development.

Tracking completion

Your screen inventory doubles as a build checklist. As screens are completed, mark them off:

• Login screen (SCR-001)
• Register screen (SCR-002)
• Dashboard (SCR-003)
• ...

This gives both you and the developer a clear picture of progress and what remains.

Understanding Your Navigation Map

Your navigation map is one of the most valuable parts of your blueprint. It answers the question that most app builds leave undefined until it's too late: exactly how does a user get from any point A to any point B?

What the navigation map contains

The navigation map is a directed graph. Every node is a screen. Every edge is a navigation action.

For each connection, the map defines:

• Trigger — What action causes the navigation (button tap, form submit, back gesture, auto-redirect)
• Condition — Whether the navigation is conditional (e.g. only if authenticated, only if form is valid)
• Direction — Push, replace, modal, or back navigation

Entry points

Every app has one or more entry points — the screens a user lands on first. Your navigation map explicitly defines:

• Unauthenticated entry — Where does a new user land? (Usually a landing page or login screen)
• Authenticated entry — Where does a returning, logged-in user land? (Usually a dashboard or home feed)
• Deep link entry — If your app supports deep links, which screens can be entered directly?

Understanding entry points matters because they determine what state each downstream screen must handle when reached unexpectedly.

Reading the flow diagram

The visual logic map (Professional and Agency plans) renders your navigation as an interactive diagram. Here's how to read it:

• Solid arrows — Primary navigation flows (the happy path)
• Dashed arrows — Conditional or secondary flows (error recovery, alternate paths)
• Red nodes — Screens that are dead ends (no exit path defined — usually an error)
• Green nodes — Terminal screens (confirmation, success states)

Click any node to open the full screen specification.

Common patterns to look for

Authentication gates

Your map will show which screens are gated behind authentication. Any screen with an incoming edge from a protected area should have an auth check — your blueprint's API contract for that screen will confirm what headers or tokens are required.

Wizard flows

Multi-step forms or onboarding sequences appear as linear chains in the map. Each step should have both a forward path and a back path. If a step only has a forward arrow, that's a flag — users need a way to correct previous steps.

Branching flows

Role-based branching is common: admin users see one path, standard users see another. Your map shows these forks explicitly. When building, check that your auth model and role definitions align with the branching logic in the navigation.

Recovery paths

Error states need exit paths. A screen that shows an error should always have an arrow leading somewhere useful — retry, go back, contact support. If your map shows error state screens with no outgoing edges, add them before building.

Using the map during development

Print or pin the navigation map where you can reference it while building. For each screen you generate:

1. Check the incoming edges — which screens link to this one? Make sure those links will work.
2. Check the outgoing edges — which screens does this one link to? Stub those navigation calls even if the target screen isn't built yet.
3. Check the conditions — are any of the edges conditional? Build that logic into the screen, not as an afterthought.

Building against the map from day one prevents the most common AI builder failure mode: screens that exist but never connect to the rest of the app.

Using oneStrukt with Lovable

Lovable is a rapid app builder that generates full React applications from natural language. It works exceptionally well with oneStrukt's per-screen prompts because the prompts provide exactly the level of specificity Lovable needs to produce accurate, connected screens.

Why blueprints + Lovable work well together

Lovable generates visual UI fast. The challenge is that without structure, screens don't connect logically and data shapes are invented on the spot. Your oneStrukt blueprint solves this by giving Lovable:

• Exact component lists per screen
• Defined navigation between screens
• Consistent data shapes from your schema
• Edge case states to generate (empty, error, loading)

Starting a Lovable project with your blueprint

When creating a new Lovable project, use your PRD overview as the initial prompt:

"Paste your app overview from the PRD. The app has X screens. I'll provide each screen specification one at a time. Start with the authentication flow."

Then paste the per-screen prompt for your login screen and let Lovable generate.

Building screen by screen

Lovable builds best when you feed it one screen at a time, in navigation order. After each screen is generated:

1. Review the output against your screen specification
2. Check that components match what's defined in your blueprint
3. Verify navigation targets are correct
4. Check that empty and error states are included
5. Confirm before moving to the next screen

If something is missing, reference your blueprint spec directly in your correction:

"The spec defines an empty state for this screen: paste empty state spec. Add it."

Handling data connections

Your blueprint's API contracts define the exact shape of data each screen needs. When generating data-connected screens, include the API contract in your prompt:

"Per-screen prompt. This screen calls GET /api/invoices which returns: paste response schema. Wire the component to this data shape."

Lovable will generate components that expect the correct data structure, making it easier to connect to a real backend later.

Design system consistency

Your oneStrukt blueprint includes design system rules. To keep every Lovable-generated screen visually consistent, include the relevant tokens in each prompt:

"Per-screen prompt. Use these design tokens: primary color #hex, font scale your scale, spacing unit your unit."

After your first few screens, Lovable will learn the visual pattern and apply it automatically to subsequent screens.

What to check before moving to the next screen

Use your blueprint as a checklist. Before confirming each screen:

• All components from the spec are present
• Loading state is shown during data fetch
• Empty state is defined and shows correct CTA
• Error state handles the conditions specified in the blueprint
• Navigation buttons/links point to the correct screens
• Data shape matches the API contract in your blueprint

Using oneStrukt with Replit

Replit's integrated environment — combining code editor, runtime, and AI — makes it especially useful for solo builders who want to go from spec to working prototype quickly. Here's how to pair it with your oneStrukt blueprint.

Setting up your Replit project

Create a new Replit and choose your stack. For most web apps, React + Vite or Next.js work well. For backend-only work, use Node.js or the language of your choice.

Before writing any code, add your blueprint to the project:

1. Create a file called BLUEPRINT.md in the root of your Repl
2. Paste your full PRD (Markdown export) into it
3. Replit's AI will index this as project context

Using Replit AI with per-screen prompts

Replit AI works in two modes: inline chat (in the editor) and the AI panel (sidebar). For screen generation, use the AI panel:

1. Open the AI panel
2. Paste your per-screen prompt
3. Add: "Create this as a new file in /src/screens/. Follow the file naming and component conventions already in the project."
4. Review and accept the generated file

Building the data layer first

Your blueprint's database schema and API contracts are the foundation everything else depends on. Before building any screens, generate your data layer:

For a Supabase backend:

"Using the database schema in BLUEPRINT.md, generate the Supabase table creation SQL and the corresponding TypeScript types for each table."

For a local/mock backend:

"Using the API contracts in BLUEPRINT.md, create a mock API using Express with in-memory data. I'll replace this with a real backend later."

Working through screens efficiently

Replit AI maintains context within a session. Build screens in sequence without starting a new conversation:

"Now build the next screen: paste per-screen prompt. Follow the same component and styling conventions as the screens already in /src/screens/."

Replit can see your existing files and will match patterns from screens you've already built.

Using Replit's shell for automation

With your JSON blueprint export, you can automate repetitive scaffolding. In Replit's shell:

# Example: create empty files for all screens
cat BLUEPRINT.json | jq -r '.screens[].name' | while read name; do
  touch "src/screens/${name}.tsx"
done

This creates placeholder files for every screen in your blueprint, which you can then fill in screen by screen.

Deploying from Replit

Once your screens are built and wired together, Replit's built-in deployment lets you publish instantly. Your blueprint's API contracts and auth model give you a checklist of what must be working before you ship:

• All defined API endpoints returning real data
• Auth flows matching the model in your blueprint
• All error states tested (not just happy paths)

Using oneStrukt with ChatGPT

ChatGPT is a flexible AI builder that works well with oneStrukt's per-screen prompt format. This guide covers how to structure your ChatGPT sessions for maximum accuracy and consistency.

Choose the right model

Use GPT-4o for the best results with complex screen specifications. The larger context window handles detailed prompts without losing critical details.

Starting a screen session

Each screen should have its own conversation thread. This keeps context focused and prevents earlier screens from bleeding into later ones.

Session opener:

"I'm building a brief app description. I have a complete system blueprint. I'm going to give you the specification for one screen at a time and ask you to build it in React/Vue/etc.. Here is the overall app context: paste your PRD overview. Are you ready for the first screen spec?"

Then paste the per-screen prompt for your first screen.

Working through the screen specification

oneStrukt's per-screen prompts are dense. After pasting, ask ChatGPT to confirm it has understood the spec before generating code:

"Before generating, summarize what this screen does, what states it has, and what it navigates to."

If the summary is correct, proceed. If it's missing something, correct it before generation.

Handling all states

Your blueprint defines multiple states for each screen: default, loading, empty, and error. Explicitly request all of them:

"Generate the complete component including all four states defined in the spec: default (with data), loading skeleton, empty state (no data yet), and error state. Include state switching logic."

AI tools default to happy-path code. Prompting explicitly for all states ensures you don't have to add them later.

Generating backend code

If you're building your own backend, your blueprint includes complete API contracts. In ChatGPT, you can use these to generate:

• Express/Fastify route handlers
• Django/FastAPI views
• Supabase Edge Functions
• Prisma schema from your database spec

Paste the relevant API contract or database schema section and ask for the implementation in your stack.

Maintaining consistency across sessions

ChatGPT doesn't retain memory between conversations. To stay consistent:

1. Keep a running style guide — After your first screen, ask ChatGPT to summarize the conventions used (naming, component structure, CSS approach). Save this and paste it at the start of each new screen session.
2. Reference your JSON export — Paste relevant sections of your blueprint JSON to give ChatGPT precise data shapes.
3. Use custom instructions — If you're building one app across many sessions, put your app overview and conventions in ChatGPT's custom instructions.

Iterating on output

When the generated code needs refinement, be specific:

• ❌ "This doesn't look right"
• ✅ "The empty state is missing the CTA button defined in the spec. Add a 'Create your first invoice' button that navigates to SCR-004."

Your blueprint gives you the ground truth to reference during iteration, which makes corrections faster and more precise.

Using oneStrukt with Cursor

Cursor is one of the most powerful AI coding tools available — but like all AI builders, it can only be as accurate as the context you give it. This guide shows you how to use your oneStrukt blueprint to get the best possible results from Cursor.

What you need

• A completed oneStrukt blueprint (Professional or Agency plan for per-screen prompts)
• Cursor installed with your project open
• Your project scaffolded with your chosen framework (React, Next.js, Vue, etc.)

Setting up your project context

Before pasting any screen prompts, give Cursor context about your overall project. In Cursor's chat panel, send a single setup message:

"I'm building app name. Here is the system overview: paste your PRD overview section. I'll be asking you to build individual screens one at a time. For each screen, I'll provide a complete specification. Match the component structure and naming conventions I establish in the first screen for all subsequent screens."

This primes Cursor's context so later screens are consistent with earlier ones.

Building screens in the right order

Always build in navigation order — entry points first, downstream screens after.

Recommended sequence:

1. Auth screens (login, register, password reset)
2. App shell and navigation (sidebar, tab bar, header)
3. Primary flow screens (the main user journey, in order)
4. Secondary screens (settings, profile, account)
5. Admin and edge case screens

Using per-screen prompts in Cursor

For each screen, open the relevant file (or create a new one) and use Cursor's inline AI or chat mode:

1. Open Cmd/Ctrl + K (inline) or the chat panel
2. Paste the per-screen prompt from your blueprint export
3. Add one line: "Use framework/component library and match the conventions established in previous screens."
4. Review the output, then confirm or iterate

Getting consistent output across screens

Cursor's context window has limits. As you build more screens, earlier context fades. To maintain consistency:

• Create a BLUEPRINT.md in your project root and paste your full PRD. Cursor will pick this up as codebase context.
• Reference existing components explicitly: "Use the same InvoiceCard component structure as in InvoiceList.tsx."
• Use Cursor's @codebase mentions to pull in relevant existing files before generating new ones.

Handling API calls

Your per-screen prompts include the exact API endpoints each screen consumes. When generating a screen, tell Cursor:

"The API calls for this screen are defined in the spec. Create placeholder service functions for each one using the request/response shapes provided. I'll wire them to the real backend later."

This keeps your UI components decoupled from your API layer during the build phase.

Tips for best results

• One screen per conversation thread — Don't mix screen contexts in a single thread.
• Review before confirming — Always read Cursor's output before accepting it. Check state handling and navigation targets specifically.
• Commit after each screen — Version-control each completed screen so you can roll back if later screens introduce conflicts.
• Use .cursorrules — Add project-wide conventions to a .cursorrules file so Cursor applies them automatically to every generation.