The HLD and the Proposal

Overview

Two more artifacts from the starter set, with different jobs, different readers and different tenses. They are routinely merged into a single document that serves neither.

The separation to hold, from this module’s opening:

The HLD describes. The ADRs explain. The proposal asks.

The HLD

A high-level design says how the system works, at a level somebody joining or integrating can actually use. Container level — Module 3’s C4 Level 2 — rather than classes or deployment detail.

What belongs in it:

The containers, and what each is responsible for in one sentence.
The boundaries, and what crosses them.
External dependencies and what they are relied on for.
The constraints that shape the whole thing.
Pointers to the ADRs for the “why”.

What does not:

Implementation detail. It will be wrong first and the code is better.
The reasoning. That is the ADRs, and duplicating it guarantees the two diverge.
Anything that will be stale within a month.

That last exclusion is the practical test, because an HLD must be revised and every sentence is a future maintenance obligation. A document that says the retrieval service uses a bounded worker pool of eight has acquired a liability for no benefit.

The readable-by-an-outsider test

The rubric for this module makes it explicit: the HLD must be readable by someone who has not read Modules 1–8.

That is a harder constraint than it looks, and it fails in three characteristic ways:

Internal jargon. Terms this guide invented or borrowed — the action boundary, the degradation ladder, trust labels, the NFR budget — are meaningless to a new engineer. Either define them in one line on first use or use ordinary words.

Assumed context. A sentence that only makes sense if you already know why the legacy system is being incrementally replaced, or which earlier project failed and left a scar, needs the context inline or a pointer to it.

Reference to decisions the reader has not seen. “As decided in ADR 004” is fine as a pointer; “the two-service split” as an unexplained given is not.

A useful check: hand it to somebody technical who knows nothing about the project and ask them to describe the system back. What they get wrong is what the document does not say.

The LLD, and why it usually should not exist

The low-level design describes one component’s internals. The code does that more accurately, stays current for free, and is where engineers look anyway.

So a separate LLD is a second source of truth, and when the two disagree the document loses — silently, after somebody has trusted it.

Two genuine exceptions: a component being built by a team that cannot yet read your code, and an algorithm whose correctness should be reviewed before anyone implements it. Both are temporary documents with a planned end, and saying so when you write them is what stops them becoming permanent liabilities.

The proposal

A proposal requests a decision. Module 8’s justification pack is one; this is the template it fits into.

The difference from an ADR is tense and purpose. A proposal is pre-decision and persuasive; a record is post-decision and archival. Much of the content transfers — the criteria, the options, the rejections — which is convenient: a decided proposal becomes an ADR with a status line and the persuasion removed.

graph LR
  A["<b>Proposal</b><br/>before<br/><i>persuasive, asks</i>"] --> B["<b>Decision taken</b>"]
  B --> C["<b>ADR</b><br/>at the moment<br/><i>archival, explains</i>"]
  B --> D["<b>HLD updated</b><br/>continuously after<br/><i>descriptive</i>"]

  classDef pre fill:#E8A33D,stroke:#C4832A,stroke-width:2px,color:#ffffff
  classDef at fill:#5B8FB9,stroke:#4A7A9E,stroke-width:2px,color:#ffffff
  classDef post fill:#7D9A4E,stroke:#5F7A38,stroke-width:2px,color:#ffffff
  class A pre
  class B at
  class C,D post

One decision, three artifacts, three tenses. The proposal is consumed; the record is permanent; the description is maintained.

A workable proposal template is short: the problem in business terms, the options, the recommendation, what you are asking for, by when, and who decides. Module 8’s pitch structure maps onto it directly, and the last two fields are the ones most proposals omit — a document that does not say who decides and by when is a document that gets postponed indefinitely.

What these cost

The HLD costs continuous revision, and the previous topic established that a wrong one is worse than none. Give it an owner and a trigger — updated whenever a container is added or a boundary moves — or do not start it.

The proposal costs the work in Module 8, which is genuine: criteria fixed in advance, options scored, rejections documented. The template lowers the cost of doing that well; it does not remove it.

What the HLD says, and what it refuses to say

An HLD for the AI support platform, written for an engineer joining next month who has never heard of this guide.

Containers, one sentence each. A retrieval service that answers questions from product documentation. An action service that performs scheduling, credit and device operations on a customer’s behalf. A documentation index. The existing Rails monolith, which remains the system of record. The support console the agents already use. An external model provider.

Boundaries and what crosses them. The action service reaches the monolith through its public API and never its database. Both services reach the model provider only within the originating region. Customer-identifying data crosses into the index only after redaction.

Constraints, stated plainly and without assuming context. Several enterprise customer contracts prohibit their data being processed outside its origin region. Support tickets contain personal data. The monolith is being incrementally replaced, and no new engineering team is available.

Pointers, not reasoning. Why two services rather than one: ADR 004. Why hosted inference: ADR 002. Why retrieval rather than a trained model: ADR 003.

What it deliberately omits. The step cap of twelve, the confidence thresholds, the cache durations, the chunk sizes — all of which are true today and would be a maintenance obligation tomorrow. Those live in the ADRs where they are dated, or in the code where they are current.

Where the outsider test bites. A first draft said “the action path enforces the blast-radius tiers”. A new engineer cannot parse that. The revision reads: “before performing any operation, the action service checks it against a list of permitted operations and their approval requirements — some run unaided, some notify afterwards, some need a support agent’s confirmation, and some are not available at all.” Longer, and comprehensible without a glossary.

Owner and trigger: owned by whoever owns the platform’s architecture; revised whenever a container is added or removed, or a boundary moves. Written in the document, because an HLD without that line decays into the misleading case.

Feeds the workbook

Two artifacts come from this topic: the HLD and the architecture proposal in template form. The rubric’s readable-by-an-outsider requirement is the one to test deliberately — find someone who has not read the guide and ask them to describe the system back to you.

→ Four artifacts defined. Templates are how they get written at all — and how the thinking gets skipped. — Templates and template theatre