Metadata Card

• Prerequisites: Chapter 2 (Abstract Data Types)
• Estimated Time: 40 minutes
• Core Difficulty: Foundation-building
• Completion Milestone: Be able to transform user requirements into architectural decisions, understand the MVP mindset

Your Progress

You've learned how to build components correctly (Chapter 1) and how to organize data so it's not misused (Chapter 2). But before you build anything, you need to answer: what should you build?

In the City of Artisans, a customer asks a craftsman for a "sword, two-handed, Damascus steel, with a red leather grip." The craftsman asks three questions before picking up a hammer:

1. "What will you use it for?" (never trust the customer's solution — understand their problem)
2. "How soon do you need it?" (deadline affects approach)
3. "How much can you spend?" (resources constrain design)

These are requirements. And the answers to these questions shape the architecture. Your Task

This chapter covers the transition from problem to design: requirements analysis, prioritization, architectural decision-making, and the MVP mindset. Not the "write 200 pages of requirements document" school—the "understand the problem well enough to make good architectural trade-offs" school.

Chapter tiers

• Required reading: Requirements classification (functional/non-functional), user stories, MVP
• Selective: Architectural patterns overview
• Advanced: Architectural decision records (ADR)

This chapter won't require you to master

• UML diagram syntax
• Enterprise architecture frameworks (TOGAF, Zachman)

---

Breaking Ground · Tracing the Source

A product manager comes to you: "We need a real-time leaderboard for the tournament system."

Your first instinct: "OK, I'll build a sorted data structure, update it on every score change, push updates via WebSocket."

But ask three questions first:

1. "How many users?" — "Maybe 100 concurrent."
2. "Is real-time to the millisecond necessary?" — "No, within 5 seconds is fine."
3. "Is this for MVP or post-launch?" — "Post-launch, we have a simpler list version working."

Now you have different architecture options. For 100 users with 5-second tolerance, you don't need WebSocket and Redis sorted sets. A simple periodic poll with a cached JSON endpoint will do. 50 lines of code instead of 500.

Requirements analysis prevents over-engineering.

First Layer: Functional vs Non-Functional Requirements

Functional requirements describe what the system does — features, behaviors, capabilities.

FR-1: Players can register for a tournament
FR-2: The system tracks scores per player
FR-3: Players can view their match history

Non-functional requirements (quality attributes) describe how the system performs — constraints on the solution.

NFR-1: Page load time < 2 seconds (Performance)
NFR-2: 99.9% uptime during tournament hours (Availability)
NFR-3: Player data encrypted at rest (Security)
NFR-4: Supports 1000 concurrent users (Scalability)
NFR-5: New tournament types can be added without modifying core code (Extensibility)

Non-functional requirements drive architecture decisions far more than functional ones. A leaderboard system functions the same whether it serves 10 users or 10,000, but the architecture is completely different.

Second Layer: User Stories — From Feature List to User Value

User stories transform "the system shall..." statements into "as a [role], I want [goal], so that [benefit]."

As a tournament organizer,
I want to set max player limits,
so that I can control match duration and quality.

The format forces you to think about who, what, and why. The "why" is the most important part — it prevents building features nobody asked for.

Third Layer: MVP — The Minimum You Can Ship

"Build for what you know today, design so you can change what you learn tomorrow."

MVP doesn't mean "low quality." It means the smallest set of functionality that delivers value and lets you learn.

Scenario: Tournament notification system.

MVP:
  - Email notification when match starts
  - Hard-coded email template
  - Synchronous sending (blocking call)

Version 2 (after learning users want SMS and push):
  - Abstract notification channel
  - Async sending with queue
  - Template system

If we'd built the full version 2 at the start, we'd have wasted
weeks building "flexibility" for notifications users didn't want.

The YAGNI principle: You Aren't Gonna Need It. Build what you need now, design so you can add what you need later.

Fourth Layer: Architecture Decisions

An architecture decision should be documented when:

1. It's hard to reverse — choosing a database technology
2. It has wide impact — choosing a framework affects all developers
3. Multiple options exist with different trade-offs — synchronous vs event-driven

Architecture Decision Record (ADR) format:

# ADR-001: Use PostgreSQL as primary data store

## Context
We need a relational data store for tournament, player, and score data.
Options considered: PostgreSQL, MySQL, MongoDB.

## Decision
Use PostgreSQL.

## Rationale
- Team has strongest PostgreSQL experience
- JSONB support allows flexible schema for tournament configurations
- Better full-text search support than MySQL
- No need for MongoDB's horizontal scaling (current data volume fits in single node)

## Consequences
- (+) Strong consistency, ACID transactions
- (+) Rich type system (enums, arrays, composite types)
- (-) Vertical scaling only (may need read replicas later)
- (-) Schema changes require migrations (not schemaless)

## Status
Accepted

ADRs are not bureaucracy — they're memory for future-you. Six months later, when someone asks "why did we pick PostgreSQL?", you have the answer written down.

Fifth Layer: Static Architecture Diagrams

Before you write code, draw boxes. The diagram doesn't need to be UML-perfect, but it must show:

• Components (services, databases, external APIs)
• Connections (protocol, direction, data flow)
• Boundaries (what's inside your system, what's outside)

A C4 model works well:

Level 1: System Context — a box for your system, boxes for external systems
Level 2: Container — services, databases, message queues
Level 3: Component — classes, modules, interfaces
Level 4: Code — you don't need to draw this unless you're in a design review

Most architecture discussions should happen at Levels 1-2. Don't draw class diagrams before you've agreed on whether the system communicates via REST or events.

---

Common Pitfalls

Pitfall 1: Building what the customer said, not what they need. The customer asks for a "garage," but what they need is "shelter from rain for their car at night." You might build a carport cover that's 1/10 the cost.

Pitfall 2: Gold-plating the MVP. "We need a full caching layer, event-driven architecture, Kubernetes cluster, and five microservices" for a prototype serving 10 users. Start simple, only add complexity when measurements prove you need it.

Pitfall 3: Not documenting architecture decisions. "Who decided to use MongoDB? Nobody remembers. Why? Nobody knows. Can we change it? Maybe, but everyone's afraid."

Pitfall 4: Treating requirements as immutable. Requirements change. That's normal. Don't treat them as sacred text. Design your system so that new requirements don't require a rewrite.

---

Passing Challenges

• Warm up: Take a feature request from your current project. Write a user story for it. Then write 3 questions that help you understand the real need behind the request.
• Challenge: Write an Architecture Decision Record for a technology choice you made recently (or plan to make). Follow the ADR format above.
• Observe: Pick a large open-source project (Kubernetes, Apache Kafka). Look at their docs — do they have any architecture docs or ADRs? How do they document design decisions?

---

Traveler's Notes

Requirements analysis is the blueprint phase. It doesn't produce code — it produces understanding. Functional vs non-functional scope tells you "what" and "how well," user stories tell you "who benefits," MVP thinking tells you "what to build now vs later," and ADRs capture "why we made these choices." Armed with this understanding, you can now make architecture decisions that are deliberate, not accidental.

---

Preview of Next Chapter

You have a blueprint. Now you need to ensure the forge produces the right output. Before you build a single component, you need a safety net that catches mistakes before they reach production. Next: Testing Strategies.