Encoding Intent Through Structure

Core Concepts

Constraints as Purpose Carriers

Design intent rarely survives as comments. It survives as structure. The idea is grounded in artifact theory: an artifact's physical structure constrains what capacities it can exhibit, and those constraints are often features, not failures. A door with no handle on the outside isn't broken—it's a deliberate signal that you cannot enter from that side.

In software, structural constraints work the same way. When you see a method that takes a NonEmptyList<T> instead of a plain List<T>, the type isn't just preventing a bug at runtime—it's communicating that the design never considers the empty case. That constraint is the rationale.

A constraint that prevents misuse is indistinguishable from a constraint that communicates intent. In good design, they are the same thing.

The goal of structural encoding is to make this implicit: future engineers shouldn't need to read a decision log to understand that the empty list case was ruled out—the type won't compile if you try to pass one.

Invariants: Encoding What Must Always Be True

Class invariants formalize constraints that encode expectations about a system's state and behavior at specific boundaries. An invariant is a condition that must hold on every instance of a class between public method calls. When you write an invariant, you are forced to articulate what the class is in terms of its stable properties, not just what its methods do.

This is why writing invariants requires developers to make their intentions explicit before implementation. The discipline of stating an invariant is the discipline of stating purpose.

Consider a BoundedQueue class. Its invariant might be:

0 <= size <= capacity

This encodes two things: the queue is never negative in size (an obvious correctness property), and the queue cannot exceed its capacity (the design boundary). The second part is the interesting one—it tells you that this component was designed with resource management as a first-class concern. That constraint communicates a design decision that no comment can express as reliably.

Invariants can also be evaluated dynamically at runtime, which closes the feedback loop: the structure doesn't just communicate intent to readers, it enforces it against the running system.

Capacity Constraints as Design Signals

Not all capacity limits are arbitrary. A well-designed system's constraints should align with its purpose, preventing misuse while enabling proper use. The challenge is distinguishing purposeful constraints from accidental ones.

A purposeful capacity constraint carries a signal: it says "this component was designed for a specific operating envelope." A ThreadPool with a maximum of 10 threads isn't a bug waiting to be raised to 100—it may be encoding that the downstream system it coordinates with supports at most 10 concurrent connections. Removing the limit breaks purpose, not just configuration.

An accidental constraint, by contrast, exists because someone hardcoded a value without thinking about it. It communicates nothing useful, and future engineers must treat it with suspicion.

The practical test: can you explain why the limit exists in terms of the system's operating context? If yes, it's purposeful and worth preserving explicitly. If not, it's noise—and potentially a maintenance hazard because readers may treat it as carrying intent that it doesn't.

LSP: Behavioral Contracts as Purpose Boundaries

The Liskov Substitution Principle, formalized by Barbara Liskov in 1987, establishes that a subtype must be substitutable for its parent type without breaking program correctness. But reading LSP purely as a correctness rule misses its deeper function.

LSP is a mechanism for encoding what a type promises. When a parent type establishes a behavioral contract—inputs it will accept, outputs it will return, exceptions it will or won't raise—that contract is the type's purpose statement. LSP violations occur when a subclass breaks the behavioral contract of its parent, which means the subclass is claiming an identity (a subtype relationship) that misrepresents its actual behavior.

From this angle, an LSP violation is not just a bug—it's a lie encoded in the type hierarchy. The hierarchy says "this is a kind of X," but the behavior says "this cannot actually do what X promised." Future engineers reading that hierarchy will be misled about what the system can do.

ISP: Interface Boundaries as Use Constraints

The Interface Segregation Principle requires creating specialized, narrow interfaces tailored to specific client needs rather than bloated general-purpose interfaces. Narrow interfaces encode purpose by limiting what operations a client can invoke.

This is not just ergonomics. When a client only receives the ReadableStore interface rather than the full Store, you've communicated something structural: this component is designed to read, not write. That boundary exists in the code, not in a document. It guides refactoring, testing, and extension.

Bloated interfaces force developers to implement methods they don't need, tempting them to throw NotImplementedException—which is an LSP violation waiting to surface. The bloat creates pressure against the design intent, and developers eventually relieve that pressure in ways that corrupt the behavioral contracts.

The LSP-ISP Entanglement

Violations of ISP (bloated interfaces) often lead directly to LSP violations (broken behavioral contracts). The chain is deterministic: a class forced to implement methods beyond its purpose throws NotImplementedException; that throws break the contract the parent established; future callers depending on that contract encounter runtime failures.

The insight this entanglement reveals is that LSP and ISP aren't independent rules—they are two angles on the same concern. ISP is about encoding purpose into the interface boundary; LSP is about enforcing that the purpose encoded survives through the type hierarchy. Together, they ensure that the structural signals you write are trustworthy.

Fitness Functions: Operationalizing Architectural Purpose

At the code level, invariants and interface boundaries encode local purpose. At the architecture level, fitness functions serve as a mechanism to encode and continuously verify that a system maintains alignment with its intended architectural purpose. Ford, Parsons, and Kua define them as "any mechanism that provides an objective integrity assessment of some architectural characteristic(s)."

Fitness functions make architectural purpose executable. Instead of writing "this system must remain maintainable" in an ADR, you write a fitness function that measures cyclomatic complexity, dependency direction, or test coverage and fails the build when those measures drift past thresholds. The purpose statement moves from a document into the deployment pipeline.

Architectural "-ilities"—scalability, maintainability, security, reliability—represent the purpose-driven qualities that stakeholders consider essential to system success. Fitness functions operationalize these by making them measurable and continuously verifiable. Stakeholders specify what the system must be, and those specifications become technical constraints that guide evolution.

Feedback Loops as Intent Verification

