Architecture practice

Documenting Service Boundaries and Dependencies with Useful Context

A dependency list tells you that two things are connected. Architecture documentation should also explain why that connection matters, where the boundary sits, and what a reader should investigate next.

Service boundaries are easy to draw and hard to explain. A box labeled “Billing” may stand for a team, a deployable service, a domain capability, or a collection of systems that happen to be managed together. When the diagram leaves that meaning implicit, different readers can reach different conclusions from the same picture.

Useful documentation makes the model’s perspective explicit. It does not need to capture every implementation detail. It needs to state the distinctions that guide design, operations, ownership, or change.

Name what the boundary means

Start by choosing the boundary relevant to the view. A team map can show ownership. A runtime map can show deployable units and infrastructure. A domain view can show capabilities and their contracts. Those boundaries may overlap, but they are not interchangeable.

Write a short note near the view explaining the grouping rule: “Groups indicate owning teams,” “Each box is an independently deployed service,” or “This view follows order lifecycle responsibilities.” That small statement prevents layout from doing more work than it can safely do.

When a service spans several responsibilities, do not force a false clean edge. Record the ambiguity as an open question or mark the part of the model that is transitional. Architecture documentation is most useful when it distinguishes observed facts from intended direction.

Describe dependencies as relationships

A line between boxes says little by itself. Add the information needed to understand the relationship: who initiates it, what passes across it, and whether it is synchronous, asynchronous, or still unknown. For example, “Order API requests stock reservation” conveys a different operational shape from “Order publishes OrderSubmitted; inventory consumes it.”

Do not add details merely because they are available. A low-level protocol or topic name belongs in the diagram when a reader needs it for the current discussion. Otherwise, link a detailed specification or add a note. The main view should stay legible at its intended zoom and audience.

Direction should be consistent. If arrows represent data flow in one view, avoid using them to mean ownership elsewhere without a clear legend. For bidirectional relationships, say what is bidirectional: two APIs, a request and response, or mutual data access. If direction is not known, do not invent it to make the picture look tidy.

Separate overview from detail

Readers rarely need every dependency at once. Begin with system context: users, external systems, the product boundary, and a few high-value relationships. Then provide focused views for the workflows, subsystems, or shared services that matter. A hierarchy gives readers a path from overview to internals without forcing them to parse a dense master diagram.

tlDiagram models elements, connectors, and views. Elements can own their own views, and an element may be reused in multiple views. This supports a practical pattern: keep a shared platform dependency visible in the system overview and also include it in the specific service view where its role needs explanation. The views stay focused while the model preserves context.

The tool’s C* approach is inspired by C4, while allowing teams to choose more than four levels of hierarchy. This flexibility is useful when a fixed number of levels does not fit the system, but hierarchy should still earn its keep. Each level should clarify a boundary, responsibility, or change surface.

Document ownership without implying certainty

Ownership helps readers know whom to involve when a contract changes. Record a team or role if the information is current and approved for the audience. Avoid embedding personal names or informal guesses that age quickly. Where ownership is shared, name the decision-making responsibility as well as the operational contact if those differ.

Likewise, distinguish deployed reality from target design. A “planned” label, a short status note, or a separate future-state view can prevent readers from mistaking a proposal for production. If a dependency is a risk or an exception, make that explicit instead of relying on a color that may be inaccessible or unexplained.

Make maintenance part of the model

Choose a source of truth and a review trigger. Some teams edit diagrams collaboratively in a web interface; others prefer text-based changes reviewed with code. The open-source tld project provides a CLI and YAML workflows alongside a web UI, and supports Git-oriented changes. Its README also describes repository indexing and codebase mapping, while the indexing docs caution that the pipeline is under active development and may have rough edges or long runtimes on large repositories.

Generated relationships can help discover candidates, but source references do not automatically reveal business ownership, intent, or runtime behavior. Validate the result with people who understand those boundaries. Keep human decisions visible and attach links to deeper technical evidence when a diagram cannot carry it all.

Architecture documentation becomes more durable when it teaches the reader how to interpret it. State the viewpoint, show only the relevant dependencies, and make uncertainty visible. Then the diagram can support real conversations about ownership and change, rather than simply recording that boxes exist.