How to Choose and Implement Architecture Contracts for Distributed Systems

Review of 2W1H Contract Decision

The purpose of making contract decisions at the architecture layer is to control change frequency while keeping component coupling within an acceptable range. By splitting a monolith into distributed components, we must consider static coupling (which components are required to run) and dynamic coupling (runtime coordination, communication, and data integrity).

What Is a Contract?

A contract describes how components communicate and exchange data. It can be a strict format like Protobuf (PB) or a loose format like JSON. The choice influences how tightly components are coupled and how easily changes can be introduced.

Data Model Read/Write Modes

Schema‑on‑Read (Looser Contract) : Data is stored in a flexible format such as MongoDB’s BSON/JSON. Example JSON document:

{
  "id": 1,
  "name": "xiaokun liu" // includes firstName
}

Application code can derive missing fields, e.g.:

if (user && user.name && !user.first_name) {
    user.first_name = user.name.split(" ")[0];
}

This demonstrates the convenience of a loose contract: storage format stays consistent while business logic adapts internally.

Schema‑on‑Write (Stricter Contract) : Data must conform to a predefined schema, such as a MySQL table. Adding a new column requires DDL changes:

ALTER TABLE users ADD COLUMN first_name varchar(50) DEFAULT NULL COMMENT 'user first name';
UPDATE users SET first_name = substring_index(name, ' ', 1);

Strict contracts enable static checks and guarantee field‑type alignment, but they reduce flexibility.

Forward and Backward Compatibility of Data Encoding

When a component evolves its data contract, compatibility must be considered.

Forward Compatibility (old readers can read new data): If component A adds a required first_name field to a Protobuf message, component B using the old definition will fail to parse the data.

message Person {
  required string user_name = 1;
  optional int64 favorite_number = 2;
  repeated string interests = 3;
  required string first_name = 4; // new field
}

Backward Compatibility (new readers can read old data): The opposite scenario where old data is read by a newer schema that adds optional fields.

Why Protobuf 3 Improves Compatibility

Protobuf 3 removes the required keyword, making all fields optional by default, which eases forward/backward compatibility. However, changing a field’s type (e.g., from int64 to string) still breaks dependent components because the underlying tag‑type mapping changes.

Practical Methodology for Architecture Contract Decisions

Clarify the current architectural needs and goals (e.g., performance vs. readability).

Map out component interactions and communication flows.

Analyze coupling and change frequency, then choose a contract type (strict vs. loose) and record the decision in an ADR.

When implementing, ensure the chosen protocol supports the required forward and backward compatibility, and prioritize the most important architectural characteristics.

Summary

When deciding on an architecture contract, assess the system’s goals, evaluate component coupling, select an appropriate data encoding (JSON for flexibility, Protobuf for efficiency), and design the protocol to be forward and backward compatible to minimize disruption during evolution.