pattern-architect-data-model

Standardize how we design data models: the shape of every entity — what gets named what, which columns it carries, how its constraints/indexes/views are spelled — follows a predictable convention so reviewers and tools can navigate the schema without surprises.

When to activate

Activate this skill whenever the user:

• designs a new table, model, or schema ("add a users table", "model the orders domain")
• adds, renames, or drops a column, index, or constraint
• edits ORM model files (models.py, models/*.py, SQLAlchemy Base subclasses, Django models)
• asks "how should I name this table/column/index/constraint?"
• proposes a new entity at architecture-discovery time and is deciding its column shape and relationships

Pattern

Naming conventions

Tables — plural nouns, snake_case:

✅ users, orders, order_items, audit_logs
❌ user, Order, OrderItem, AuditLog

Columns — descriptive snake_case nouns. Avoid single-letter or generic names:

✅ email, created_at, total_amount_cents, shipping_address_id
❌ e, ts, amt, addr_id, data, info

Constraints, indexes, views — prefix with the kind, then table, then columns:

SQLAlchemy MetaData naming convention

Pin the prefixes above at the MetaData level so every autogenerated migration emits predictable names — never rely on the dialect's anonymous defaults (they make downgrade() and name-parity tests impossible):

from sqlalchemy import MetaData

NAMING_CONVENTION = {
    "pk": "pk_%(table_name)s",
    "fk": "fk_%(table_name)s_%(column_0_name)s",
    "ix": "idx_%(table_name)s_%(column_0_name)s",
    "uq": "uq_%(table_name)s_%(column_0_name)s",
    "ck": "ck_%(table_name)s_%(constraint_name)s",
}

metadata = MetaData(naming_convention=NAMING_CONVENTION)
# Base = declarative_base(metadata=metadata)  /  class Base(DeclarativeBase): metadata = metadata

Multi-column or rule-bearing artifacts still pass name= explicitly (UniqueConstraint("org_id", "email", name="uq_users_org_id_email")); the convention is the safety net, not a substitute for deliberate names on anything compound.

Recording the decision in the data-model contract

Every entity-shape decision this skill produces lands in docs/data-model/<entity>.yaml — one ODCS file per persistence entity (template: skills/workflow-writer-publish-architecture/templates/data-model.yaml). The contract is the single source of truth: engineers implement against it (pattern-engineer-database, the migration/ORM layer), E2E seed helpers conform to it (pattern-e2e-coding-standard), and reviewers verify against it (pattern-reviewer-contract). Do NOT decide entity shape in code, commit messages, or PR descriptions.

What the contract file declares, per entity: table name (plural snake_case physicalName), every column with type + nullability + default, PK/FK/unique/check constraints and indexes by their convention names above, FK ON DELETE/ON UPDATE policy, and relationship cardinality.

Cross-references: endpoint shape lives in the sibling docs/api-contract/<entity>.yaml; project-wide axes (ID strategy, timestamp policy) live in the relevant ADR — this contract inherits them rather than redefining.

If the contract is missing for an entity the engineer is about to touch, this skill — not the engineer — owns adding it. The engineer halts and surfaces "no data-model contract for <entity>" rather than guessing.