Chapter 9: Architecture: The graph of programs and wires
This introduction defines multi-service architecture as a graph to reconstruct and previews a three-step AI process for mapping its components, stacks, and request wiring.
After this chapter you will be able to
- Multi-service architecture boundary. Distinguish a single-process codebase from a multi-service system, and explain why the latter requires a graph of programs connected over the network. State that a single executable, library, or CLI has module-level architecture, whereas multiple booted programs and their calls form a service graph.
- Distributed architecture evidence. Describe the four kinds of evidence used to reconstruct a multi-service architecture: process configuration, environment variables, SDK client initializations, and Terraform state. Explain that local runtime configuration reveals managed internal services, while variables and external integrations reveal dependencies beyond the team’s own processes.
- Service graph model. Explain an architecture as a graph whose nodes are programs that run and whose edges are the communication lines between them. Describe why understanding it means naming the nodes, tracing their wires, and anticipating how each wire can fail.
- Connection failure categories. Classify an edge by whether it is synchronous or asynchronous and whether it stays internal or crosses the public internet. Explain that internal asynchronous work can fail silently after the user receives success, while public synchronous calls put third-party latency and failures on the user's request path.
- Graph-based design inferences. Explain what the service graph's node count, node labels, and arrow directions reveal: the build-versus-buy ratio and rough reading workload, custom versus commodity code, and inbound, internal, or outbound trust and reliability boundaries. Describe how image versus build directives can provide a quick estimate of commodity versus bespoke components.
- Four-source architecture map. Explain how compose/process declarations, environment files, application code, and Infrastructure-as-Code combine to reveal different parts of a system's architecture. State the primary evidence each source provides and the blind spot that requires the other sources.
- Process declarations and boot dependencies. Describe how compose files, Procfiles, or Kubernetes manifests identify programs that run together, and how depends_on relationships can reveal an internal dependency graph. Distinguish boot-order evidence from proof of every service the system calls.
- Candidate dependencies and runtime proof. Distinguish environment-variable names as candidate evidence for external dependencies from SDK imports or client construction in application code as evidence that an integration is used. Describe how code can also show whether a call is synchronous in a request, performed by a worker, or sent through an asynchronous queue.
- Source-backed component inventory. Describe how to ask an agent for an inventory of every runtime program and connection, using configuration as a starting hint but source-code call sites as proof. State that each entry should describe what the component physically does and name its downstream connections rather than use marketing language.
- Four ownership bands. Explain the CLIENT, RUN, RENT, and CALL ownership bands by crossing who wrote the code with who operates the machine. Relate each band to the control available during an incident: edit RUN, push fixes but not operate CLIENT devices, reconfigure but not patch RENT software, and retry, cache, or route around CALL dependencies.
- Architecture diagram and shape. Describe how the inventory becomes a Mermaid diagram with one node per component, grouped by ownership band, and edges labeled as synchronous or asynchronous and internal or public. Explain that the diagram reveals call direction, trust boundaries, and system shape in a way a flat list cannot.
- Decomposition and failure trade-offs. Distinguish monoliths, modular monoliths, and microservices in terms of deploy units, operational simplicity, team autonomy, and distributed-systems cost. Explain how to ask about failure isolation in measurable blast-radius terms, using Cal.com's Google Calendar failure as an example where affected organizers lose calendar sync but the booking still commits.
- Three-part node documentation. Describe how to document each architecture node with a plain-English role, its concrete underlying technology, and confirmation through a file path and line number.
- Concrete implementation inventory. Explain how the card format converts each generic architecture label into a specific implementation, including libraries, storage systems, protocols, surprising simplifications, and the code that confirms them.
- Database choice constraints. Explain that a database choice locks in consistency, scaling, and failure trade-offs, and describe Cal.com's Postgres-through-Prisma choice as strong, atomic single-primary booking transactions with JSONB and pg_trgm support.
- Cache freshness strategy. Describe a cache as a potentially stale second copy of truth, distinguish cache-aside, write-through, and refresh-ahead trade-offs, and explain Cal.com's Redis availability-cache invalidation strategy.
- End-to-end request trace. Describe how to trace the product’s core user action from the initial user interaction through every service hop to the final response, citing a file and line number for each hop.
- Synchronous response boundary. Explain how the HTTP response, such as 200 OK, divides user-waits work from queued-for-a-worker background work, and mark that boundary in a request trace.
- Runtime path variants. Describe why the same core action can follow different paths for different plan tiers, user states, entry points, feature flags, regions, or connected integrations, and compare at least three representative variants.
- Trace blind spots. Explain why a single-request trace misses collisions and cross-store behavior, and name the follow-up questions about consistency, concurrent writers, and latency budgets that expose those risks.
What it builds on
- An interface is a list of doors (chapter 8) · The distinction between an interface as an entry point and the implementation behind that entry point.
- Trace one endpoint from request to response (chapter 8) · Tracing an endpoint from request to response across code and dependencies.
- Ask for the product in one "It's X, but Y" sentence (chapter 5) · Using a concise, concrete description to orient investigation of a codebase.
- Trace one user action across services (chapter 8) · Tracing one user action across services.
- Every codebase builds for someone, even a library (chapter 5) · The earlier distinction among kinds of codebases provides the starting point for choosing the appropriate architecture model.
- Prune the obvious, then let the LLM pick the rest (chapter 3) · Using repository structure and guided file selection to find relevant files.
- Step 2: Map relationships (1 LLM call) (chapter 3) · Mapping relationships between files and components after an overview.
- Most repos fit. The interesting question is what to do when they don't. (chapter 3) · Adapting repository analysis when the relevant material does not all fit or appear in one obvious place.
Section by section
Introduction
This introduction defines multi-service architecture as a graph to reconstruct and previews a three-step AI process for mapping its components, stacks, and request wiring.
- Multi-service architecture boundary: Distinguish a single-process codebase from a multi-service system, and explain why the latter requires a graph of programs connected over the network. State that a single executable, library, or CLI has module-level architecture, whereas multiple booted programs and their calls form a service graph.
Why it matters: You need to know whether to map modules inside one process or services and network dependencies across a system. - Distributed architecture evidence: Describe the four kinds of evidence used to reconstruct a multi-service architecture: process configuration, environment variables, SDK client initializations, and Terraform state. Explain that local runtime configuration reveals managed internal services, while variables and external integrations reveal dependencies beyond the team’s own processes.
Why it matters: Architecture is usually scattered through configuration and code rather than written in a single architecture document. - Three-step mapping process: Outline the chapter’s architecture-mapping process: identify every component, determine each component’s real technology stack, and trace one request through the wiring. Relate the process to the Cal.com booking example, where one user action can touch applications, dispatchers, databases, and external APIs.
Why it matters: This sequence turns a confusing repository into a usable architectural map instead of an unconnected inventory of files.
Key terms: single-process codebase, multi-service system, service graph, module-level architecture, docker-compose.yml, Procfile, Kubernetes manifests, environment variables, SDK client initializations, Terraform state
9.1 An architecture is a graph of programs and the wires between them
This section defines architecture as a service graph and shows how its nodes, connections, and shape reveal failure risks, trust boundaries, and build-versus-buy choices.
- Service graph model: Explain an architecture as a graph whose nodes are programs that run and whose edges are the communication lines between them. Describe why understanding it means naming the nodes, tracing their wires, and anticipating how each wire can fail.
Why it matters: A service graph gives you a system-level picture before you get lost in individual functions. - Connection failure categories: Classify an edge by whether it is synchronous or asynchronous and whether it stays internal or crosses the public internet. Explain that internal asynchronous work can fail silently after the user receives success, while public synchronous calls put third-party latency and failures on the user's request path.
Why it matters: The kind of connection predicts whether users wait, where security boundaries lie, and how failures appear in production. - Node ownership classification: Describe how asking who operates a node's underlying machine distinguishes what the team controls from what it only configures. Explain that this affects who is paged when it fails and whether engineers can change source code or only configuration.
Why it matters: Ownership tells you where operational responsibility and practical control actually sit. - Common web stack template: Describe the common multi-node web application template: browser to central web server, the server to a database, cache and queue beside it for expensive queries and slow background work, and external APIs for specialized domains. Explain that cache and queue move work off the main synchronous request path.
Why it matters: Recognizing the recurring template helps you form an initial map before inspecting implementation details. - Graph-based design inferences: Explain what the service graph's node count, node labels, and arrow directions reveal: the build-versus-buy ratio and rough reading workload, custom versus commodity code, and inbound, internal, or outbound trust and reliability boundaries. Describe how image versus build directives can provide a quick estimate of commodity versus bespoke components.
Why it matters: These graph clues let you prioritize investigation and identify the most consequential reliability and security boundaries quickly. - Architecture model scope: Distinguish the multi-program service graph of a web application or service from a library or CLI's single-process module graph and a data pipeline or ML run's directed acyclic graph of stages. State that after identifying a single-process system, you should stop searching for a multi-service graph and use the module-oriented approach instead.
Why it matters: Using the wrong architectural model wastes time looking for services that do not exist.
Key terms: architecture, graph, nodes, edges, service graph, synchronous, asynchronous, internal, public internet, internal asynchronous
9.2 Four sources hold the architecture
This section shows how to reconstruct an architecture by combining process declarations, environment configuration, application code, and Infrastructure-as-Code while treating configuration as evidence to verify.
- Four-source architecture map: Explain how compose/process declarations, environment files, application code, and Infrastructure-as-Code combine to reveal different parts of a system's architecture. State the primary evidence each source provides and the blind spot that requires the other sources.
Why it matters: No single configuration file is the architecture, so combining sources prevents you from missing live services and dependencies. - Process declarations and boot dependencies: Describe how compose files, Procfiles, or Kubernetes manifests identify programs that run together, and how depends_on relationships can reveal an internal dependency graph. Distinguish boot-order evidence from proof of every service the system calls.
Why it matters: Boot configuration quickly exposes the locally or jointly deployed parts of a system and their important wiring decisions. - Candidate dependencies and runtime proof: Distinguish environment-variable names as candidate evidence for external dependencies from SDK imports or client construction in application code as evidence that an integration is used. Describe how code can also show whether a call is synchronous in a request, performed by a worker, or sent through an asynchronous queue.
Why it matters: This distinction keeps dead configuration and unused secrets from becoming false edges in your architecture map. - Infrastructure inventory and configuration drift: Describe how Terraform, Pulumi, or CloudFormation inventory managed cloud resources that may not appear in compose or application code. Explain why all configuration is a claim to verify against call sites and runtime conditions, including the effects of stale files, different development and production setups, feature flags, and repository deployment boundaries.
Why it matters: Cloud resources and configuration often outlive or diverge from active code, so verification prevents an inaccurate map during debugging or an incident.
Key terms: process declaration file, compose file, .env, application code, Infrastructure-as-Code, IaC, docker-compose.yml, Docker Compose, Procfile, Kubernetes manifests
9.3 Ask the agent to inventory every part from the config
This section shows how to use an AI agent to build a source-backed architectural inventory, classify each component by ownership, diagram its connections, and investigate the trade-offs revealed by the map.
- Source-backed component inventory: Describe how to ask an agent for an inventory of every runtime program and connection, using configuration as a starting hint but source-code call sites as proof. State that each entry should describe what the component physically does and name its downstream connections rather than use marketing language.
Why it matters: A source-backed inventory gives a new engineer a map of the system that actually runs rather than the smaller system someone intended to run. - Four ownership bands: Explain the CLIENT, RUN, RENT, and CALL ownership bands by crossing who wrote the code with who operates the machine. Relate each band to the control available during an incident: edit RUN, push fixes but not operate CLIENT devices, reconfigure but not patch RENT software, and retry, cache, or route around CALL dependencies.
Why it matters: Knowing the ownership band tells on-call engineers which remedies are possible before they start debugging implementation details. - Architecture diagram and shape: Describe how the inventory becomes a Mermaid diagram with one node per component, grouped by ownership band, and edges labeled as synchronous or asynchronous and internal or public. Explain that the diagram reveals call direction, trust boundaries, and system shape in a way a flat list cannot.
Why it matters: During an incident, the diagram makes it easier to see the dependency path and identify where a failure can cross a boundary. - Build-versus-buy interpretation: Explain how the count and distribution of CLIENT, RUN, RENT, and CALL nodes reveals a system's build-versus-buy strategy and can support a one-sentence shape verdict. Describe Cal.com's distribution as a lean core application acting largely as an integration layer because it outsources payments, video, and calendar capabilities to external APIs.
Why it matters: The ownership distribution helps a developer see which capabilities the team considers differentiating enough to build itself. - Decomposition and failure trade-offs: Distinguish monoliths, modular monoliths, and microservices in terms of deploy units, operational simplicity, team autonomy, and distributed-systems cost. Explain how to ask about failure isolation in measurable blast-radius terms, using Cal.com's Google Calendar failure as an example where affected organizers lose calendar sync but the booking still commits.
Why it matters: A component map becomes operationally useful when you can predict which failures spread globally and which degrade only one feature or user slice.
Key terms: architectural inventory, runtime, source-backed, configuration files, environment variables, downstream nodes, CLIENT, RUN, RENT, CALL
9.4 Open each box to its real tech stack
This section shows how to turn abstract architecture-map nodes into actionable documentation of their real implementations, code locations, and operational trade-offs.
- Three-part node documentation: Describe how to document each architecture node with a plain-English role, its concrete underlying technology, and confirmation through a file path and line number.
Why it matters: This turns a vague diagram label into a description a teammate can verify and act on during debugging. - Concrete implementation inventory: Explain how the card format converts each generic architecture label into a specific implementation, including libraries, storage systems, protocols, surprising simplifications, and the code that confirms them.
Why it matters: Knowing the real primitive prevents wasted debugging effort on systems the application does not actually use. - Cal.com background tasker: Trace Cal.com's tasker as a durable Prisma Task table drained by a Next.js cron route, rather than a Redis or external message broker, and describe its retry and asynchronous-work caveats.
Why it matters: This tells an incident responder where queued work actually runs and why some failed booking side effects may not be retried. - Shared provider interfaces: Explain that Cal.com's external calendar providers implement a common Calendar interface, allowing core booking code to use common operations instead of vendor-specific SDK calls.
Why it matters: This reveals where to look when debugging a provider and why adding another provider can be isolated to an implementation file. - Database choice constraints: Explain that a database choice locks in consistency, scaling, and failure trade-offs, and describe Cal.com's Postgres-through-Prisma choice as strong, atomic single-primary booking transactions with JSONB and pg_trgm support.
Why it matters: Database constraints quietly shape every read path, write path, and operational trade-off in the system. - Cache freshness strategy: Describe a cache as a potentially stale second copy of truth, distinguish cache-aside, write-through, and refresh-ahead trade-offs, and explain Cal.com's Redis availability-cache invalidation strategy.
Why it matters: Cache failures often appear to users as incorrect product state, so freshness rules are essential to debugging them.
Key terms: Plain English, Under the Hood, Confirmation, node inventory, generic label, specific technology, protocol, file path, line number, tasker
9.5 Trace one request across the whole system
This section shows how to trace one core user request through a live architecture, distinguish synchronous from background work, compare runtime variants, and investigate risks a single trace hides.
- End-to-end request trace: Describe how to trace the product’s core user action from the initial user interaction through every service hop to the final response, citing a file and line number for each hop.
Why it matters: A concrete trace turns an inventory of components into an explanation of what the system actually does for one user. - Synchronous response boundary: Explain how the HTTP response, such as 200 OK, divides user-waits work from queued-for-a-worker background work, and mark that boundary in a request trace.
Why it matters: This boundary identifies which operations directly determine perceived latency and which failures can be invisible to the user. - Runtime path variants: Describe why the same core action can follow different paths for different plan tiers, user states, entry points, feature flags, regions, or connected integrations, and compare at least three representative variants.
Why it matters: Comparing variants reveals the runtime execution graph that a static architecture diagram cannot show. - Trace blind spots: Explain why a single-request trace misses collisions and cross-store behavior, and name the follow-up questions about consistency, concurrent writers, and latency budgets that expose those risks.
Why it matters: Many costly production failures appear only when data stores drift, requests race, or a slow synchronous dependency dominates latency. - Cal.com booking safeguards: Explain the Cal.com example’s key findings: Postgres is the source of truth while Redis is disposable, duplicate bookings are stopped by a derived unique idempotency key at insert time, and synchronous provider calls dominate booking latency.
Why it matters: The example demonstrates how a trace and follow-up questions turn abstract architecture risks into concrete code-level conclusions.
Key terms: trace, core action, hop, node inventory, file:line, 200 OK, synchronous, asynchronous, user waits, queued for a worker
9.6 Summary
This summary gives a repeatable way to reconstruct a distributed system’s architecture by combining four evidence sources, inventorying components, investigating each one, and tracing a request end to end.
Concepts explained in this chapter
- build-versus-buy decisionBuild-versus-buy is a software strategy choice between implementing functionality internally and obtaining it from existing components or vendors.
- contractAn external API is an interface exposed by a separately operated system for client software to access its operations or data.
- architectural inventoryAn architectural inventory is a source-grounded list of the runtime components and connections that make up a software system.
- monolithic architectureA monolith is a software system whose major application functionality is developed and deployed as one tightly integrated unit.
- ownership bandAn ownership band classifies a component by who wrote its code and who operates the machine on which it runs.
- synchronous serviceSynchronous work is processing that must finish before the initiating operation can return its result.
- environment variableAn environment variable is a named value supplied through a process environment to configure runtime behavior or provide deployment-specific data.
- consistency modelA consistency model specifies what values concurrent readers and writers are guaranteed to observe in a distributed or concurrent system.
- execution graphAn execution graph is a runtime representation of the components and connections that a particular request actually traverses.
- fan-outFan-out is a pattern in which one operation launches multiple downstream operations, often waiting for several branches to complete.
- percentilep99 latency is the response time below which 99 percent of measured operations complete.
- source of truthA source of truth is the authoritative system or representation from which the accepted value of data is determined.
- tail at scaleTail at scale is the distributed-systems effect in which parallel work completes at the speed of its slowest branch, making high-percentile latency dominate the overall request.
- service-to-service call graphA service graph is a representation of services or processes as nodes and the network calls between them as connections.
- infrastructure as codeInfrastructure as code is the practice of declaring and provisioning infrastructure resources through machine-readable files or programs.
- PostgreSQLPostgreSQL is an open-source object-relational database management system.
- RedisRedis is an in-memory data store commonly used for caching, rate limiting, queues, and other low-latency data operations.
- calendar interfaceA calendar interface is a software contract that standardizes availability and event operations across calendar-provider implementations.
- .env fileAn environment file is a configuration file containing key-value pairs such as service endpoints, credentials, and runtime settings.
- docker-compose.ymldocker-compose.yml is a YAML configuration file that defines and configures services for Docker Compose.
- polyrepoA polyrepo is an architecture in which related software projects or services are maintained in separate repositories.
- attack surfaceA security attack surface is the set of exposed interfaces and entry points through which an unauthorized party could attempt to affect a system.
- directed acyclic graphA directed acyclic graph is a directed graph containing no cycle, so its edges impose a one-way dependency ordering.
- failure modeA failure mode is a specific way in which a software component or interaction can malfunction.
- graphA graph is a mathematical structure consisting of entities represented as vertices and relationships represented as edges.
- queueA queue is an ordered structure in which items are added for later processing, typically in first-in-first-out order.
- trust boundaryA trust boundary is a boundary across which data or control passes between components with different security assumptions.
- black boxA black box is a software component whose internal implementation or reasoning is opaque to its users.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
