The Documentation Rot Problem

If you’ve worked on a backend team for long enough, you know the lifecycle of database documentation.

On day one, the lead architect meticulously draws a beautiful Entity-Relationship Diagram (ERD). Everyone nods in agreement. On day ten, a feature requirement changes, and a developer adds a new column to a table via a migration script. The ERD is not updated. By day sixty, the visual diagram is entirely detached from reality, rendering it not just useless, but actively misleading.

This phenomenon—documentation rot—occurs because the visual representation of the schema and the actual implementation of the schema live in two entirely separate ecosystems.

Code as the Source of Truth

The only way to guarantee that your database diagram is accurate is to derive it directly from the code executing in production.

Historically, this meant running complex reverse-engineering tools against a live SQL database. While effective, this approach is often slow, requires active database connections, and misses application-level relationship context that isn’t enforced by strict foreign keys.

This is where Drizzle ORM completely changes the game.

The TypeScript Advantage

Drizzle ORM is built on a fundamentally different philosophy than older ORMs like Prisma or TypeORM. With Drizzle, your schema is defined purely in standard TypeScript code. There are no proprietary schema languages to learn, and no heavy code-generation steps required just to boot your app.

// A standard Drizzle schema definition
import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
  id: uuid('id').primaryKey().defaultRandom(),
  email: text('email').notNull().unique(),
  createdAt: timestamp('created_at').defaultNow(),
});

Because Drizzle schemas are just Abstract Syntax Trees (ASTs) written in TypeScript, they can be statically analyzed with incredible precision.

Bidirectional Parsing with Sepio

At Sepio, we realized that Drizzle’s architecture provided the perfect foundation for solving documentation rot.

We built a bidirectional parsing engine that can consume a Drizzle TypeScript file, instantly convert it into an interactive visual ERD, and vice versa.

When you drag a new relation line in the Sepio visual canvas, we don’t just update a pretty picture. We generate the exact underlying DBML (Database Markup Language) and the corresponding Drizzle ORM TypeScript code required to make that relationship a reality.

The New Workflow

1. Plan Visually: Start your new feature by drawing tables in Sepio. It’s faster to reason about foreign keys and cardinalities visually.
2. Export to Code: Click export, and instantly drop the generated Drizzle TypeScript into your codebase.
3. Evolve in Code: Six months later, when you add a column in your IDE, simply paste the code back into Sepio. The visual canvas immediately updates to reflect reality.

By treating code as the ultimate source of truth, and treating the visual diagram as simply a projection of that truth, we can finally kill documentation rot for good.