Skills

Software Architecture Design Document

8 weeks · 0 milestones

Produce a software architecture document for a real or realistic system covering: a component diagram showing at least 4 logical components with named interfaces, an interface specification for each inter-component communication (message format, protocol, error handling), documented architectural decisions with at least 3 alternatives considered per major decision and explicit trade-off rationale, and a quality attribute analysis (how the architecture addresses 2 chosen quality attributes such as scalability, fault tolerance, or security). Diagrams produced using draw.io (free), Lucidchart free tier, or PlantUML (free, text-based). Proof artifacts: the architecture document with diagrams (design artifact) and a documented trade-off rationale for the primary architectural decisions (documentation artifact). Accessible: draw.io and PlantUML are fully free; no hardware or software license required. Verification: a senior software engineer or architect challenges 'why did you choose this component boundary?' and 'what breaks first when load doubles?' — you must answer in terms of the specific system, not general principles.

Part of: Engineering · Proves for: Engineers, UG

Milestone map

3 milestones

Define Architectural Drivers and Quality Attributes

1–2 weeks (3–4 hrs/week)

Identify the architectural drivers for a real or realistic software system: functional requirements that drive architectural decisions, quality attributes (performance, scalability, security, maintainability, availability), and constraints (technology stack mandates, team size, regulatory requirements, budget). For each quality attribute, define a quality attribute scenario in the format: stimulus → system response → measurable response measure. These scenarios are the testable criteria that your architecture must satisfy — an architecture without quality attribute scenarios is untestable.

Proof required

Submit your architectural drivers document (≥600 words): the system context (what the software does and who uses it), ≥5 functional requirements that drive architectural decisions, ≥4 quality attribute scenarios in stimulus/response/measure format, and ≥2 architectural constraints.

What gets checked

Quality attribute scenarios are in stimulus/response/measure format — not statements like 'the system should be fast'
≥4 quality attributes are addressed — not all performance, at least 3 different quality dimensions
Constraints distinguish between technology mandates (must use) and preferences (prefer to use)

Common mistakes

Quality attributes stated without measurable response measures — 'the system should be scalable' is not a quality attribute scenario; 'the system shall serve 10,000 concurrent users at 95th-percentile response time < 500 ms' is
Confusing constraints with preferences — a constraint is an absolute limit (must comply with GDPR); a preference is a trade-off (prefer React for the frontend)

Resources

Foundationstart here

Depthgo deeper

What a verifier looks for

Confirm quality attribute scenarios are in stimulus/response/measure format — flag any stated as aspirations.
Confirm ≥4 different quality dimensions are addressed — flag if all are performance.
Confirm constraints distinguish between absolute mandates and preferences.

You'll sign in first, then come straight back here.

Design and Document the System Architecture

3–4 weeks (4–5 hrs/week)

Design the system architecture to satisfy the quality attribute scenarios from M1. Document the architecture using ≥3 views: (1) a Context diagram (C4 Level 1 or UML deployment view) showing the system and its external users/systems; (2) a Container diagram (C4 Level 2 or UML component view) showing the main deployable units and their responsibilities; (3) a Component or Sequence diagram showing how a key functional requirement flows through the architecture at runtime. Justify the major architectural decisions (e.g. microservices vs monolith, synchronous vs event-driven, relational vs NoSQL) using Architecture Decision Records (ADRs) — one ADR per major decision.

Proof required

Submit ≥3 architecture diagrams (context, container, and one dynamic or component view) and ≥2 ADRs: each ADR states the decision, the alternatives considered, the chosen option, and the rationale referencing the quality attribute scenarios from M1.

What gets checked

≥3 views are provided — context + container + one dynamic/component view — not just one diagram
≥2 ADRs document major architectural decisions with alternatives considered and quality attribute rationale
Architecture diagrams use a named notation (C4, UML, or equivalent) and include a legend

Common mistakes

A single diagram that conflates multiple views — context, containers, and component interactions should be separate views because they serve different audiences
ADRs that state a decision without documenting the alternatives — the value of an ADR is the rejected options and their trade-offs; an ADR that only records what was decided is a log, not an architectural document

Resources

Foundationstart here

Depthgo deeper

What a verifier looks for

Confirm ≥3 distinct views are present — context, container, and one dynamic or component view.
Confirm ≥2 ADRs document alternatives considered and quality attribute rationale — flag ADRs that only record decisions.
Confirm diagrams use a named notation with a legend.

You'll sign in first, then come straight back here.

Write the Architecture Document and Present for Review

2–3 weeks (2–3 hrs/week)

Assemble the complete Software Architecture Document (SAD) combining M1 drivers, M2 diagrams, and ADRs. The SAD should include: executive summary, system context, architectural drivers (quality attribute scenarios), architecture views (context, container, component), ADRs, risks and technical debt (what was deliberately deferred and why), and deployment notes (environment requirements, scaling strategy). Have the document reviewed by a senior software engineer or software architect and respond to Q&A on the major architectural decisions and their quality attribute trade-offs.

Proof required

Submit your Software Architecture Document (≥2,000 words, including all M1 drivers, M2 diagrams, ≥2 ADRs, and a risks/technical debt section) and review record: reviewer name, role, ≥3 challenge questions about architectural decisions or trade-offs, and your responses.

