FOSMVVM Fluent DataModel Generator

Generate Fluent DataModels for server-side persistence following FOSMVVM architecture.

Dependency: This skill uses fosmvvm-fields-generator for the Fields layer (protocol, messages, YAML). Run that skill first for form-backed models.

Scope Guard

This skill is specifically for Fluent persistence layer (typically in Vapor server apps).

STOP and ask the user if:

• - The project doesn't use Fluent
• The target is iOS-only with CoreData, SwiftData, or Realm
• The user mentions a non-Fluent ORM or persistence layer
• You're unsure whether Fluent is the persistence layer

Check for Fluent indicators:

• - Package.swift imports fluent, fluent-postgres-driver, fluent-sqlite-driver, etc.
• Existing models use @ID, @Field, @Parent, @Children, @Siblings property wrappers
• A Migrations/ directory exists with Fluent migration patterns
• Imports include FluentKit or INLINECODE11

If Fluent isn't present, inform the user: "This skill generates Fluent DataModels for server-side persistence. Your project doesn't appear to use Fluent. How would you like to proceed?"

---

When to Use This Skill

• - User asks to create a new model/entity/table
• User wants to add a database-backed type (Users, Ideas, Documents, etc.)
• User mentions needing CRUD operations for a new concept
• Creating the persistence layer for a new entity

Architecture Context

In FOSMVVM, the Model is the center - the source of truth that reads and writes flow through.

See FOSMVVMArchitecture.md | OpenClaw reference for full context.

DataModel in the Architecture

CODEBLOCK0

Fields vs DataModels

Fields protocol = Form input (user-editable subset)

• - What users type into forms
• Validation, labels, placeholders
• NO relationships, NO system-assigned fields

DataModel = Complete entity (Fluent implementation)

• - All fields including system-assigned (createdBy, timestamps)
• All relationships (@Parent, @Siblings, @Children)
• Fluent property wrappers, migrations, seeds

Not all entities need Fields:

• - Session: system auth, no user form → DataModel-only
• Audit records: system-generated → DataModel-only
• Junction tables: pure storage → DataModel-only

---

File Structure

Each form-backed model requires files across multiple targets:

CODEBLOCK1

---

How to Use This Skill

Invocation:
/fosmvvm-fluent-datamodel-generator

Prerequisites:

• - Model structure understood from conversation context
• Fields protocol exists (if form-backed model) via fosmvvm-fields-generator
• Relationships and system-assigned fields identified
• Fluent confirmed as the persistence layer

Workflow integration:
This skill is used for server-side persistence with Fluent. For form-backed models, run fosmvvm-fields-generator first to create the Fields protocol. The skill references conversation context automatically—no file paths or Q&A needed.

Pattern Implementation

This skill references conversation context to determine DataModel structure:

Model Type Detection

From conversation context, the skill identifies:

• - Entity purpose (user data, system records, audit logs, junction table)
• User input involvement (form-backed vs system-generated)
• Fields protocol requirement (if user edits this data)

Relationship Analysis

From requirements already in context:

• - One-to-many relationships (@Parent in DataModel, not in Fields)
• Many-to-many relationships (Junction table + @Siblings, NOT UUID arrays)
• Relationship naming (self-documenting names, not vague references)

Field Classification

Based on data source:

• - User-editable fields (from Fields protocol)
• System-assigned fields (createdBy, timestamps, status - DataModel only)
• Computed relationships (@Parent, @Children, @Siblings)

File Generation Order

If form-backed model (Fields protocol exists):

1. 1. Fields layer already created via fosmvvm-fields-generator
2. DataModel implementation referencing Fields
3. Schema migration
4. Seed data migration
5. Tests
6. Migration registration

If system-only model (no Fields):

1. 1. DataModel struct
2. Schema migration
3. Seed data migration (if needed)
4. Tests
5. Migration registration

Design Validation

Before generating, the skill validates:

