Where an unfashionable stack is still the sensible choice, and where it is not.
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.
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
Backend API
Async processing
Storage
Configuration
Infrastructure
Testing
Security
Performance
Reliability
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