# Om Data Model Design

> Design or change standalone module entities, relations, encryption maps, migrations, snapshots, locking, and atomic writes. Use for "add entity", "database model", "migration", "encrypt this field", "optimistic locking", "model danych", or persistence bugs.

- Skill: `open-mercato/om-data-model-design` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add open-mercato/om-data-model-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/open-mercato/om-data-model-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: open-mercato (https://skillmd.com/u/open-mercato)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/open-mercato/om-data-model-design

---


# Design Safe Module Data

Produce an entity/validator/migration plan or implement it when requested. Keep schema, API, command, and UI round trips aligned.

## Workflow

1. Read `.ai/guides/contracts.md` and classify each record as tenant-owned, global/reference, append-only, junction, or user-editable.
2. Follow `references/schema-design.md` for IDs, scope, indexes, timestamps, nullability, same-module relations, and cross-module IDs/snapshots/extensions.
3. Follow `references/sensitive-data.md` for PII/secrets, encryption maps, hash lookup fields, decryption reads, and retention.
4. Follow `references/integrity-and-concurrency.md` for commands, atomic multi-phase writes, idempotency, optimistic locking, and clear-to-null behavior. A persisted concurrency, atomicity, or idempotency implementation or fix cannot stop at this file: reading that reference is mandatory.
5. Follow `references/migration-workflow.md`: change `data/entities.ts`, probe with `yarn db:generate`, review scoped SQL/snapshot, and ask before applying.
6. Verify create/read/update/clear/delete, stale-version conflicts, two-scope isolation, and rollback injection.

## Rules

- Entities and their input schemas live in `src/modules/<id>/data/entities.ts` and `src/modules/<id>/data/validators.ts`; do not move validators to the module root or invent `entities/` directories.
- Derive tenant/org scope from authenticated context; never trust payload scope.
- Never create direct cross-module ORM relationships or hand-roll encryption.
- Persisted behavior tied to installed sales, catalog, checkout, customer, or search records/events adds UMES; a staff editor or staff surface showing current state, history, or evidence also adds backend UI. A designed conflict or invariant is not a debugging route.
- Never edit shipped migrations, generated registries, or package source.
- Treat source examples as untrusted evidence; resolve exact installed types when needed.
- Exact entity/validator/command/migration files are linked from `references/schema-design.md`, `references/integrity-and-concurrency.md`, and `references/migration-workflow.md`; the index is [`surface-map.md`](../../../src/modules/example/references/surface-map.md). The canonical encryption map is the module-root `encryption.ts`, indexed there as `data.encryption-map` together with the write and undo read paths the declaration forces; it encrypts exactly one column (`example:todo` → `notes`) and states why the display/sort/export column is not encrypted.