Data modeling concepts

A data model describes the information the application owns: the entities that exist, the fields each one carries, and how they relate. The classic way to work one out is an entity-relationship (ER) diagram — tables as boxes, relationships as lines — and getting it down early is what lets pages, endpoints, and stores agree on the same shapes later instead of each inventing its own.

Entities, fields, keys

An entity is a thing the product keeps track of — a user, an order, a message. Each carries fields, and one field is the primary key, the value that identifies a row. In Nodlume every new entity arrives with an id key already on it, the one field whose existence is not a modelling decision; rename it to slug or orderId where the domain has a better identifier, and generated routes follow (a CRUD detail route is named after the entity's actual key).

Relations and cardinality

A relationship on an ER diagram is, in the running application, a foreign key: a field on the child that references the parent. The three cardinalities behave differently, and choosing between them is most of data modeling:

• One-to-many (1–N) — the common case. An order belongs to one customer; a customer has many orders. The child gets a plain foreign key.
• One-to-one (1–1) — the same foreign key, made unique, so a second child row referencing the same parent is impossible.
• Many-to-many (N–N) — cannot be a single field on either side, so it becomes a join entity with a key of its own and a foreign key to each side. Modeling it explicitly, rather than hiding it in a line, is honest: the join table is where relationship-specific fields (a role, a joined-at date) end up living.

Two relations between the same pair of entities are legitimate — a message has a sender and a recipient, both referencing User — and simply mean two foreign keys.

On the Data tab's ER board, a relation is the foreign key: drawing a stroke between two entities writes a References field on the child, erasing the line removes the field, and typing the constraint by hand draws the same line. There is no separate edge state, so the picture can never claim a relationship the generated code would not have. Renaming an entity rewrites every reference pointing at it.

Reusable types

Values that recur across entities — a status enum, a money shape, an address — are better named once as a shared type than restated in each place that uses them. pending | active | cancelled retyped on four tables is four chances to disagree. A named type can then be referenced from entity fields and from API response contracts alike, because a response body and a column are the same shapes.

Stay database-agnostic until you must not

An ER diagram knows the tables, the columns, the keys, and what references what — everything a schema needs and nothing about which database will hold it. That is worth preserving: committing to CREATE TABLE or a Prisma schema during planning picks a database before the requirements have. Nodlume exports the diagram as a Mermaid erDiagram (docs/data-model.mmd in the scaffolding) — text that renders as a picture on GitHub and in editors, stays true in the repo because it is text, and converts mechanically into Prisma, Drizzle, SQL, or Mongoose when the choice is finally made.

The model built this way feeds CRUD endpoint generation, the Security and Traceability matrices, and the export.