Ujjwal Raj

Posted on Jul 20

System Design Example using 'The Method'

#systemdesign #distributedsystems #softwareengineering #programming

Welcome to another article on system design on another Sunday. Every Sunday we have been discussing on how to design a good software system. This is going to be end of the series. Don't worry if you have not read the previous ones. We are carrying forward with us the rules that we keep on our finger tips.

The motive is to show that system design is not tech but an engineering art. The series is based on the Book Righting Software by Juval Lowey. I would be taking the same example in chapter 5 of the book in this article.

Here are the rules to follow:

Avoid functional decomposition (what we were doing in universities), and remember: a good system design speaks — through how components interact.
The client should not be the core business. Let the client be the client — not the system.
Decompose based on volatility — list the areas of volatility.
There is rarely a one-to-one mapping between a volatility area and a component.
List the requirements, then identify the volatilities using both axes: — What can change for existing customers over time? — Keeping time constant, what differs across customers? What are different use cases? (Remember: Almost always, these axes are independent.)
Verify whether a solution/component is masquerading as a requirement. Verify it is not variability. A volatility is not something that can be handled with if-else; that’s variability.
Use the layered approach and proper naming convention:
- Names should be descriptive and avoid atomic business verbs.
- Use <NounOfVolatility>Manager, <Gerund>Engine, <NounOfResource>Access.
- Atomic verbs should only be used for operation names, not service names.
layers given in the template should correspond to 4 question:
- Client : Who interacts withe system
Managers : What is required of the system
Engines : How system performs the business logic
ResourceAccess : How system access the resources
Resource : Where is the system state
Validate if your design follows the golden ratio (Manager:Engine). Some valid ratios: 1:(0/1), 2:1, 3:2, 5:3.

More than 5 Managers? You’re likely going wrong.
Volatility decreases from top to bottom, while reusability increases from top to bottom.
Slices are subsystems. No more than 3 Managers in a subsystem.
Design iteratively, build incrementally.
Design with the smallest set of reusable components needed to support core use cases. A good architecture integrates ~10–20 components to support them composably. Features are outcomes of integration, not implementation.
Design Don'ts
1. A Client should not call multiple Managers for a single use case.
2. A Client must not call Engines.
3. Managers must not queue calls to more than one Manager in the same use case. The need to have two (or more) Managers respond to a queued call is a strong indication that more Managers (and maybe all of them) would need to respond — so you should use a Pub/Sub Utility service instead.
4. Engines and ResourceAccess services do not receive queued calls.
5. Clients, Engines, ResourceAccess, or Resource components do not publish events.
6. Engines, ResourceAccess, and Resources do not subscribe to events. This must be done in a Client or a Manager.
7. Engines never call each other.
8. ResourceAccess services never call each other.

System Design Example

TradeMe is a platform that connects independent tradesmen (like plumbers, electricians, carpenters, etc.) with contractors who need skilled labor for construction projects. Tradesmen can list their skills, availability, location, and expected rate, while contractors can post project requirements, locations, desired skills, and budgets.

Key points:

Matching System: Facilitates dynamic matching of contractors and tradesmen based on skills, timing, and rates.
Market-Driven Pricing: Rates are influenced by discipline, skill level, experience, location, project type, supply-demand, risk, weather, and certification.
Project Flexibility: Tradesmen may be hired for varying durations, often joining and leaving projects at different times.
Payment & Compliance: TradeMe handles payments, logs hours, manages regulatory compliance, and prevents direct contractor-tradesman arrangements.
Revenue Model: Earns through a rate spread and annual membership fees from both contractors and tradesmen.
Call Centers: Nine localized centers with reps manage project-tradesman assignments based on local laws and codes.
Competition: A rival app focusing on cheaper labor is gaining traction, appealing to cost-focused contractors.

The Core Use Case

There is only one core use case - TradeMe is a system for matching
tradesmen to contractors and projects.

The Anti Design Effort

The following figure is the anti design which needs to be avoided at any cost. This is merely based on functional decomposition.

The Architecture

Who

Tradesmen: Independent, self-employed workers with specialized skills.
Contractors: General contractors who hire tradesmen for specific tasks on construction projects.
TradeMe Reps: Account representatives who manage matching and scheduling via call centers.
Education Centers: Institutions providing certification and continuing education for tradesmen.
Background Processes: Automated system functions like payment scheduling and regulatory reporting.

