Unit 7.1 · Tutorial 1

Requirements & Architecture Planning

Chapter 21 · Capstone Project
~2.5 hours Intermediate Requirements · C4 Model · ADR

Overview

Every successful project starts with a solid plan. This tutorial covers the critical first phase of your capstone project: gathering requirements, defining user stories, writing functional specifications, and creating architecture diagrams using the C4 model. You will also learn about Architectural Decision Records (ADRs) to document your design choices.

Why this matters: A well‑planned architecture saves countless hours of rework. Clear requirements and documentation ensure your team (and stakeholders) are aligned on what you're building and why.

1. Gathering Requirements

Requirements define what the system should do. They come from stakeholders, users, and business objectives.

Types of requirements

  • Functional: What the system does (e.g., "Users can create an account.").
  • Non‑functional: How the system performs (e.g., "Page load time < 2 seconds.").
  • Business: Strategic goals (e.g., "Support 10,000 concurrent users.").
// Example requirements for an e‑commerce app // Functional - Users can register and log in - Users can browse products by category - Users can add items to a shopping cart - Users can check out and pay // Non‑functional - API response time < 200ms p95 - Support 1000 concurrent users - 99.9% uptime - Secure: HTTPS, JWT authentication
Tip: Use the MoSCoW method to prioritise: Must‑have, Should‑have, Could‑have, Won't‑have.

2. User Stories & Use Cases

User stories describe features from the user's perspective. They follow the format: "As a [role], I want [action] so that [benefit]."

// Example user stories for an e‑commerce app As a **shopper**, I want to **browse products by category** so that I can **find what I'm looking for quickly**. As a **shopper**, I want to **add items to my cart** so that I can **purchase multiple items at once**. As a **registered user**, I want to **save my shipping address** so that I can **check out faster next time**. As an **admin**, I want to **add and update products** so that the **catalogue stays current**.

Use cases go deeper, describing the step‑by‑step flow of a user interaction.

3. Functional Specifications

A functional specification (or spec) translates user stories into detailed technical requirements. It includes:

  • Endpoints: API routes, methods, and request/response formats.
  • Data models: Entities and their relationships.
  • Business logic: Validation, calculations, and workflows.
  • User flows: Step‑by‑step interaction sequences.
// Example: Register user endpoint spec Endpoint: POST /api/auth/register Request Body: { "email": "user@example.com", "password": "secure123", "name": "John Doe" } Validation: - email: valid email format, unique - password: min 8 chars, at least one number Response (201 Created): { "id": 1, "email": "user@example.com", "name": "John Doe", "createdAt": "2026-09-01T12:00:00Z" } Error (400 Bad Request): { "message": "Email already registered" }

4. C4 Architecture Model

The C4 model provides a structured way to visualise architecture at four levels, each with a different audience:

  • Level 1: System Context – The system and its users (for executives).
  • Level 2: Containers – High‑level services (frontend, backend, database).
  • Level 3: Components – Internal building blocks of each container.
  • Level 4: Code – Classes and functions (for developers).
// Level 1: System Context (text diagram) [User] ---> [E‑Commerce App] ---> [Payment Gateway] | +--> [Email Service] // Level 2: Containers [React App] ---> [Node.js API] ---> [PostgreSQL DB] | +--> [Redis Cache] // Level 3: Components (API) [Auth Controller] ---> [User Service] ---> [User Repository] [Product Controller] ---> [Product Service] ---> [Product Repository] [Order Controller] ---> [Order Service] ---> [Order Repository]
Tools: Use draw.io, Lucidchart, or Structurizr (C4‑native) to create diagrams.

5. Architectural Decision Records (ADR)

ADRs document important design decisions. They help future developers understand why certain choices were made.

# ADR 001: Select React for Frontend ## Context We need a frontend framework for the e‑commerce app. Options include: React, Vue.js, and Angular. ## Decision We will use React. ## Rationale - Largest ecosystem and community - Team has experience with React - Excellent performance with Virtual DOM - Strong TypeScript support ## Consequences - Must use JSX or TSX - Need to choose a state management library (Redux/Zustand) - Larger bundle size than vanilla JS (but manageable) ## Status Accepted

Quiz

Question 1

What does the "C" in the C4 model stand for?

  • Code
  • Container
  • Component
  • All of the above (Context, Container, Component, Code)
Show answer
D. All of the above – Context, Container, Component, Code.

Question 2

Which requirement type defines how the system performs (e.g., response time)?

  • Functional
  • Non‑functional
  • Business
  • Technical
Show answer
B. Non‑functional.

Question 3

What is the purpose of an Architectural Decision Record (ADR)?

  • To track bugs
  • To document design decisions and their rationale
  • To store user passwords
  • To generate code
Show answer
B. To document design decisions and their rationale.

Exercises

Exercise 1

Write 3 user stories for a food delivery app (customer side). Use the "As a... I want... so that..." format.

Sample answer
  • As a hungry customer, I want to browse restaurants by cuisine so that I can find food I'm craving.
  • As a hungry customer, I want to track my order in real‑time so that I can know when to expect my food.
  • As a repeat customer, I want to reorder my favourite meal so that I can save time.

Exercise 2

Write a simple C4 Level 2 (Containers) diagram for a blog platform with users, posts, comments, and a database.

Sample answer
[React App] ---> [Node.js API] ---> [PostgreSQL DB] | +--> [Redis Cache] // Components (Level 3) for the API: [Auth Controller] ---> [User Service] ---> [User Repository] [Post Controller] ---> [Post Service] ---> [Post Repository] [Comment Controller] ---> [Comment Service] ---> [Comment Repository]

Homework

Homework 1

For your capstone project idea, write a complete set of functional requirements (at least 10) and create a Level 2 (Containers) C4 diagram.

Sample outline
  • Requirements: List 10+ functional requirements for your project.
  • Containers: Identify the main containers (e.g., React app, Node.js API, PostgreSQL DB).
  • Diagram: Draw connections between containers with arrows showing data flow.
  • Justification: Explain why you chose each container technology.

Mini‑Project

Architecture Planning for Your Capstone

Create a comprehensive architecture plan for your capstone project:

  • Write 5–10 user stories
  • Define functional and non‑functional requirements
  • Create C4 Level 1 (System Context) and Level 2 (Containers) diagrams
  • Write at least 3 ADRs for key decisions (e.g., framework choice, database choice)
Sample outline
  • Project name: Your capstone project name
  • User stories: 5–10 stories covering core features
  • Requirements: List of functional and non‑functional requirements
  • C4 diagrams: Use draw.io or similar to create diagrams
  • ADRs: Document at least 3 decisions with context, decision, and rationale

Tutorial Summary

You learned the essential planning phase of the capstone project: gathering requirements, writing user stories, defining functional specifications, creating C4 architecture diagrams, and documenting decisions with ADRs. This foundation will guide the entire implementation.

Key takeaway: Good architecture is planned, not emergent. Invest time in planning and documentation to ensure a smooth development process and a successful capstone project.