What gets checked

Risks and technical debt section names ≥2 deliberate deferrals with an explicit rationale — not a statement that no technical debt was incurred
Reviewer has senior software engineering or architecture experience and challenged the architectural decisions or trade-offs specifically
The SAD links architectural decisions back to the quality attribute scenarios from M1 — not free-standing decisions

Common mistakes

Technical debt section that says 'there is no technical debt' — all real systems incur deliberate deferrals; a section claiming zero debt either means the assessment was not honest or the system was not real
Reviewer without senior engineering experience — Q&A on microservices trade-offs, event-driven consistency challenges, or database sharding decisions requires domain depth

Resources

Foundationstart here

Depthgo deeper

What a verifier looks for

Engineering Design Triad check: M1–M3 together produce a design artifact (architecture views + ADRs), an analysis artifact (quality attribute scenarios + trade-off analysis), and a documentation artifact (SAD + review record) — confirm all three types are present.
Confirm risks and technical debt section names ≥2 deliberate deferrals with rationale — flag zero-debt claims.
Confirm architectural decisions are linked back to the quality attribute scenarios from M1.
Confirm reviewer has senior software engineering or architecture experience and challenged decision trade-offs specifically.
The Proof Accessibility Rule applies — arc42 (free), C4 model (free), draw.io (free), CMU SEI free resources, and Michael Nygard ADR format (free) are all accessible without commercial licence.

You'll sign in first, then come straight back here.

Part of

Software Engineering Foundations →

Related outcomes

Milestone map

3 milestones

Define Architectural Drivers and Quality Attributes

1–2 weeks (3–4 hrs/week)

Proof required

What gets checked

Quality attribute scenarios are in stimulus/response/measure format — not statements like 'the system should be fast'
≥4 quality attributes are addressed — not all performance, at least 3 different quality dimensions
Constraints distinguish between technology mandates (must use) and preferences (prefer to use)

Common mistakes

Quality attributes stated without measurable response measures — 'the system should be scalable' is not a quality attribute scenario; 'the system shall serve 10,000 concurrent users at 95th-percentile response time < 500 ms' is
Confusing constraints with preferences — a constraint is an absolute limit (must comply with GDPR); a preference is a trade-off (prefer React for the frontend)

Resources

Foundationstart here

Depthgo deeper

What a verifier looks for

Confirm quality attribute scenarios are in stimulus/response/measure format — flag any stated as aspirations.
Confirm ≥4 different quality dimensions are addressed — flag if all are performance.
Confirm constraints distinguish between absolute mandates and preferences.

You'll sign in first, then come straight back here.

Design and Document the System Architecture

3–4 weeks (4–5 hrs/week)

Proof required

What gets checked

≥3 views are provided — context + container + one dynamic/component view — not just one diagram
≥2 ADRs document major architectural decisions with alternatives considered and quality attribute rationale
Architecture diagrams use a named notation (C4, UML, or equivalent) and include a legend

Common mistakes

A single diagram that conflates multiple views — context, containers, and component interactions should be separate views because they serve different audiences
ADRs that state a decision without documenting the alternatives — the value of an ADR is the rejected options and their trade-offs; an ADR that only records what was decided is a log, not an architectural document

Resources

Foundationstart here

Depthgo deeper

What a verifier looks for

Confirm ≥3 distinct views are present — context, container, and one dynamic or component view.
Confirm ≥2 ADRs document alternatives considered and quality attribute rationale — flag ADRs that only record decisions.
Confirm diagrams use a named notation with a legend.

You'll sign in first, then come straight back here.

Write the Architecture Document and Present for Review

2–3 weeks (2–3 hrs/week)

Proof required

What gets checked

Risks and technical debt section names ≥2 deliberate deferrals with an explicit rationale — not a statement that no technical debt was incurred
Reviewer has senior software engineering or architecture experience and challenged the architectural decisions or trade-offs specifically
The SAD links architectural decisions back to the quality attribute scenarios from M1 — not free-standing decisions

Common mistakes

Technical debt section that says 'there is no technical debt' — all real systems incur deliberate deferrals; a section claiming zero debt either means the assessment was not honest or the system was not real
Reviewer without senior engineering experience — Q&A on microservices trade-offs, event-driven consistency challenges, or database sharding decisions requires domain depth

Resources

Foundationstart here

Depthgo deeper

What a verifier looks for

Engineering Design Triad check: M1–M3 together produce a design artifact (architecture views + ADRs), an analysis artifact (quality attribute scenarios + trade-off analysis), and a documentation artifact (SAD + review record) — confirm all three types are present.
Confirm risks and technical debt section names ≥2 deliberate deferrals with rationale — flag zero-debt claims.
Confirm architectural decisions are linked back to the quality attribute scenarios from M1.
Confirm reviewer has senior software engineering or architecture experience and challenged decision trade-offs specifically.
The Proof Accessibility Rule applies — arc42 (free), C4 model (free), draw.io (free), CMU SEI free resources, and Michael Nygard ADR format (free) are all accessible without commercial licence.

You'll sign in first, then come straight back here.