Skip to content
Liquid Labs
All articles
Engineering practice

How we do technical design

Upfront technical design is one of the highest-leverage habits an engineering team can build. Here is how Liquid Labs teams approach it — from philosophy to checklist to worked example.

[Author][Date]3 minute read

Philosophy

The goal of technical design is to understand every change that needs to be made — code, configuration, schema, data — before development begins. Without that understanding, estimation is guesswork and sprint plans are unreliable.

A few principles guide how we approach it:

  • You cannot estimate a task you don't understand. Technical design and estimation are inseparable.
  • You cannot design something you haven't fully read. Full requirements clarity — acceptance criteria, UI designs — must precede any design work.
  • You cannot design on top of a system you don't know. Familiarise yourself with the existing implementation before proposing changes.
  • Prefer smaller, story-level designs over large feature-level ones. Fragmentation is a risk, but it's usually preferable to a monolithic design that is slow to evolve.
  • Keep design documentation brief and changeable. Bullet points beat long descriptions and complex diagrams.

Pre-design checklist

Before starting a technical design, answer these questions. If any answer is "no", close the knowledge gap first.

  • Are the acceptance criteria present and agreed upon?
  • Is the UI design present where relevant?
  • Have you personally used the existing product features related to the new functionality?
  • Have you familiarised yourself with the existing frontend, backend, APIs, database schema, configurations, and messaging pathways related to the area you are changing?

Technical design checklist

For every design, work through these areas. List the specific changes under each heading. If a category is not applicable, mark it "none" — the discipline of checking is the point.

Frontend

Screen changes
Action changes
Local storage changes
Backend API call changes

Backend API

New or changed endpoints
Logic changes in existing endpoints

Async processing

Message changes
Scheduled job changes

Storage

Database schema changes
File changes
Cache changes
Data migrations

Configuration

Feature flags, environment variables, credentials

Infrastructure

New or changed provisioning — API gateways, firewalls, compute, managed services

Testing

Manual, unit, API, and E2E test scenarios
Sandbox and test data requirements

Security

Frontend, APIs, database, third-party integrations, infrastructure, customer data

Performance

Frontend, APIs, database, queues and scheduled jobs

Reliability

Error handling, logging, alerting

Post-design checklist

  • Has the design been reviewed by the team lead?
  • Has the design been reviewed by other team leads affected by the changes, and where necessary, an architect?
  • Have all review comments been addressed?

Worked example

The following example shows how an engineer applies this process to a concrete story. The product is an e-commerce SaaS. The story:

"Show 'Shipped' status in customer orders."

Orders currently show Accepted, Processing, and Delivered. The warehouse system can mark an order as Shipped, but that status is not surfaced to customers. Assigned engineer: Bob.

Understand existing functionality

Bob is not familiar with order management (he's from the payments team). He runs the full order lifecycle in a test environment: places an order as a customer, accepts it as an owner, marks it as Shipped in the warehouse system, then checks — the customer still sees "Processing". This tells him the Shipped state from the delivery service is not being synced back.

Understand existing implementation

Bob traces the workflow in code using the browser network panel to find which endpoint fires when an owner accepts an order. He reads the controller and finds:

  • The order table has a status column whose code enum does not include a Shipped value.
  • On accept, an HTTP POST is sent to a third-party DeliveryService to create a delivery record, with the order ID as reference.
  • The DeliveryService API allows fetching a delivery by reference ID, and that entity has its own status field that becomes 'Shipped' when the warehouse user acts.
  • There is no webhook from DeliveryService. The Shipped state must be polled.

Design

Bob designs top-down, frontend first:

  • Frontend: show new Shipped status in both the order detail and order list screens. Assumes /orders and /orders/{id} will return a new enum value for Order.status.
  • Backend API: update both controllers to include the Shipped enum. Assumes the existing status column in the order table will be extended rather than adding a new delivery_status column.
  • Async processing: introduce a scheduled job that runs hourly, iterates through all orders in Processing state, fetches their delivery status from DeliveryService, and updates the order table if the status has changed. Batch by tenant to manage API call volume. Make the interval an environment variable.
  • No database schema changes beyond the enum extension. No data migration required — the job will correct historical records on its first run.
  • Configuration: new environment variable for the job interval.
  • Performance: monitor DeliveryService call volumes. Calculate peak rates based on open orders and tenant count if volume becomes a concern.

More articles

Talk to the founders.

Tell us about your product and the team you need. Gehan or Hasitha will reply.

Talk to the founders