Skip to content
← Engineering handbook

Workflows & Automation · Backend· 6 min read

Docs-first delivery: why the schema and the contract come before the code

Writing architecture decision records (ADRs), interface contracts, and typed schemas before implementation. How documentation upfront accelerates velocity and prevents architectural rework.

DocumentationADRArchitectureEngineering Practices

On this page

The fastest way to slow down an engineering team is to write code before agreeing on the data contract. When developers start with implementation, frontend teams wait on unstable endpoints, backend engineers rewrite DTOs three times, and database schemas drift. In my projects, every complex system begins with an Architecture Decision Record (ADR) and explicit TypeScript DTO schemas.

The anatomy of a working ADR

  • Context: What specific business or scaling problem are we solving? What are the constraints?
  • Options considered: Why not use Redis Streams? Why choose PostgreSQL instead of MongoDB here?
  • Decision: The exact pattern, library, and data model selected.
  • Consequences: What operational trade-offs do we accept? (e.g. higher memory usage, eventual consistency).

When an ADR is written and reviewed, writing the code is straightforward execution. The schema defines the boundary, class-validator enforces the contract, and automated OpenAPI generators produce frontend API clients instantly.