On this page
What is it?
The Database Design Document defines the structure of the information a product needs to store and maintain. It describes entities, attributes, relationships, constraints, and other data decisions required to support the documented product behavior.
FSD
What
BRD
Rules
UFD
Behavior
DSD
Experience
DDD
Data
Why do we need it?
Features and user flows describe what the product does, but they do not fully define what information must exist behind those behaviors.
Without DDD
With DDD
The goal is to remove ambiguity around the information the system needs to persist. The problem is undocumented product-level data decisions, not that engineers cannot design databases.
When do we create it?
The DDD is created once the product functionality, business rules, user flows, and important interface requirements provide enough context to identify the information the system needs to store.
This is an information relationship, not a rigid waterfall. Data modeling can expose missing product rules or behavioral decisions that need clarification.
Who benefits from it?
Product
Uses it to understand what product information must persist.
Design
Uses it to understand which data and states need to be represented in the experience.
Engineering
Uses it as the explicit source for data structures and relationships.
AI agent
Uses it to implement data models without inventing undocumented structures.
What does it contain?
These are the fields a data specification can define.
- 01
Entities
The major objects or records the system needs to store.
- 02
Attributes
The properties or fields associated with each entity.
- 03
Relationships
How entities relate to one another.
- 04
Identifiers
How records are uniquely identified.
- 05
Data Types
The type of information each attribute represents.
- 06
Constraints
Data-level constraints that must be preserved.
- 07
Required / Optional Fields
Which attributes must exist and which may be absent.
- 08
Defaults
Defined default values where applicable.
- 09
Lifecycle
How data is created, updated, archived, or otherwise changes over its lifecycle when relevant.
- 10
Indexing Requirements
Data access requirements that should be explicitly documented when they affect the design.
- 11
Audit Information
Required creation, update, ownership, or other audit data where applicable.
- 12
Data Integrity
Relationships and constraints required to keep stored data consistent.
What does it NOT contain?
- Product vision
- Feature scope
- Complete business rules
- User journeys
- UI layouts
- UI interaction design
- API endpoints
- Request / response contracts
- Application architecture
- Frontend implementation
- Backend application logic
- Deployment configuration
BRD
What rules apply?
UFD
What behavior occurs?
DSD
How is the experience represented?
DDD
What data must exist?
ASD
How is that data communicated?
TAD
How is the system structured?
What does a data specification look like?
Data specification
- Entity ID
- ENTITY-001
- Entity name
- Project
Purpose
Represents a project created within the product.
Identity
Project ID
Unique identifier for the project record.
Core attributes
Name
The project name.
Organization ID
Identifies the organization associated with the project.
Created at
Records when the project was created.
Updated at
Records when the project was last updated.
Relationships
Organization
A project belongs to an organization.
Lifecycle
A project is created when the project creation flow completes successfully.
This is a methodology example, not a complete database schema — exact SQL, data types, and database engine syntax are not defined here.
Data design elements
- 01
Entity
A major object or record represented in the system.
- 02
Attribute
A property belonging to an entity.
- 03
Identifier
A value used to uniquely identify a record.
- 04
Relationship
A defined connection between entities.
- 05
Data Type
The type of value an attribute stores.
- 06
Constraint
A data-level condition that must be preserved.
- 07
Lifecycle
How data changes over time.
- 08
Index
A documented requirement for efficient access when relevant to the data design.
How does AI use it?
The DDD gives the AI agent an explicit data model. It tells the agent which entities exist, what information they contain, how they relate, and which data-level constraints must be preserved.
AI understands
- What entities exist
- What attributes they contain
- Which fields identify records
- How entities relate
- Which fields are required
- Which constraints must be preserved
- What lifecycle considerations exist
The DDD reduces the need for the AI agent to invent database structures from feature descriptions alone.
Without DDD
With DDD
AI should not silently invent important data relationships. If required data decisions are missing, the implementation should surface a specification gap.
Specification gap
Feature
Create Project
The documentation requires projects to belong to an organization, but the relationship between Project and Organization has not been defined.
Implementation paused.
Decision required
Define the relationship before implementation.
How does it connect to other documents?
FSD
Create Project
“What capability exists?”
BRD
Project creation rules
“What conditions apply?”
UFD
Create Project flow
“How does the behavior progress?”
DSD
Create Project interface
“How should the experience be represented?”
DDD
Project data
“What information must be stored?”
ASD
Project communication
“How is that information communicated?”
TAD
Technical structure
“How is the system structured?”
The DDD translates product behavior into explicit data requirements that engineering can implement.
Feature
FEAT-004
Rule
RULE-001
Flow
FLOW-001
Screen
SCREEN-009
Entity
ENTITY-001
Example
Feature concept
Create a Project
DDD perspective
The system stores the project information and its relationship to the relevant organization.
PRD
Why
Users need a way to organize their work into projects.
FSD
What
Users can create a project.
BRD
Rules
Project creation follows defined business rules.
UFD
Behavior
The user moves through the project creation journey and reaches a defined outcome.
DSD
Experience
The interface represents the journey through defined screens, states, interactions, responsive behavior, and feedback.
DDD
Data
The system stores the project information and its relationship to the relevant organization.
ASD
Communication
How the client and server exchange project information.
TAD
Structure
How the capability is technically structured.
DR
Order
When it should be implemented.
AI Instructions
Implementation
How the agent should implement the task.
DDD Template
ddd-template.md
# Database Design Document
## 01. Data Model Overview
## 02. Entity Specification
### Entity ID
### Entity Name
### Purpose
### Identifier
### Attributes
### Required / Optional
### Data Types
### Defaults
### Constraints
### Relationships
### Lifecycle
### Audit Information
### Indexing Requirements
---
## 03. Relationship Specification
### Relationship ID
### Related Entities
### Relationship Type
### Purpose
### Constraints
### Lifecycle Considerations
---
## 04. Data Integrity
## 05. Open Data Decisions
Common mistakes
- Designing tables without first understanding the product behavior.
- Duplicating business rules inside the data model.
- Leaving important relationships implicit.
- Failing to define identifiers.
- Not distinguishing required and optional data.
- Leaving important data constraints undocumented.
- Creating fields because they "might be useful later" without a documented need.
- Mixing API contracts into the database design.
- Mixing application architecture into the database design.
- Letting AI invent entities or relationships that were never specified.
- Treating the database schema as the entire technical architecture.