VibeMap Logo

2.2 — The data model in plain English

On this page

2.2 — The data model in plain English

If you're going to use the API or the MCP server, you'll see these object shapes everywhere. Here's what each one is, in plain English.

You don't need to memorize this — the API and MCP responses are self-explanatory. But understanding the relationships unlocks a lot.

Projects

A project is one product you're building. It has:

  • A name and a one-paragraph prompt
  • A status (whether spec generation is still running, ready, or has errors)
  • All of the entities below

Most users have 1-3 projects. There's no hard limit on the Pro tier.

Personas

A persona is a type of user your product serves. Each persona has:

  • A name ("Cost-Conscious First-Time Diver")
  • A short bio
  • Goals and pain points
  • A primary motivation

Personas exist so that user stories can be for someone specific. "As a cost-conscious first-time diver, I want …" is much stronger than "As a user, I want …"

Features

A feature is one major capability of your product. "Booking Engine", "Reviews & Ratings", "Dive Site Catalog".

Features are the top-level grouping in the spec. Everything else (user stories, acceptance criteria) lives under a feature.

A feature has:

  • A name and description
  • A kind — usually feature, sometimes bootstrap (system foundation work like auth scaffolding) or infrastructure
  • An approval state
  • A list of user stories underneath it

User stories

A user story answers "who, what, why" for one slice of a feature.

"As a cost-conscious first-time diver, I want to filter dives by price so that I can stay within my budget."

Each user story:

  • Is tied to one persona
  • Belongs to one feature
  • Has zero or more acceptance criteria underneath it

A feature can — and usually does — have multiple user stories. Each user story can have multiple acceptance criteria.

Acceptance criteria (ACs)

Acceptance criteria are the unit of work. This is what your AI agent claims, implements, and submits. Everything in the kanban board is an AC.

An AC is small, atomic, and testable. Think "Filter UI shows price slider with min/max bounds matching the listing prices" — not "build the booking page."

Each AC has:

  • A title and description (the "what")
  • A status: draft, approved, ready, in_progress, in_review, passed, blocked
  • A relationship to a user story (and through that, a feature)
  • Optionally a sprint assignment (after planning)
  • Optionally a list of prerequisites (other ACs it depends on)
  • Optionally a kind — usually criterion, sometimes bootstrap for system foundation criteria

ACs are where the rigor lives. Get these right and your agent will build the right thing.

Pages

A page is one screen or route in your product.

Each page has:

  • A name and URL slug
  • A purpose statement
  • A list of sections (the layout)
  • Auth rules (who can see it)
  • The personas it primarily serves

Schema

The schema is your database structure. VibeMap generates:

  • A list of tables, each with columns and types
  • Relationships between tables (foreign keys, joins)
  • An ER-style diagram you can view on the Schema tab

It's a starting point — your agent (and you) can extend it as the build progresses.

Files

The files outline is a starter folder/file structure for your codebase. It's intentionally light — your agent will fill in actual files. The outline gives the agent (and you) a shared map of where things go.

Sprints (Pro+)

A sprint is a themed group of acceptance criteria, sequenced so that prerequisites land first.

Each sprint has:

  • A number (1, 2, 3, …)
  • A theme ("Auth & Onboarding", "Booking Flow")
  • A goal statement
  • A list of ACs assigned to it
  • A status: planned, active, complete

Only one sprint is "active" at a time. ACs from non-active sprints aren't claimable by your agent — even if they're approved.

How it all hangs together

Project
├── Personas (loose — referenced by user stories)
├── Features
│   └── User Stories  (each tied to a Persona)
│       └── Acceptance Criteria  (the claimable unit)
│             ├── Prerequisites (other ACs)
│             └── Sprint assignment (Pro+)
├── Pages  (referenced by Features and Personas)
├── Schema (tables + relationships)
└── Files  (folder outline)

If you ever feel lost in the UI, come back to this diagram. Every screen in VibeMap is a view onto one of these layers.

Where to go next