Blog/A first-principles approach

A first-principles approach to your data layer

Take the most concise thing you can write to work with a database table and follow where it leads, without adding anything along the way. That one small definition keeps answering the next problem, until it adds up to a whole data layer.

September 30, 2025Design4 min read

The simplest thing you can write

Start at the bottom. The database owns the data model, and the application needs a concise, typed way to work with it. The least you can write to make a database row usable in application code is its shape, a typed and named set of fields. In a modern language that is a record or a data class.

City.kt Kotlin
1
2
3
4
5
data class City(
    @PK val id: Int,
    val name: String,
    val country: String
) : Entity<Int>

The names come from convention, Entity marks the class as a table-backed entity ST/ORM can read and write, and Kotlin nullability says which values may be absent in application code. That is the entire application-facing shape. The first principle is to keep it this small: the data and nothing else, with no hidden lifecycle, behavior, or framework state attached. The rest of this post follows from refusing to add to it.

It happens to be the perfect carrier

The first thing you get for free is a carrier. A plain data class is also the best way to move the data around, and since nothing is attached to it, it passes through every layer unchanged: out of the repository, into your services, through the controller, out to a serializer, across a thread boundary, and back. You did not have to design a carrier, because the smallest useful shape already is one, and what you loaded is what you pass.

And it queries the whole graph

A relationship can be part of that shape too. If a user always needs its city, the field is typed as City; if the load should be deferred, it is typed as Ref<City>.

User.kt Kotlin
1
2
3
4
5
data class User(
    @PK val id: Int,
    val name: String,
    @FK val city: City
) : Entity<Int>

With relationships in the shape, the definition that carries the data also describes how to query it. ST/ORM generates a metamodel from it, and you can follow those relationships across the relation graph. users.findAll(User_.city.name eq "Sunnyvale") reaches from a user to its city in one line, type-checked, with the join derived from the relationship path instead of written by hand at every call site.

What falls out of keeping it small

The same small shape ends up doing jobs that usually take separate pieces you write, map, and keep in sync. It is the value your application passes around, the typed contract your queries compile against, and the path into the relation graph. In ST/ORM all of that comes from one decision: keep the application-facing view of database data small, typed, and free of hidden state.