Data Modeling — Defining Data Structures

When to use

• API Design passed Gate 4 validation
• System stores persistent data
• Multiple entities with relationships
• Large Track workflow (2+ day features)

Skip when

• Small Track workflow → skip to Task Breakdown
• No persistent data → skip to Dependency Map
• API Design not validated → complete Gate 4 first

Sequence

Runs before: ring:pre-dev-dependency-map Runs after: ring:pre-dev-api-design

Defines WHAT data exists, HOW entities relate, and WHO owns what data — before database technology selection.

Phase 0: Database Field Naming Strategy (MANDATORY)

Step 1: Check for Gate 4 API standards

If docs/pre-dev/{feature}/api-standards-ref.md exists, auto-detect naming convention.

Step 2: Ask user

If api-standards-ref.md EXISTS: AskUserQuestion: "How should database fields be named?"

• "Convert to snake_case (Recommended)" — API: userId → DB: user_id
• "Keep same as API (camelCase)" — API: userId → DB: userId
• "Different standards — provide DB dictionary"
• "Define manually"

If api-standards-ref.md DOES NOT EXIST: AskUserQuestion: "How should database fields be named?"

• "Use snake_case (Recommended)" — standard for PostgreSQL/MySQL
• "Use camelCase" — standard for MongoDB/document DBs
• "Load from standards document"
• "Define manually"

Step 3: Generate db-standards-ref.md

Option: Convert to snake_case — apply automatic rules:

• userId → user_id, createdAt → created_at, isActive → is_active, phoneNumber → phone_number, userID → user_id

Option: Keep same — copy field names without modification.

Option: Load from doc — WebFetch or read, extract field definitions, save to db-standards-ref.md.

Mandatory Workflow

Entity Template

### Entity: {EntityName}

**Ownership:** {service-name}
**Primary persistence:** Relational | Document | Key-value | Time-series

| Field | Type | Required | Constraints | Notes |
|-------|------|----------|-------------|-------|
| id | uuid | Yes | PK, unique | Auto-generated |
| name | string | Yes | max 255 chars | |
| status | enum | Yes | ACTIVE, INACTIVE, BLOCKED | |
| created_at | timestamp | Yes | UTC | |
| updated_at | timestamp | Yes | UTC | |

**Indexes:** [field combinations worth indexing for query patterns]

**Relationships:**
- has-many: {RelatedEntity} via {foreign_key}
- belongs-to: {ParentEntity} via {foreign_key}

Data Rules

Include

• Entity names and descriptions
• Field names (following naming strategy), types, constraints
• Relationships and cardinality
• Data ownership per entity
• Lifecycle states (ACTIVE, INACTIVE, etc.)
• Data retention rules

Never Include

• Database-specific syntax (PostgreSQL, MongoDB)
• SQL DDL statements (CREATE TABLE)
• ORM annotations (@Column, json:"field")
• Migration scripts
• Query patterns (belong in subtasks)

Topology-Aware Output

Gate 5 Validation Checklist

Gate Result: ✅ PASS → Dependency Map | ⚠️ CONDITIONAL (fix naming/missing entities) | ❌ FAIL (incomplete schema)