Practice: Technical scoping, design docs and solution architecture for customer engagements
Generated by Claude through GigAI 0.1.11.10 on 2026-10-11.
Main tool: AWS · AWS publishes the Well-Architected Framework and a set of decision guides whose criteria and comparison tables give you real material for scoping, recording decisions and reviewing a design, all from a laptop and without running paid resources. · Alternatives: Azure Well-Architected Framework and Google Cloud Architecture Framework offer similar pillar-based review guidance for their own clouds; adr-tools scaffolds decision records from the command line but gives no selection criteria; Structurizr, Mermaid and PlantUML render C4 diagrams as code but do not help choose what goes in the boxes; Google Docs or Markdown on GitHub hold the design doc itself and its review history.
Every step links into the tool's own documentation; links were checked on 2026-10-11 · version 1
Setup (one time)
1. Sign in to the AWS Management Console with a free tier account; nothing in this path needs a paid resource, and if you have no account you can work from the documentation alone.
The console is where you would later look up services and run a formal review, so you should know how to reach it. No step here creates billable resources.
Explained in: What is the AWS Management Console? - AWS Management Console (docs.aws.amazon.com), checked 2026-10-11
Done when: You see the console home page after signing in, or you have noted that you will follow the path from the documentation only.
2. Read how AWS security credentials work and confirm you are signed in as a non-root identity.
Customer engagements start with access questions, and a scoping document must state who holds which credentials. Knowing the credential types lets you write that section accurately.
Explained in: AWS General Reference - AWS General Reference (docs.aws.amazon.com), checked 2026-10-11
Done when: You can name the credential type you signed in with and it is not the root user.
3. Create a local Git repository with a Markdown design doc skeleton, a decisions folder and a diagrams folder, and add a review section with one heading per pillar of the framework.
Every later step writes into this repository, so the design doc, the decision records and the diagrams stay versioned together. The pillar headings come from the framework introduction.
Explained in: AWS Well-Architected Framework - AWS Well-Architected Framework (docs.aws.amazon.com), checked 2026-10-11
Done when: The repository holds a design doc file with empty sections for scope, requirements, decisions, architecture, cost and one review heading per pillar.
Steps
1. Write a one-page scoping brief for a sample engagement, such as a document question answering assistant for a customer support team, listing what is in scope, what is out of scope, assumptions and the two trade-offs you expect to argue about.
Scoping turns a vague request into a bounded commitment, and the framework introduction gives you the vocabulary of trade-offs between pillars. Naming the trade-offs up front tells the customer where decisions will be needed.
Explained in: AWS Well-Architected Framework - AWS Well-Architected Framework (docs.aws.amazon.com), checked 2026-10-11
Done when: The scope section of the design doc lists in-scope items, out-of-scope items, assumptions and two named trade-offs.
2. Write the requirements section of the design doc by answering each compute criterion in the decision guide for your sample workload.
A useful design doc states requirements before solutions. The guide's criteria are a ready checklist of questions to put to a customer.
Explained in: Choosing an AWS compute service - AWS Decision Guides (docs.aws.amazon.com), checked 2026-10-11
Done when: The requirements section has one answered line per criterion in the guide, with unknowns marked as open questions.
3. Compare the compute options in the guide against your answers and write the options-considered section of the design doc with one chosen option and two rejected ones.
Reviewers trust a design doc that shows the alternatives and why they lost. The comparison table gives you the facts to do that.
Explained in: Choosing an AWS compute service - AWS Decision Guides (docs.aws.amazon.com), checked 2026-10-11
Done when: The design doc names one chosen compute option and two rejected options, each with a one-line reason tied to a requirement.
4. Write your first architecture decision record for the compute choice, with status, context, decision and consequences, using the serverless section as evidence for the context.
A decision record captures one decision in a form that outlives the engagement. The guide supplies the facts; the record format is your own short Markdown file in the decisions folder.
Explained in: Choosing an AWS compute service - AWS Decision Guides (docs.aws.amazon.com), checked 2026-10-11
Done when: The decisions folder holds a numbered record whose consequences section lists at least one cost you accept.
5. Write a second decision record for which generative AI service the assistant uses, drawn from the choose table in the generative AI guide.
For this role the model service is usually the most contested decision. Writing it down with its alternatives stops it being reopened in every meeting.
Explained in: Choosing a generative AI service - AWS Decision Guides (docs.aws.amazon.com), checked 2026-10-11
Done when: A second numbered record exists and names the chosen service, the alternatives considered and the condition that would make you revisit it.
6. Write a third decision record for the data store, then mark it as superseded by a fourth record after you change one requirement, such as adding a need for semantic search.
Decision records are never edited after acceptance; they are superseded. Practising that once shows how a decision history stays honest.
Explained in: Choosing an AWS database service - AWS Decision Guides (docs.aws.amazon.com), checked 2026-10-11
Done when: The third record shows status superseded and links to the fourth, which shows status accepted.
7. Create a C4 system context diagram and a container diagram in Mermaid in the diagrams folder, with the customer's users and existing systems outside the boundary and your chosen services as containers.
The context level is for customer stakeholders and the container level is for engineers. The integration guide helps you identify which external systems and message flows must appear.
Explained in: Choosing an AWS application integration service - AWS Decision Guides (docs.aws.amazon.com), checked 2026-10-11
Done when: Two diagrams render in your Markdown preview, and every container in the second maps to a service named in a decision record.
8. Label every arrow between containers with the integration service or pattern you pick from the guide, and add a short key under the diagram.
Unlabelled arrows hide the hardest parts of a design. Choosing queue, event bus or workflow for each one forces the integration decisions into the open.
Explained in: Choosing an AWS application integration service - AWS Decision Guides (docs.aws.amazon.com), checked 2026-10-11
Done when: No arrow in the container diagram is unlabelled, and the key explains each integration choice in one line.
9. Write the cost section of the design doc, stating how the customer will track and cap spend and which cost trade-off you made against performance or reliability.
A scoped commitment without a cost view is not bounded. The guide's criteria tell you what to ask about budgets, visibility and ownership.
Explained in: Choosing an AWS cost management strategy - AWS Decision Guides (docs.aws.amazon.com), checked 2026-10-11
Done when: The cost section names a tracking approach, a budget owner and one explicit trade-off with its reasoning.
10. Run a pillar review of the finished design doc by writing, under each pillar heading, one strength, one risk and one follow-up action; the AWS Well-Architected Tool in the console can hold the same review at no charge if you have an account.
Checking against the standard pillars catches gaps a single author misses. It also gives the customer a familiar frame for the review meeting.
Explained in: AWS Well-Architected Framework - AWS Well-Architected Framework (docs.aws.amazon.com), checked 2026-10-11
Done when: Every pillar heading has a strength, a risk and an action, and at least one risk has led to a change in the design doc or a new decision record.
11. Create a reusable engagement template in the repository from the criteria you used, then reproduce the requirements and options sections for a second scenario where the customer already runs containers.
A forward deployed engineer repeats this process for every customer, so it must be repeatable. Rerunning it on a different workload proves the template works and is not tied to one design.
Explained in: Choosing an AWS container service - AWS Decision Guides (docs.aws.amazon.com), checked 2026-10-11
Done when: A template folder exists, and a second design doc built from it reaches a different compute decision with its own record.
12. Reproduce the full pack for a production-like variant in which part of the workload must stay in the customer's own data centre, updating the scope, the decision records, the C4 diagrams and the pillar review.
Real engagements come with constraints such as data residency and existing hardware. Reworking the whole pack under one hard constraint is the closest laptop substitute for a production engagement.
Explained in: Choosing an AWS container service - AWS Decision Guides (docs.aws.amazon.com), checked 2026-10-11
Done when: The repository holds a complete second pack in which the on-premises constraint is visible in the scope, in at least one decision record, in the container diagram and in the pillar review.
Back to Technical scoping, design docs and solution architecture for customer engagements