Technical scoping, design docs and solution architecture for customer engagements

Generated by Claude through GigAI 0.1.11.10 on 2026-10-11.

Concept: Technical scoping · also covers System design and architecture, Solutions architecture · Step 2 of 34 in AI forward deployed engineer · version 1

Practice this

On this page

Scoping turns a customer's stated need into a bounded technical commitment, and the design document is where the trade-offs behind that commitment are written down and reviewed. This lesson covers the structure of a useful design doc, how to record individual decisions, how to draw architecture at the right level for each audience, and how to check a design against standard quality pillars.

Read more

How it is done in practice

After discovery, the FDE writes a one-page scope and a short design doc in a shared document tool, with a C4 context and container diagram embedded. The customer's architect and security lead comment directly on the doc, and a review meeting resolves the open threads. Decisions that came out of the review are recorded as numbered ADR files in the engagement repository. Before build starts, the team walks the design through the quality pillars and records gaps as risks. The doc is updated when implementation diverges and is given to the customer's operating team at handover together with the ADR log.

Technologies

Google DocsMarkdownadr-toolsStructurizrMermaidPlantUMLAWS Well-Architected ToolGitHub

Diagram

flowchart TB
  U[Customer operations user] --> W[Web app]
  subgraph S[Deployed solution]
    W --> API[API service]
    API --> Q[Worker and LLM orchestration]
    API --> DB[(Application database)]
  end
  Q --> LLM[Model provider API]
  Q --> CRM[Customer CRM]
  API --> IDP[Customer identity provider]
  Q --> DWH[(Customer data warehouse)]
flowchart TB
  U[Customer operations user] --> W[Web app]
  subgraph S[Deployed solution]
    W --> API[API service]
    API --> Q[Worker and LLM orchestration]
    API --> DB[(Application database)]
  end
  Q --> LLM[Model provider API]
  Q --> CRM[Customer CRM]
  API --> IDP[Customer identity provider]
  Q --> DWH[(Customer data warehouse)]

Code

markdown
# ADR 0007: Use the customer's warehouse as the retrieval source

## Status
Accepted

## Context
Source documents already land in the customer warehouse nightly.
Security review does not allow a second copy outside their network.

## Decision
Read documents through a read-only warehouse role and build the
index inside the customer's cloud account.

## Consequences
- No new data egress path to review.
- Freshness is bounded by the nightly load.
- Index rebuild cost is paid on the customer's account.

Subtopics

Scoping an engagement and making trade-off calls

From request to commitment

Scoping starts by restating the customer's problem in measurable terms, then listing constraints: data location, identity provider, network boundaries, compliance regime, latency budget, and who will operate the system. Each requirement is classified as must, should or out. The output is a one-page scope with goals, explicit non-goals, assumptions, dependencies on the customer, and the main risks. An FDE is expected to make most trade-off calls alone, so the discipline is to write each call down with its reasoning, so that it can be challenged later without relitigating from memory.

The design document

Sections that matter

The format described for Google design docs is informal but consistent. Context and scope gives the reader the background facts briefly. Goals and non-goals lists what the system will do and what it deliberately will not. The design section presents an overview first, usually with a system-context diagram, then APIs, data storage and the degree of constraint the solution operates under. Alternatives considered explains why other reasonable designs were rejected. Cross-cutting concerns covers security, privacy and observability. The emphasis is on trade-offs, not on an implementation manual.

When and how long

A design doc is worth writing when the solution is ambiguous, when senior review can catch an expensive mistake, or when several teams must agree. If the answer is obvious, skip it and prototype. For a customer engagement, a short doc of a few pages is usually enough, and it should be readable by the customer's architects. The lifecycle is draft and rapid iteration, review, implementation with updates as reality diverges, and a final pass so the doc remains an accurate entry point for whoever operates the system.

Architecture decision records

One decision per record

An architecture decision record (ADR) captures a single significant decision in a short text file kept in the repository. The widely used template by Michael Nygard has a title, a status such as proposed, accepted or superseded, the context that forced the decision, the decision itself, and its consequences, including the negative ones. Records are numbered and never rewritten: a changed decision gets a new record that supersedes the old one. In customer work, ADRs are valuable at handover, because they explain why the system looks the way it does.

Drawing architecture with the C4 model

Four levels of zoom

The C4 model gives four hierarchical diagram types. A system context diagram shows the system as one box with its users and the external systems it talks to. A container diagram opens that box into separately deployable or runnable units such as a web app, an API, a worker and a database. A component diagram shows the major building blocks inside one container. A code diagram shows classes and is rarely worth maintaining by hand. Supplementary views include system landscape, dynamic and deployment diagrams.

Use in customer engagements

The context and container levels do most of the work. The context diagram is the one to show executives and security reviewers, because it makes every data flow across the customer boundary visible. The container diagram is what the customer's platform team needs to plan networking, identity and hosting. Each element should carry a name, a technology and a one-line responsibility, and every line should be labeled with what flows and over which protocol. A deployment diagram is added when the customer hosts the system.

Reviewing a design against quality pillars

Pillars as a checklist

The AWS Well-Architected Framework organizes design review around six pillars: operational excellence, security, reliability, performance efficiency, cost optimization and sustainability. Each pillar has design principles and questions. In a customer engagement the pillars work as a structured walkthrough of the proposed solution with the customer's architects: how is it deployed and observed, who can access what, what happens when a dependency fails, where are the latency and throughput limits, what does it cost per unit of work. Gaps become tracked risks with owners instead of surprises at security review.

Sources

Related lessons

Practice this
The forward deployed delivery model: from signed scope to go-liveMapping customer workflows and choosing what to automate with AI