Detailed Technical Design: Bridging Architecture and Code for Predictable Delivery

Detailed Technical Design is a vital step in software development.

You can’t jump directly from architecture—which provides the overall System Design—into coding. Not if you want reasonable development costs, long-term maintainability, and predictable delivery.

System Design outlines the system’s services and building blocks, as well as how they interact. Detailed Technical Design, on the other hand, specifies how each of those elements should actually be built.

Why Detailed Technical Design Matters

Like any design discipline, its main role is to reduce costs by finding the right solution early. It is always cheaper to test a design (sometimes through a Proof of Concept or custom testing tools) than to fully implement a component only to later realize it doesn’t fit.

A common misconception is that design “emerges” from code. In reality, engineering follows the opposite direction: first design, then build. Skipping this step usually undermines predictability.

Establishing Technical Design as a Process

Technical Design should exist as a clear activity in the development process.

On the projects I lead, I always emphasize this stage. Usually an architect or senior developer owns the task, since it requires strong analytical skills and deep system knowledge.

Scrum often misses this step. I’ve seen estimates made on half-understood solutions, riddled with unknowns, or based on assumptions the team didn’t share. Grooming, backlog refinement, or planning meetings rarely leave enough space for the analytical thinking needed here.

When estimates fail, defects pile up, or rework becomes unavoidable, developers often get blamed. But the real cause is skipping a proper Technical Design phase. Running Scrum ceremonies on top of well-defined Technical Designs leads to better quality, higher efficiency, and improved predictability.

What a Detailed Technical Design Should Cover

A solid Detailed Technical Design usually answers three key questions:

1. What are the requirements of the service/component?
2. What contracts define how others interact with it?
3. How will those contracts be implemented? (including internal code design, structure, and technologies).

1. Service Requirements

System Design defines services and their interactions to support requirements like scalability, reliability, or security. Each service then has its own responsibilities to meet.

These need to be written down and validated against the system’s use cases.

Requirements are rarely tied directly to a feature.
Example: Just as a jet’s fuel pump has nothing to do with serving meals, an IdentityProviderService has nothing to do with placing an order. Its requirement is clear: provide a security token from username and password.

2. Service Contracts

Strong contracts are the foundation of modular systems. They should be:

• Cohesive
• Logically consistent
• Independent
• Reusable

The level of detail depends on the project and the team’s experience—from draft interfaces with placeholder functions to fully defined APIs with detailed parameters.

3. Implementation

The Technical Design should define:

• How contracts are implemented
• Which frameworks and technologies will be used
• How those choices meet the service requirements

Even for something like a web client—where frameworks set many conventions—the design should specify best practices, exceptions, and customizations.

In larger systems with many services, keeping a consistent structure is crucial. Components should look and feel like part of the same system, which is only possible through consistent design practices.

The design should also capture:

• Key technical decisions
• Alternatives considered
• The reasoning behind choices

An Iterative Activity

Design is not linear. Each step gets revisited, refined, and validated against core use cases. Mistakes are expected—they’re much cheaper to fix in design than in code.

Peer review sessions are often invaluable, as a fresh set of eyes helps challenge assumptions and validate ideas.

Deliverables of Technical Design

The output of a Technical Design can include:

• A design document
• Diagrams and interface definitions (sometimes written in code)
• Proofs of Concept to validate design choices
• Small demos (vertical slices) showing how the design applies in practice

Case Study: Messaging Component in an Energy Project

In one energy system I worked on, the architecture defined a Messaging Component that had to support both Pub/Sub messaging and Fire-and-Forget commands.

Requirements:

• Message durability, reliability, and deduplication
• Ownership and security
• High performance under load
• Publishing transactions
• Monitoring and diagnostics

Contracts:

We defined the main concepts first (Message, Event, Task, Endpoint, Handler, MessageOwner, etc.). After several iterations, these were refined into clear interfaces in C#.

Implementation:

We compared Kafka and RabbitMQ. Through PoCs, RabbitMQ proved to be the better fit.

The design also established the code structure:

• Assemblies with clear roles and dependencies
• Rules for referencing across services
• How and where messages owned by other services would be written

Finally, we created demos to show how events and tasks would be published and handled.

Consistency Across Services

The same project had over a dozen services. Two examples—DataManagement and LongRunningFlows—were very different in purpose, yet shared the same coding structure and dependency principles. This consistency was achieved through detailed code design and technical guidelines.

The Value of Detailed Technical Design

The effort required for Detailed Technical Design is modest compared to implementation.

Designing a service or component usually takes two to five days. Sometimes, more time is needed for PoCs and technology evaluations, which should be handled separately.

By formalizing the design before writing code, you save time, reduce risks, and build systems that are easier to maintain.