Connecting the Pieces

Almost every meaningful application is built from multiple components that must work together: a user interface that displays data fetched from a server, a server that reads and writes a database, a notification system that triggers when a record changes. Each component may work perfectly in isolation. The moment you try to connect them, a new class of problem appears — not bugs inside a component, but failures at the boundaries between components. This lesson is about those boundaries.

Interfaces: The Contract Between Components

An interface (in the architectural sense used here) is an explicit agreement between two components about how they will communicate. It specifies: - What the caller sends: the name, type, and constraints of every input. - What the callee returns: the structure, type, and possible values of every output. - What happens on error: how failures are communicated back to the caller. Interfaces must be defined before either component is built — not discovered after the fact by reading the code. When two components are built to separate, pre-agreed interfaces, connecting them is straightforward. When they are built without such an agreement, connecting them requires reading both implementations, finding the mismatches, and fixing them — a much slower and more error-prone process. Concrete example: consider a front-end component that displays a list of expenses and a back-end route that fetches them. The interface between them might read: Request: GET /expenses?month=2026-04 Response (success, HTTP 200): { status: "ok", data: [ { id: string, amount: number, category: string, date: string, note: string | null } ] } Response (error, HTTP 500): { status: "error", message: string } With this interface agreed on, the front-end developer and the back-end developer (or the two separate prompting sessions that build them) can work independently without coordination beyond the interface itself.

When connecting components in practice, the integration phase has three steps: Step 1 — Verify the interface on each side. Before writing any connection code, check: does the back-end actually return the format specified in the interface? Does the front-end actually send the request in the format the back-end expects? Do this by reading the code on each side against the written interface specification. Step 2 — Test the connection in isolation. Connect only two components at a time, with the simplest possible data. For a web app, use a tool like curl or Postman to send a test request to the back-end and confirm the response matches the interface. Then connect the front-end to the back-end with a hardcoded test case before adding real data. Step 3 — Identify and fix mismatches. Mismatches are nearly inevitable. The amount field is returned as a string '12.50' but the front-end expects a number 12.50. The date field is returned as a full ISO timestamp but the front-end expects just the YYYY-MM-DD part. Each mismatch must be fixed either in the producer (the component sending the data) or the consumer (the component receiving it) — and that decision should be recorded in your project brief. AI assistance in the integration phase is particularly valuable for writing the small transformation functions that convert data from one format to another. These are tedious to write by hand, well-specified (you know the input format and output format exactly), and straightforward for the AI to generate correctly given precise input and output descriptions.

Common Integration Failures and How to Prevent Them

Four integration failures appear repeatedly in AI-assisted projects: 1. Type mismatch: one component sends a string, the other expects a number. Prevention: specify types explicitly in every interface definition. 2. Field name mismatch: one component uses 'categoryName,' the other uses 'category.' Prevention: define field names in the interface, not in the components independently. 3. Error-handling gap: a component fails silently (returns null or undefined instead of an error message) and the other component crashes because it receives something unexpected. Prevention: always define the error case in the interface. 4. Timing mismatch: one component assumes the other has already fetched data by the time it runs, but the fetch is asynchronous and may not be complete. Prevention: design interfaces to make asynchronous flow explicit (the component that needs data must wait for the fetch to complete before using the result). Each of these is a design problem, not a coding problem. They are best caught at the interface review stage, before either component is implemented.