Fitness functions provide continuous feedback loops that make architectural purpose visible and verifiable throughout the development lifecycle. When a change threatens an architectural goal, developers see it immediately—not six months later in a postmortem.

Deployment pipelines that include fitness function checks embed purpose-enforcement into the development process itself, making purpose a first-class concern alongside functional correctness. This is structurally identical to what invariants do at the object level: they make the violation detectable, automatically, at the boundary where it matters.

Worked Example

Scenario: A Rate-Limited API Client

Consider an API client component designed to enforce a rate limit of 100 requests per minute imposed by a third-party service. Here is how the same design intent can be encoded with varying levels of structural legibility.

Accidental encoding (purpose hidden):

class ApiClient:
    def __init__(self):
        self._counter = 0
        self._window_start = time.time()

    def request(self, endpoint):
        if self._counter >= 100:
            raise RateLimitExceeded()
        self._counter += 1
        # ... make request

The 100 is a magic number. The reset logic is missing. There is no invariant. Future engineers will wonder: is 100 a server-side limit? A safety margin? A performance tuning parameter? Can I raise it?

Purposeful encoding (intent embedded in structure):

class RateLimitedApiClient:
    """
    Client enforcing the ExternalService limit of 100 req/min.
    Invariant: 0 <= _requests_in_window <= MAX_REQUESTS_PER_MINUTE
    """
    MAX_REQUESTS_PER_MINUTE = 100  # ExternalService SLA, see ADR-012

    def __init__(self):
        self._requests_in_window: int = 0
        self._window_start: float = time.time()
        self._assert_invariant()

    def _assert_invariant(self):
        assert 0 <= self._requests_in_window <= self.MAX_REQUESTS_PER_MINUTE

    def request(self, endpoint: str) -> Response:
        self._rotate_window_if_needed()
        if self._requests_in_window >= self.MAX_REQUESTS_PER_MINUTE:
            raise RateLimitExceeded(
                f"Limit of {self.MAX_REQUESTS_PER_MINUTE} req/min reached"
            )
        self._requests_in_window += 1
        self._assert_invariant()
        # ... make request

Now the constraint communicates purpose. The constant is named after its origin. The invariant is explicit and checked. The exception message encodes the limit. A future engineer who wants to "just raise the limit" must actively confront what that means.

Adding interface segregation:

class ReadableApiClient(Protocol):
    def get(self, endpoint: str) -> Response: ...

class WritableApiClient(Protocol):
    def post(self, endpoint: str, body: dict) -> Response: ...

Consumers that only read get ReadableApiClient. This encodes at the interface level that read and write operations have different roles in the system—a structural signal that guides testing, mocking, and future extension without a word of documentation.

Compare & Contrast

Structural Encoding vs. Documentary Encoding

	Structural Encoding	Documentary Encoding
Form	Types, invariants, interfaces, fitness functions	ADRs, comments, READMEs
Durability	Survives refactoring (enforced by compiler/test suite)	Drifts silently (not enforced)
Discoverability	Encountered during normal development	Requires knowing to look
Granularity	Local (class) to global (architecture)	Any level, but harder to scope precisely
Maintenance cost	Paid upfront in design discipline	Low upfront, high long-term (staleness)

The two approaches are complements, not substitutes. Structural encoding carries the load of what must be true. Documentation carries the why that structure alone cannot express. The mistake is treating one as sufficient for the other.

Purposeful Constraints vs. Accidental Constraints

Fig 1

The practical test is causal: if you remove the constraint, does something break or change in behavior? If yes, the constraint is carrying real information. If nothing changes, it's noise—and worse, it trains future engineers to distrust constraints in general.

Common Misconceptions

"LSP and ISP are separate rules to check independently." They are entangled. ISP violations cascade into LSP violations through the NotImplementedException mechanism. Applying ISP correctly is a precondition for LSP being enforceable. Treat them as a pair.

"Invariants are just defensive programming." Defensive programming adds guards to catch unexpected inputs. Invariants are different: they formalize what the class promises about its own state. Writing invariants requires making design intentions explicit before implementation—the discipline is about articulating purpose, not just catching bugs.

"Fitness functions are for big, complex systems." Fitness functions are mechanisms. They scale down to a linting rule in a CI pipeline. Any automated check that measures whether the system maintains an architectural property—dependency direction, test coverage floor, response time budget—is a fitness function. The formalism is available at any scale.

"A constraint that is documented is as good as a constraint that is structural." Documentation drifts. Structural constraints do not drift silently—they can be evaluated dynamically at runtime or fail the build. The two are not equivalent carriers of intent; structural encoding is more durable by design.

"Capacity constraints should always be configurable." Some should. But making every capacity constraint configurable removes the design signal it carries. When MAX_REQUESTS_PER_MINUTE becomes a config value, the fact that it originated from a third-party SLA becomes invisible. Know which constraints encode hard boundaries before making them soft.

Active Exercise

Reading Structure as Argument

Take a codebase you own or work in regularly. Select one component or subsystem and do the following:

1. Inventory the structural constraints. List: type boundaries, method visibility, interface definitions, class invariants (explicit or implicit), and any capacity limits (timeouts, queue sizes, thread counts).

2. Classify each constraint. For each item: Can you state why this constraint exists in terms of the system's operating context? If yes, mark it purposeful. If not, mark it uncertain or accidental.

3. Find the gaps. Identify at least one design decision you know was intentional—something from architecture review, a postmortem, or a past conversation—that is not reflected structurally anywhere in the code.

4. Encode one gap. For the gap you identified, determine the right structural mechanism: an invariant, a narrower interface, a named constant with an explanatory comment, or a fitness function in your CI pipeline. Implement it.

5. Reflect. What would a new engineer on this codebase now understand from the structure that they couldn't before?