What

Membership: Both tradesmen and contractors register and pay to use the platform.
Marketplace: A digital platform where contractors post projects and tradesmen offer services.
Certificates & Training: Tracks qualifications and ongoing training requirements for tradesmen.

How

Searching: Tradesmen and contractors use the platform to find each other based on skills, availability, and rates.
Regulatory Compliance: Ensures wages, taxes, certifications, and safety standards are met.
Access to Resources: Provides tools for scheduling, reporting, and payment handling.

Where

Local Database: Stores regional data specific to each call center’s jurisdiction.
Cloud: Hosts centralized application logic, user data, and scheduling algorithms.
Other Systems: Interfaces with regulatory bodies, educational institutions, and financial systems.

Areas of Volatility

The core idea behind decomposition is to identify areas of volatility — parts of the system likely to change — and encapsulate them to reduce the impact of change. The TradeMe design team carefully analyzed these volatilities and mapped them to specific architectural components. Here's a summary:

🧩 Key Observations from Volatility Analysis

Volatility ≠ Variability: For example, tradesman attributes may vary (e.g., adding skills) but do not impact architecture significantly, so it's not volatile.
Volatility Requires Clarity: Each candidate must be examined to determine why it's volatile and what risk it introduces.
Some volatilities are external: For instance, payments may change frequently, but since TradeMe doesn’t implement its own payment system, it's treated as an external Resource.

🧱 Identified Areas of Volatility and Their Encapsulation

Volatile Area	Encapsulated In	Notes
Client Applications	Client Application	Different UI tech, devices, access methods; volatile interfaces.
Membership Management	Membership Manager	Adding/removing users, benefits; varies by locale.
Fees and Revenue Models	Market Manager	How the system makes money is changeable.
Project Definitions	Market Manager	Size and scope impact workflows; central to matching logic.
Dispute Resolution	Membership Manager	Must handle fraud and misunderstandings.
Matching and Approvals	Search Engine & Market Manager	Matching logic and search criteria both volatile.
Education Workflow	Education Manager	Scheduling, searching for training; certification required.
Certifications & Regulations	Regulation Engine	Rules change frequently by region or over time.
Reports & Auditing	Regulation Engine	Compliance-driven volatility.
Localization (Language, UI)	Client Applications & Regulation Engine	Can affect UI and regulatory compliance.
External Resources (e.g., Payments)	Resources and ResourceAccess	Store data and connect to systems with volatile access tech.
Deployment Strategies	Message Bus & Subsystems	Geographic, cloud/on-premise, and modular deployment needs.
Authentication & Authorization	Security Utility	Flexible and diverse in real-world scenarios.

📌 Design Insight

Not all volatile aspects deserve their own component; grouping them logically (like in a Manager) avoids architectural complexity.
If a proposed decomposition leads to a tangled system or asymmetry, it’s a sign of poor design.
Volatility-based decomposition aligns the system with business risk and adaptability.

This approach ensures that changes in business needs or external conditions have a localized impact, preserving the system’s stability and maintainability.

Static Architecture

Some components dependency diagrams

The Add Tradesman/Contractor call chain

Request Tradesman call chains (until matching)

Call chains for the Match Tradesman use case

Call chains for the Assign Tradesman use case

Call chains for the Terminate Tradesman use case

Call chains for the Pay Tradesman use case

Call chains for the Create Project use case

Call chains for the Close Project use case

Conclusion

System design is not merely an academic exercise or a diagramming ritual — it's the art of managing change. Through this series, we’ve consistently reinforced one truth: volatility is the compass of good architecture. By identifying and encapsulating the parts of a system most likely to change, we build not only for functionality today, but for adaptability tomorrow.

Using TradeMe as a running example, we’ve explored how to decompose a system based on business-driven change vectors, not arbitrary technical boundaries. We've learned to avoid the traps of functional decomposition and instead think in terms of clients, managers, engines, and resources, each aligned to a specific responsibility in the system.

While this is the end of the series, it should be the beginning of a new lens through which you view system design. Design iteratively, build incrementally, and always measure your architecture against the axis of volatility. That is how software stays simple, stable, and scalable — even in the face of constant change.

Thanks for reading every Sunday.

Here are links to previous articles in case you missed them:

DEV Community