Interface IModel

Finished documentation for this model. Lead with the stored concept, lifecycle, ownership, and important relationships.

Also name any value the entity exposes that is derived rather than stored (an aggregate or rollup over related rows) together with its aggregation path — the relation it sums over and that relation's direction, so downstream phases aggregate from the correct side (rows that reference this entity in one role are not the rows where it acts in another). When the source is a polymorphic {type, id} pointer, state the join to perform — downstream phases read this prose to surface that attribute, so stating only "query output" drops both the attribute and its direction.

Foreign key fields establishing relationships to other models.

GIN indexes for PostgreSQL full-text search (trigram).

Final table/model name.

Use a plural, snake_case, prefix-aware table name. When stance is "material", place the special mv_ prefix before the configured database prefix.

Regular persisted data fields owned by this row, including values that a snapshot/history row intentionally captures at a point in time.

Every model must include a non-null created_at datetime plain field. Mutable business rows also include non-null updated_at, while deleted_at is added only for soft-delete requirements. Current query/service output reconstructed from source rows belongs in prose or materialized views instead.

Regular indexes for query performance.

Primary key field (UUID).

Architectural role of this model, guiding API endpoint generation.

• "primary": Core entity users manage independently (full CRUD APIs). Use when users need to create, search, or manage entities outside their parent context.
• "actor": Authenticated user type with its own identity, credentials, and auth flow. Generates auth endpoints.
• "session": Login session table belonging to exactly one actor. Append-only audit trail, managed via auth flows.
• "subsidiary": Supporting entity scoped to a parent context. It is not a standalone root resource by default, but its exact creation surface is decided from its foreign-key parentRelation and interface endpoint design.
• "snapshot": Point-in-time versioning record, typically append-only and read-only from user perspective.
• "material": Read-only materialized query projection. The table name must start with mv_, and normal CRUD endpoints are not generated.

Unique indexes for data integrity constraints.