Data models

Use a data model to explain ownership and relationships, not to reproduce an entire production schema. Flowmark turns foreign-key declarations into ERD connections automatically.

Edit source — diagram updates live

Source

Copy sourceDownload SVGReset

diagram "Checkout schema" {
  direction LR

  presentation {
    title: "Checkout schema"
    titleSubtitle: "Customers · catalog · orders · payments — FK crow’s-feet"
  }

  layout {
    density: normal
    spacingScale: 1.1
    groupLayout: flat
    nodePlacement: basic
    considerModelOrder: true
    edgeNodeSpacing: 28
    edgeEdgeSpacing: 16
  }

  edges {
    route: orthogonal
    crossings: gaps
  }

  customers: table "customers" {
    columns {
      id: uuid PK
      email: text UK NN
      name: text NN
      created_at: timestamptz NN
    }
  }

  products: table "products" {
    columns {
      id: uuid PK
      sku: text UK NN
      name: text NN
      unit_price_cents: int NN
      active: bool NN
    }
  }

  orders: table "orders" {
    columns {
      id: uuid PK
      customer_id: uuid FK NN -> customers.id
      status: text NN
      currency: text NN
      total_cents: int NN
      placed_at: timestamptz NN
    }
  }

  order_items: table "order_items" {
    columns {
      id: uuid PK
      order_id: uuid FK NN -> orders.id
      product_id: uuid FK NN -> products.id
      qty: int NN
      unit_price_cents: int NN
    }
  }

  payments: table "payments" {
    columns {
      id: uuid PK
      order_id: uuid FK NN -> orders.id
      provider: text NN
      provider_ref: text UK
      amount_cents: int NN
      status: text NN
      captured_at: timestamptz
    }
  }

  shipments: table "shipments" {
    columns {
      id: uuid PK
      order_id: uuid FK NN -> orders.id
      carrier: text NN
      tracking: text UK
      shipped_at: timestamptz
    }
  }
}

diagram "Checkout schema" { direction LR presentation { title: "Checkout schema" titleSubtitle: "Customers · catalog · orders · payments — FK crow’s-feet" } layout { density: normal spacingScale: 1.1 groupLayout: flat nodePlacement: basic considerModelOrder: true edgeNodeSpacing: 28 edgeEdgeSpacing: 16 } edges { route: orthogonal crossings: gaps } customers: table "customers" { columns { id: uuid PK email: text UK NN name: text NN created_at: timestamptz NN } } products: table "products" { columns { id: uuid PK sku: text UK NN name: text NN unit_price_cents: int NN active: bool NN } } orders: table "orders" { columns { id: uuid PK customer_id: uuid FK NN -> customers.id status: text NN currency: text NN total_cents: int NN placed_at: timestamptz NN } } order_items: table "order_items" { columns { id: uuid PK order_id: uuid FK NN -> orders.id product_id: uuid FK NN -> products.id qty: int NN unit_price_cents: int NN } } payments: table "payments" { columns { id: uuid PK order_id: uuid FK NN -> orders.id provider: text NN provider_ref: text UK amount_cents: int NN status: text NN captured_at: timestamptz } } shipments: table "shipments" { columns { id: uuid PK order_id: uuid FK NN -> orders.id carrier: text NN tracking: text UK shipped_at: timestamptz } } }

Declare a table

diagram.flowmark

diagram "Order data" {
  direction LR

  customers: table "customers" {
    columns {
      id: uuid PK
      email: text UK NN
      created_at: timestamptz NN
    }
  }
}

Each column is name: type followed by zero or more markers:

Marker	Meaning
PK	primary key
FK	foreign key
UK	unique key
NN	not null

Markers are compact diagram notation, not database migration syntax.

Create relationships from foreign keys

Point an FK column at table.column:

diagram.flowmark

orders: table "orders" {
  columns {
    id: uuid PK
    customer_id: uuid FK NN -> customers.id
    status: text NN
    total_cents: int NN
  }
}

Flowmark creates the relationship edge and attaches it to the relevant row. You do not need a second edge declaration.

Choose a useful slice

An ERD becomes unreadable faster than an architecture diagram because every table contains several lines. Prefer one of these scopes:

• the tables owned by one service
• the write model for one transaction
• the entities touched by one feature
• the relationship around one risky migration

Omit audit columns, indexes, and implementation details unless they answer the reader’s question. The source is documentation, not a schema dump.

Tune ERD layout

Tables often benefit from basic placement and orthogonal routes:

diagram.flowmark

layout {
  nodePlacement: basic
  considerModelOrder: true
  edgeNodeSpacing: 28
}

edges {
  route: orthogonal
  crossings: gaps
}

Declare central tables early if considerModelOrder is enabled. If six or more relationship lines cross, first remove unrelated tables or split the view; spacing controls are the second remedy.

Flowmark can place ordinary architecture nodes and tables in the same diagram. That is useful for a service plus the small schema it owns. Keep it rare: mixing levels without a clear purpose creates more cognitive load than insight.