What to put in your architecture.md when building in Dreamflow

When people talk about AI coding tools, they usually start with speed. Rapid prototyping, vibe coding, spinning up projects in a flash. And sure, speed is part of it. But it’s not the whole story, and it’s not the part that matters once you’re building something meant to last.

An AI agent is just another tool in your kit. Like any professional tool, it only gets powerful when you know how to direct it. The teams who get the most out of Dreamflow don’t ask the agent to “build the whole app.” They use it to establish real, production-grade architectural patterns and then iterate from there.

That’s where prompting like an architect comes in.

Your architecture.md gives the agent context, constraints, and structure—so the code it generates behaves like part of an actual architecture, not a one-off output.

A good architecture.md doesn’t need to be long. It needs to be clear. It’s the blueprint that keeps your prompts grounded as the app grows.

Here’s what to put in it.

1. Start by telling the agent to record your decisions

Before generating any code, take ownership of the architecture.

You can explicitly instruct the agent to capture your structural choices so they become the foundation of every future change.

Prompt examples:

Add these architectural decisions to architecture.md and use them as the source of truth for future steps.

or:

Build a habit tracker using layered architecture and Provider for state management. 

Create the files and folders but do not write any implementation yet. Add these decisions to architecture.md.

‍

This mirrors what experienced teams do in Dreamflow: define the system upfront so the agent always has something consistent to reference.

2. The core objects

List the primary data models your app relies on. This is the first place the agent builds its mental model of your system.

Good architectural.md objects describe:

• the data shape
• the fields
• relationships
• what's owned vs. referenced

Example:

Habit:

  id: string

  name: string

  frequency: enum(daily, weekly)

  createdAt: datetime

This clarifies the domain logic the agent needs to maintain across screens, flows, and backend integration.

3. The essential flows

Flows describe behavior, not UI.

They’re the backbone of how your app works, and they prevent the agent from improvising logic that doesn’t match your intent.

Examples:

User creates a habit → app saves it → user returns to list.

User scans a product → app fetches details → user saves to favorites.

This teaches the agent what should happen, not what the UI should look like.

4. Architectural decisions that matter

If you want the agent to build like an architect, it needs to know what decisions you’ve already made.

Capture things like:

• state management choice (provider, riverpod)
• routing pattern
• where state originates
• what must remain pure or side-effect-free
• constraints the agent should not break

This is where the tooling in the transcript comes in: layered architecture, feature-based architecture, data modeling choices, serialization, localization—decisions that shape the whole codebase.

5. Data sources and backend expectations

Even before connecting Firebase or Supabase, establish how data is meant to behave. This keeps the agent consistent and prevents churn when backend logic is generated later.

Define:

• which API or database the app will use
• how collections/tables are structured
• auth requirements
• security assumptions
• patterns for reading/writing data
  
  

Example:

Backend: Supabase  

Tables:

  habits (id, userId, name, frequency)  

  entries (id, habitId, date, isComplete)

‍

Rules: users may only access their own habits and entries.

‍

This prepares the agent for real data integration and reduces refactoring later.

6. The next 3–5 tasks

The teams that move fastest in Dreamflow work in small, constrained steps.

Adding a short task list at the bottom of architecture.md gives both you and the agent a focused starting point every time you open the project.

Examples:

• implement CRUD for Habit
• add Entry logging flow
• wire up Firebase Auth
• add offline caching
• refine streak calculation

You build one piece, review it, then move to the next.

Case study: Flywheel Studios

Flywheel is one of the fastest teams building with Dreamflow. Their workflow is simple but disciplined:

1) They plan before they prompt

Every build starts with a concept, a short product plan, and a clear architecture.md.

The agent always works from that source of truth—not from a detached, one-off prompt.

2) They build in tight steps

They never ask for the entire app.

They ask for:

• one screen
• one flow
• one backend operation
• one refinement pass

This keeps quality high and iteration friction low.

3) They connect their backend early

Firebase or Supabase gets wired up early so the app is testable and shareable while it’s being built.

4) They use all three Dreamflow surfaces

Agent for structure → visual builder for refinement → code editor for precision. Everything stays in sync because Flutter is the source of truth.

If you want to see Flywheel’s full workflow, watch their build session.

Why this matters

Your architecture.md becomes the north star for your conversation with the agent. It shifts your role from “describe a widget” to “define the system.” The agent builds the files, the layers, the flows, the logic. You steer the ship.

And when your prompts reference a clear plan, Dreamflow stops acting like a tool and starts acting like a teammate who understands the system you’re trying to build.

If you’re ready to take the next step, connect your backend and turn the blueprint into a working product.

CTA: Connect your backend

FAQ 

What is architecture.md?

architecture.md is the blueprint file Dreamflow uses to understand how your app is supposed to work. It’s where you define the system; not the UI, not individual screens, but the underlying structure the agent should follow as it generates code.

It usually includes:

• the purpose of the app
• the core data models
• the main user flows
• your architectural decisions (state management, routing, data layer patterns)
• backend expectations
• the next small set of tasks

Do I update architecture.md as I build?

Yes. Treat architecture.md as a living document.

Anytime you make a meaningful architectural decision, such as adding a new data model, introducing a state management pattern, or defining routing behavior, capture it in the document. The clearer the blueprint, the better the agent performs.

‍