Chapter 8: Interfaces: Where the product's verbs live
This chapter introduces a three-level AI-assisted way to turn a tangled API surface into a product-oriented map and trace the paths relevant to a specific change.
After this chapter you will be able to
- Interface as product verbs. Explain why an interface is the set of actions an application exposes externally, and why this makes it the layer where change requests begin. Relate a ticket such as preventing duplicate bookings to finding the handler for the user action rather than merely implementing a small guard.
- Three interface zoom levels. Describe the three reusable AI views introduced in the chapter: a complete feature-grouped endpoint hierarchy, an ordered trace of endpoints for one user gesture, and a request-to-response trace for one endpoint including the services it touches.
- Feature menu reduction. Explain the alternative to reading every handler: group endpoints by what they let users do, ignore framework boilerplate, and drill into only the path touched by the current ticket.
- Interface door model. Explain an interface as a list of doors, where each door has an address, a key, and a procedure that runs when the key is used. Relate this model to web endpoints, CLI commands, and public library functions.
- Schema and interface roles. Distinguish a database schema from an interface: the schema declares what data can exist, while the interface defines the approved operations that can act on that data. Explain why business rules are enforced in procedural handlers rather than appearing in the schema.
- Five-part door structure. Describe the five parts shared by every interface door: address, method, request body, core logic, and return code. Map those parts to the corresponding forms in an API endpoint, a CLI command, and a library function.
- Door-first codebase reading. Justify starting codebase exploration at an interface door instead of a deeply buried helper function. Describe how the door preserves the triggering request and state context, while route names and route groupings reveal product concepts, versioning, and permission boundaries before handler code is read.
- Route manifest purpose. Explain what a route manifest is and why finding it is the fastest way to understand an API or other public interface. State that it provides a complete list of system entry points, such as server URLs, CLI subcommands, or library exports.
- Framework route conventions. Describe the common framework conventions that reveal where routing or public API declarations live. Explain that the route manifest's location is usually a reusable framework convention rather than an obviously named file.
- Routing style tradeoffs. Distinguish filesystem routing, single-file aggregation, decorator-scattered routing, and schema-defined APIs by how difficult they are to survey. Explain that each style has the same objective—one complete list of entry points—even though the effort to produce that list differs.
- Feature menu construction. Describe how to transform a full endpoint inventory into feature groups named for product features, ordered by endpoint count rather than file path or alphabet. State that every endpoint remains listed with its method, path, short purpose, and required authentication tier.
- Product-priority signals. Explain how group sizes, HTTP operation mix, and authentication-tier distribution let you infer product investment, intended audiences, and whether an API mainly serves outsiders or the company’s own UI. Distinguish evidence from conclusions by tying claims back to counts in the menu.
- API versioning strategy. Explain how URL-path versions, date or header versions, and additive-only contracts handle breaking changes differently. Describe Cal.com's two-layer scheme, in which the URL path selects v1 or v2 and a cal-api-version date header pins a v2 client to a specific contract.
- Authentication mechanisms and cost. Distinguish an endpoint's auth tier from its authentication mechanism, and explain how the credential sent over the wire determines the caller's integration cost. Describe the different Cal.com surfaces: unauthenticated public booking, session-cookie web app, apiKey-based v1 REST, and OAuth-based v2 partner API.
- Public and internal API boundary. Explain why the public-versus-internal API boundary is a promise about stability rather than merely a naming distinction. Describe how Cal.com makes REST its documented public contract and tRPC its undocumented, web-app-only private channel without compatibility guarantees.
- Representative action tracing. Describe how to use the API surface and feature groups to trace six to eight representative actions as runtime flows, including read-only, write-heavy, scheduled, and admin-only actions. Explain that the trace follows one action through services in execution order rather than cataloging endpoints by feature.
- Swimlane trace interpretation. Explain what an action swimlane trace should show: the services or feature groups involved, endpoint calls in firing order, the lane that blocks the user’s spinner, and work that begins after the response. Describe why this makes hidden service chains and latency bottlenecks visible.
- Three request phases. Describe the common three-phase shape of a request: edge gating, a small atomic critical section, and asynchronous fan-out after commit and response. Explain the distinct jobs of gates, the transaction, and background follow-up work.
- Outbox reliability gap. Explain the failure gap between committing the core database write and making external side effects, and describe how the outbox pattern closes it. State that the handler writes an outbox event in the same transaction as the core write, then a separate worker drains and retries it after commit.
- Endpoint sequence diagrams. Describe how a sequence diagram represents one endpoint’s exact runtime path, with service lifelines, message arrows, and time flowing from top to bottom. Explain why an LLM can generate this diagram from the route, its flow, and handler source, while a message list remains the precise audit trail.
- Response boundary and fan-out. Explain that the response arrow is the critical boundary between synchronous work the user waits for and asynchronous best-effort work that runs after success is shown. Distinguish the latency and consistency trade-off of moving a dependency from below that line to above it.
- Booking endpoint execution. Trace the important execution order for Cal.com’s POST /api/book/event: gateway checks and payload validation, availability and conflict reads, transactional booking creation, required video-room and calendar creation, the 201 Created response, and post-response notifications. Explain why calendar and video calls remain synchronous: the confirmation needs the meeting link.
- Idempotent booking writes. Explain how Booking.idempotencyKey makes repeated requests for the same booking slot safe: the server deterministically derives a uuidv5 from startTime, endTime, and userId, and a UNIQUE constraint rejects a duplicate insert so the handler can return the existing booking rather than create or charge twice.
- Write-race resolution. Distinguish the three ways to resolve concurrent writes—pessimistic locks, optimistic version checks with retries, and UNIQUE constraints—and explain that Cal.com relies on the unique constraint as the true guard. State that its earlier availability check is soft, while the losing concurrent booking gets a duplicate-key error and a 409 conflict.
What it builds on
- Trace one user action across the tables (chapter 7) · Tracing a user action across schema tables as a way to understand behavior.
- Analyze: The overview-then-zoom-in pattern (chapter 3) · The overview-then-zoom-in analysis pattern.
- Flow trace: One question, 15 files, zero guidance (chapter 4) · Using an agent to trace one flow across many files.
- Different questions for different layers (chapter 3) · Choosing questions appropriate to a particular codebase layer.
- Ask for the product in one "It's X, but Y" sentence (chapter 5) · Summarizing product behavior in user-oriented language.
- A schema is a tidy stack of spreadsheets (chapter 7) · The distinction assumes the earlier view of a schema as a structured representation of stored data.
- One file can't answer cross-file questions. 20 lines fix that. (chapter 2) · Providing selected code or context to ask cross-file questions.
- What the LLM sees determines everything (chapter 3) · Choosing what repository context the LLM sees.
Section by section
Introduction
This chapter introduces a three-level AI-assisted way to turn a tangled API surface into a product-oriented map and trace the paths relevant to a specific change.
- Interface as product verbs: Explain why an interface is the set of actions an application exposes externally, and why this makes it the layer where change requests begin. Relate a ticket such as preventing duplicate bookings to finding the handler for the user action rather than merely implementing a small guard.
Why it matters: Seeing interfaces as product actions helps you start investigation from what users do rather than from scattered code matches. - API accretion and ambiguity: Describe why a mature codebase can contain several coexisting APIs and many old endpoints that touch the same data, making a broad keyword search unable to identify the endpoint a web user actually hits.
Why it matters: This explains why reading handlers one by one or trusting an ungrounded AI answer is slow and unreliable. - Three interface zoom levels: Describe the three reusable AI views introduced in the chapter: a complete feature-grouped endpoint hierarchy, an ordered trace of endpoints for one user gesture, and a request-to-response trace for one endpoint including the services it touches.
Why it matters: The three zoom levels let you narrow from an overwhelming API inventory to the exact path relevant to your ticket. - Feature menu reduction: Explain the alternative to reading every handler: group endpoints by what they let users do, ignore framework boilerplate, and drill into only the path touched by the current ticket.
Why it matters: A feature menu converts hundreds of files into a focused investigation of a few relevant paths.
Key terms: API surface, endpoints, interface, user action, coexisting APIs, handlers, REST, tRPC, route, top-down view
8.1 An interface is a list of doors
This section frames interfaces as the system’s entry doors, showing how their common structure exposes approved product operations and provides the best starting point for codebase exploration.
- Interface door model: Explain an interface as a list of doors, where each door has an address, a key, and a procedure that runs when the key is used. Relate this model to web endpoints, CLI commands, and public library functions.
Why it matters: Seeing interfaces as doors gives you one reusable way to orient yourself in APIs, command-line tools, and libraries. - Schema and interface roles: Distinguish a database schema from an interface: the schema declares what data can exist, while the interface defines the approved operations that can act on that data. Explain why business rules are enforced in procedural handlers rather than appearing in the schema.
Why it matters: You need both the data model and its allowed operations to understand what a product actually does and what rules govern changes. - Five-part door structure: Describe the five parts shared by every interface door: address, method, request body, core logic, and return code. Map those parts to the corresponding forms in an API endpoint, a CLI command, and a library function.
Why it matters: The five-part structure lets you read unfamiliar routes, command help, and public functions with the same checklist despite framework-specific syntax. - Door-first codebase reading: Justify starting codebase exploration at an interface door instead of a deeply buried helper function. Describe how the door preserves the triggering request and state context, while route names and route groupings reveal product concepts, versioning, and permission boundaries before handler code is read.
Why it matters: Starting from an entry point lets you follow downstream calls with the user intent and system context that make their behavior meaningful. - HTTP interface vocabulary: State that web handlers use HTTP methods, status codes, and headers as their operating vocabulary, and explain that methods can reject unsupported requests while status codes communicate distinct outcomes such as successful creation versus a duplicate conflict.
Why it matters: Recognizing this compact vocabulary lets you interpret what an endpoint accepts and how it reports its result.
Key terms: interface, door, address, key, procedure, web endpoint, database schema, declarative, procedural, business logic
8.2 Find the route manifest in any framework
This section shows how to find and read a codebase's route manifest to map every exposed entry point and infer product history from its interface structure.
- Route manifest purpose: Explain what a route manifest is and why finding it is the fastest way to understand an API or other public interface. State that it provides a complete list of system entry points, such as server URLs, CLI subcommands, or library exports.
Why it matters: A route manifest gives you the product's exposed capabilities without forcing you to reconstruct them handler by handler. - Framework route conventions: Describe the common framework conventions that reveal where routing or public API declarations live. Explain that the route manifest's location is usually a reusable framework convention rather than an obviously named file.
Why it matters: Knowing the convention lets you locate an unfamiliar codebase's public surface quickly instead of searching blindly. - Routing style tradeoffs: Distinguish filesystem routing, single-file aggregation, decorator-scattered routing, and schema-defined APIs by how difficult they are to survey. Explain that each style has the same objective—one complete list of entry points—even though the effort to produce that list differs.
Why it matters: The routing style tells you whether a file listing, one aggregator file, or a broader handler scan is needed to map the API. - Mixed surface discovery: Describe how to use an LLM to identify surface files from a repository or, for a large repository, from its file tree. Explain that mature codebases can combine routing styles, so all relevant surface conventions must be included in the map.
Why it matters: This lets you efficiently find the complete interface even when public and internal APIs use different technologies. - Interface structure as history: Explain what route and directory patterns can reveal about past product decisions: sibling action files, side-by-side version directories, and parallel transports. State that the surface layer is thin but valuable because it shows what the team chose to expose for people to do.
Why it matters: Reading interface structure reveals product evolution and exposed capabilities before you dive into the much larger backend implementation.
Key terms: route manifest, entry point, surface area, public interface, config/routes.rb, urls.py, urlpatterns, include(), routes.ts, router.ts
8.3 Map the whole API surface into a feature menu
This section shows how to turn a complete route inventory into a count-ranked feature menu and tour that exposes a product’s real priorities.
- Feature menu construction: Describe how to transform a full endpoint inventory into feature groups named for product features, ordered by endpoint count rather than file path or alphabet. State that every endpoint remains listed with its method, path, short purpose, and required authentication tier.
Why it matters: A complete, count-ranked menu gives a new engineer a usable map of a large API instead of an unsearchable route dump. - Appropriate analysis scope: Explain that the feature-menu technique is for an API surface too large to comprehend at once, not a tiny CLI or small library. Describe why route definitions, unlike implementation bodies, can usually be sent together in one LLM pass.
Why it matters: Using the technique at the right scale avoids unnecessary analysis while letting one prompt cover a large product surface. - Product-priority signals: Explain how group sizes, HTTP operation mix, and authentication-tier distribution let you infer product investment, intended audiences, and whether an API mainly serves outsiders or the company’s own UI. Distinguish evidence from conclusions by tying claims back to counts in the menu.
Why it matters: The route surface can reveal the business and operational priorities that a README or marketing page leaves out. - Guided product tour: Describe the companion guided tour as a short three-to-six-step narrative through the most revealing feature groups, beginning with user or product meaning rather than code details. State that later steps transition to a newly uncovered surface, such as a different audience, write pattern, or admin-only area, rather than merely recapping earlier groups.
Why it matters: A tour turns a reference inventory into an onboarding story that helps a beginner see what matters first. - Cal.com surface interpretation: State how the Cal.com example uses the menu to show that scheduling is only about 17% of its 295 endpoints when Bookings & Availability and Event Types are combined, while teams, administration, integrations, and newer capabilities occupy most of the surface. Explain that the counts support the interpretation of Cal.com as more than a simple scheduling application.
Why it matters: The example demonstrates how a route inventory can overturn the first impression created by a product’s marketing.
Key terms: feature menu, API surface, endpoint, authentication tier, public, signed-in user, LLM pass, route definitions, controller bodies, endpoint count
8.3.1 Three design questions to ask once you have the menu
This subsection shows how to interpret an API feature menu by examining versioning, authentication, and the public-versus-internal boundary as design choices that determine integration cost and stability.
- API versioning strategy: Explain how URL-path versions, date or header versions, and additive-only contracts handle breaking changes differently. Describe Cal.com's two-layer scheme, in which the URL path selects v1 or v2 and a cal-api-version date header pins a v2 client to a specific contract.
Why it matters: Versioning tells you whether an integration will survive product changes or become a legacy maintenance burden. - Authentication mechanisms and cost: Distinguish an endpoint's auth tier from its authentication mechanism, and explain how the credential sent over the wire determines the caller's integration cost. Describe the different Cal.com surfaces: unauthenticated public booking, session-cookie web app, apiKey-based v1 REST, and OAuth-based v2 partner API.
Why it matters: The authentication mechanism reveals how much work a caller must do before it can make a useful API call. - Public and internal API boundary: Explain why the public-versus-internal API boundary is a promise about stability rather than merely a naming distinction. Describe how Cal.com makes REST its documented public contract and tRPC its undocumented, web-app-only private channel without compatibility guarantees.
Why it matters: Knowing which interface is a public contract prevents you from building against an internal implementation detail that can change at any time.
Key terms: URL path versioning, date header, additive-only contract, breaking change, cal-api-version, maintenance mode, auth tier, authentication mechanism, session cookie, API key
8.4 Trace one user action across services
This section shows how to trace representative user actions across services and use those traces to uncover request phases, reliability gaps, and user-visible latency.
- Representative action tracing: Describe how to use the API surface and feature groups to trace six to eight representative actions as runtime flows, including read-only, write-heavy, scheduled, and admin-only actions. Explain that the trace follows one action through services in execution order rather than cataloging endpoints by feature.
Why it matters: A small, diverse set of runtime traces exposes the service chains behind most of a product’s core workflows. - Swimlane trace interpretation: Explain what an action swimlane trace should show: the services or feature groups involved, endpoint calls in firing order, the lane that blocks the user’s spinner, and work that begins after the response. Describe why this makes hidden service chains and latency bottlenecks visible.
Why it matters: Knowing which calls are on the critical path tells you where a slow dependency becomes a slow product experience. - Three request phases: Describe the common three-phase shape of a request: edge gating, a small atomic critical section, and asynchronous fan-out after commit and response. Explain the distinct jobs of gates, the transaction, and background follow-up work.
Why it matters: Separating these phases lets you reason about where invalid requests stop, where state becomes durable, and where delayed failures can occur. - Outbox reliability gap: Explain the failure gap between committing the core database write and making external side effects, and describe how the outbox pattern closes it. State that the handler writes an outbox event in the same transaction as the core write, then a separate worker drains and retries it after commit.
Why it matters: Without durable handoff, a crash can preserve the main record while silently losing notifications, calendar syncs, or other side effects. - Fan-out diagnostic questions: State the three questions to ask beyond a simple trace: whether fan-out work is persisted before workers attempt it, how failed webhooks retry and end up in a dead-letter destination, and which calls are synchronous versus background. Apply these questions to distinguish reliability behavior from user-visible latency.
Why it matters: A flow diagram shows that work exists, but these questions reveal whether it can be lost, how failures recover, and what slows the user down.
Key terms: feature menu, API surface, runtime trace, user action, swimlane diagram, lanes, lane, endpoint event, synchronous, asynchronous
8.5 Trace one endpoint from request to response
This section shows how to generate and read a per-endpoint sequence diagram, then use its response boundary and database guards to reason about latency, failures, retries, and booking races.
- Endpoint sequence diagrams: Describe how a sequence diagram represents one endpoint’s exact runtime path, with service lifelines, message arrows, and time flowing from top to bottom. Explain why an LLM can generate this diagram from the route, its flow, and handler source, while a message list remains the precise audit trail.
Why it matters: A sequence diagram turns a dense handler into an inspectable story of which services a request actually touches and in what order. - Response boundary and fan-out: Explain that the response arrow is the critical boundary between synchronous work the user waits for and asynchronous best-effort work that runs after success is shown. Distinguish the latency and consistency trade-off of moving a dependency from below that line to above it.
Why it matters: Knowing which side of the response line a call occupies tells you whether it affects the spinner, can report an error to the user, or needs recovery outside the request. - Booking endpoint execution: Trace the important execution order for Cal.com’s POST /api/book/event: gateway checks and payload validation, availability and conflict reads, transactional booking creation, required video-room and calendar creation, the 201 Created response, and post-response notifications. Explain why calendar and video calls remain synchronous: the confirmation needs the meeting link.
Why it matters: This concrete trace shows how to locate the real blocking path and separate required booking creation from follow-up notification work. - Idempotent booking writes: Explain how Booking.idempotencyKey makes repeated requests for the same booking slot safe: the server deterministically derives a uuidv5 from startTime, endTime, and userId, and a UNIQUE constraint rejects a duplicate insert so the handler can return the existing booking rather than create or charge twice.
Why it matters: Idempotency is the protection that makes browser retries and double-clicks safe for a write endpoint. - Write-race resolution: Distinguish the three ways to resolve concurrent writes—pessimistic locks, optimistic version checks with retries, and UNIQUE constraints—and explain that Cal.com relies on the unique constraint as the true guard. State that its earlier availability check is soft, while the losing concurrent booking gets a duplicate-key error and a 409 conflict.
Why it matters: The actual concurrency guard, not an earlier availability read, determines whether a new write path remains correct under simultaneous requests.
Key terms: sequence diagram, UML sequence diagram, lifeline, Mermaid sequenceDiagram, synchronous messages, async tasks, response arrow, synchronous, asynchronous, fan-out
8.6 Summary
This summary presents interfaces as stable entry-point maps and recaps a scalable LLM workflow for turning an API, CLI, or library surface into product understanding.
Where this is used later
- Trace one request across the whole system (chapter 9) · Extends request tracing from an endpoint path to the whole system.
- (chapter intro) (chapter 9) · The distinction between an interface as an entry point and the implementation behind that entry point.
- Summary (chapter 9) · Tracing a user action across services as a way to understand system behavior
- Four sources hold the architecture (chapter 9) · Following execution from an endpoint request through its implementation.
Concepts explained in this chapter
- idempotency keyAn idempotency key is a value that identifies logically identical operations so repeated attempts can be detected and prevented from creating duplicate effects.
- contractAn external API is an interface exposed by a separately operated system for client software to access its operations or data.
- endpointAn API endpoint is a specific network-accessible operation or resource exposed by an API at a defined route.
- HTTP status codeAn HTTP status code is a standardized numeric response classification indicating the outcome of an HTTP request.
- fan-outFan-out is a pattern in which one operation launches multiple downstream operations, often waiting for several branches to complete.
- swim laneA swimlane diagram is a process diagram that separates activities into lanes representing participants or services and orders events across a sequence.
- UML sequence diagramA sequence diagram is a diagram that represents interactions among participants in temporal order.
- authentication levelAn authentication tier is a permission classification such as public, user, or administrator access.
- critical sectionA critical section is the portion of execution that performs a coordinated state change requiring atomicity or concurrency control.
- edge gatingEdge gating is the practice of rejecting invalid, abusive, or unauthorized requests before they reach application state-changing logic.
- idempotency guardAn idempotency guard prevents repeated processing of the same logical request from creating duplicate state changes.
- outbox eventAn outbox event is a persistent database record describing an external side effect that a worker must deliver after a transaction commits.
- outbox patternA transactional outbox is a technique that records a database change and its associated event in the same transaction before a separate process delivers the event.
- service chainA service chain is an ordered sequence of services that participate in completing one request or user action.
- MermaidMermaid is a text-based diagramming tool and syntax for generating diagrams from declarative descriptions.
- concurrency controlConcurrency control is the set of mechanisms that coordinates simultaneous operations to preserve correctness when they access shared data.
- database transactionA database transaction is a unit of database operations that is committed or rolled back as a whole.
- unique constraintA unique constraint requires one or more database columns to contain a value combination that is not duplicated by another row.
- feature menuA feature menu is an organized view of an API surface that groups endpoints by user-facing product features.
- route manifestA route manifest is a file or declaration that enumerates the entry points exposed by a software system.
- HTTP methodAn HTTP method is a standardized verb specifying the intended operation of an HTTP request.
- business logicA business rule is a domain-specific condition or policy that governs how a system should behave.
- interface addressAn interface address is the identifier that selects an operation, such as a URL path, CLI subcommand, or qualified function name.
- aggregator routerAn aggregator router is a routing component that consolidates multiple procedures or handlers into a single readable routing definition.
- file-system based routingFile-based routing is a routing pattern in which filesystem paths determine the URL paths or other externally accessible routes.
- entry pointAn entry point is a file or function through which an application starts execution or initializes its major components.
- tutorialA guided tour is a narrative explanation that walks a reader through related product features in a meaningful sequence.
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.