1. 1. Form requirement - System-generated entities skip Fields
2. Relationship patterns - Junction tables for many-to-many, @Parent for foreign keys
3. Naming clarity - Relationships have self-documenting names
4. Field separation - User fields in protocol, system fields in DataModel only

Context Sources

Skill references information from:

• - Prior conversation: Model requirements, relationships discussed
• Fields protocol: If Claude has read Fields protocol into context or just created it
• Database schema: From codebase analysis of existing models
• Migration patterns: From existing migrations in project

---

File Templates

See reference.md for complete file templates with all patterns.

---

Key Patterns

Fluent DataModel

CODEBLOCK2

Relationships (Associated Types Pattern)

PRINCIPLE: Existential types (any Protocol) are a code smell. Always ask "Is there any other way?" before using them.

For required relationships, use associated types in the protocol:

CODEBLOCK3

In the Fluent model, @Parent directly satisfies the protocol:

CODEBLOCK4

In schema: INLINECODE14

When to use each pattern:

• - Associated type (associatedtype User: UserFields): Required relationships
• Optional associated type: Not supported - use ModelIdType? for optional FKs
• Plain ModelIdType: Optional FKs, external system references

Migrations

• - Schema migration named: INLINECODE18
• Seed migration named: INLINECODE19
• Seed is environment-aware (debug, test, release)
• Seed is idempotent: INLINECODE20

Raw SQL in Migrations (PostgreSQL Features)

For PostgreSQL-specific features (tsvector, LTREE, etc.), use SQLKit:

CODEBLOCK5

Key points:

• - Import SQLKit (not just Fluent)
• Cast database: INLINECODE23
• Use SQLQueryString with \(unsafeRaw:) for identifiers
• These columns are database-only (not in protocol or Fluent model)

Tests

• - Use @Suite annotation with descriptive name
• Conform to INLINECODE27
• Test all form fields
• Test validation with INLINECODE28
• Create private test struct implementing the Fields protocol

Test structs with associated types:

CODEBLOCK6

---

Naming Conventions

Concept	Convention	Example
Model class	PascalCase singular	INLINECODE29, INLINECODE30
Table name

snake_case plural | users, ideas |
| Field keys | snake_case | created_at, user_id |
| Enum cases | camelCase | searchLanguage, inProgress |
| Enum raw values | snake_case | "search_language", "in_progress" |
| Protocol | {Model}Fields | UserFields, IdeaFields |
| Messages struct | {Model}FieldsMessages | UserFieldsMessages |

Common Field Types

Swift Type	Fluent Type	Database
INLINECODE44	INLINECODE45	INLINECODE46
INLINECODE47

.int | INTEGER | | Bool | .bool | BOOLEAN | | Date | .datetime | TIMESTAMPTZ | | UUID | .uuid | UUID | | [UUID] | .array(of: .uuid) | UUID[] | | Custom Enum | .string | VARCHAR (stored as raw value) | | JSONB | .json | JSONB |

---

See Also

• - FOSMVVMArchitecture.md - Full FOSMVVM architecture
• fosmvvm-fields-generator - For form validation (Fields protocols)
• fosmvvm-viewmodel-generator - For ViewModels that project from DataModels
• reference.md - Complete file templates

---

Version History

Version	Date	Changes
1.0	2025-12-23	Initial skill based on SystemConfig pattern
1.1

2025-12-23 | Added relationship patterns (@Parent), initialization order, imports list | | 1.2 | 2025-12-23 | Associated types for relationships (not existentials), raw SQL patterns, test struct patterns | | 1.3 | 2025-12-24 | Factored out Fields layer to fields-generator skill | | 2.0 | 2025-12-26 | Renamed to fosmvvm-fluent-datamodel-generator, added Scope Guard, generalized from Kairos-specific to FOSMVVM patterns, added architecture context | | 2.1 | 2026-01-24 | Update to context-aware approach (remove file-parsing/Q&A). Skill references conversation context instead of asking questions or accepting file paths. |