📚 Software Architecture Study Guide

Interfaces & Architecturally Significant Requirements (ASRs)

Welcome! Let's Get You Ready 🚀

What This Quiz is About

Your quiz covers two main topics:

  1. Software Interfaces - How different parts of a system communicate
  2. ASRs (Architecturally Significant Requirements) - Requirements that actually shape the system's architecture

Don't worry! I'll explain everything step-by-step, using the xBank withdrawal service example your professor provided.

🎯 Learning Path: We'll start with the basics, build up to complex concepts, then practice with real examples. Take your time with each section!
1
Learn Interfaces
2
Master YAML
3
Study xBank
4
Understand ASRs
5
Practice & Quiz

Understanding Software Interfaces 🔌

What is an Interface?

Think of an interface like a contract between two parts of a system. It's a boundary that defines:

  • What services are offered (provided interface)
  • What services are needed (required interface)
  • How they communicate (data formats, protocols)
  • What happens when things go wrong (error handling)

🏪 Real-Life Analogy

Think of a restaurant:

  • Provided Interface: The menu (what the kitchen offers)
  • Required Interface: What the kitchen needs (ingredients from suppliers)
  • Interaction: You order (request), waiter brings food (response)
  • Error Handling: "Sorry, we're out of that dish"

Key Interface Concepts

1. Provided vs Required Interfaces

Provided Interface ○

Services the component OFFERS

  • What I can do for you
  • Shown as a lollipop (○) in diagrams
  • Example: ATM's withdrawal API

Required Interface ⊂

Services the component NEEDS

  • What I need from others
  • Shown as a socket (⊂) in diagrams
  • Example: Needs database connection

2. Three Types of Interfaces

Type When What it Defines Example
Design-Time Compile-time, between modules/classes Function signatures, preconditions, logic Java method: executeDebit(String id, Decimal amt)
Runtime When system is running, across processes APIs, data formats, error codes REST API: POST /withdraw
Connector Network/gateway level Protocols, timeouts, quality attributes HTTPS, timeout 2500ms, 99.99% availability
💡 Key Insight: "What" vs "How"
  • What: Runtime spec says "send account ID and amount"
  • How: Connector spec says "send via HTTPS with JSON format and 2.5s timeout"

Interface Scope & Design Principles

Gateways - The Mediator

A gateway sits between components to:

  • Translate interfaces - Convert between different formats
  • Restrict resources - Control what's accessible
  • Stabilize interfaces - Shield internal changes from external users

Example: xBank ATM Gateway

ATMs don't talk directly to the bank's internal systems. A gateway:

  • Handles authentication (checks if you're a valid user)
  • Routes requests to the right internal service
  • Protects internal system details from the ATM

Interaction Styles

Synchronous (Sync)

  • I wait for your response
  • Like a phone call
  • Example: Withdrawal must know success/failure immediately

Asynchronous (Async)

  • I don't wait, continue my work
  • Like sending an email
  • Example: Log events to monitoring system

Data Representation

When components communicate, they need to agree on data format:

Format Pros When to Use
JSON Human-readable, widely supported REST APIs, web services
XML Structured, schema validation Enterprise systems, SOAP
Protocol Buffers Fast, compact, binary High-performance systems, gRPC

Error Handling

Errors are PART OF THE INTERFACE! You must specify:

  • What errors can occur
  • What they mean
  • How they're communicated
# xBank Error Specification errors: - code: 402 meaning: "Insufficient Funds" - code: 404 meaning: "Account ID Invalid" - code: 500 meaning: "Internal server error"

YAML for Architecture Documentation 📝

What is YAML?

YAML (YAML Ain't Markup Language) is a human-readable data format used to document architectures.

Why YAML for Architecture?
  • ✅ More readable than JSON (no brackets everywhere)
  • ✅ Supports comments (unlike JSON)
  • ✅ Machine-parsable (unlike pure text docs)
  • ✅ Less verbose than XML

YAML Syntax Basics

1. Key-Value Pairs (Mappings)

name: Ahmad role: DevOps Engineer graduated: false

2. Lists (Sequences)

courses: - Mathematics - Physics - Software Architecture

3. Nested Structures

student: id: 1 name: Ahmad courses: - Mathematics - Physics

4. Comments

# This is a comment - very useful for documentation! interface_type: REST-API # inline comment

5. Multiline Strings

# Literal (|) - preserves newlines validation_logic: | if (amount > balance) { throw InsufficientFunds; } # Folded (>) - turns into one line notes: > This interface is specifically designed for xBank internal use and follows the security protocols defined in the 2025 audit.

6. Anchors & Aliases (Reuse)

# Define once with & standard_quality: &quality_defaults latency_p95: 200ms availability: "99.99%" # Reuse with * service_quality: *quality_defaults
⚠️ YAML Gotchas:
  • Indentation MATTERS! Use spaces, NOT tabs
  • One wrong space breaks everything
  • Quote strings with special characters: "@#$%"

🎯 Try It Yourself!

Write YAML to describe yourself as a student:

  • Your name
  • Your major (Computer Science)
  • A list of at least 2 courses
  • Whether you're currently working (true/false)
Hint: Remember to use proper indentation! 
student:
  name: Ahmad
  major: Computer Science
  courses:
    - Software Architecture
    - DevOps
  working: true

xBank Withdrawal Service - Complete Walkthrough 🏦

The Scenario

xBank is building a microservice to handle cash withdrawals from ATMs.

Key Players:

  • WithdrawalService - The service we're documenting
  • ATM Terminal - External client (needs withdrawal service)
  • Core Banking Ledger - Internal system (withdrawal service needs this to update balances)
  • API Gateway - Sits between ATM and WithdrawalService
The Question: How do we document this service's interfaces?
The Answer: THREE different interface specifications!

1. Design-Time Interface (Module Level)

Purpose: Documents the internal logic and function signatures

# Documentation of internal logic and code-level signatures design_time_interfaces: - id: DT-xBank-Logic kind: module-interface level: design-time # Defined during coding phase # Syntax: Function name and parameters operations: - name: executeDebit signature: "Receipt executeDebit(String accId, Decimal amt)" # Semantics: Behavior and business rules semantics: state_changes: - "Decrements account balance in the database" errors: - "NegativeAmountException: Thrown if amt <= 0"
When to use: For documenting internal modules/classes that work together inside the same process

2. Runtime Interface (Component Level)

Purpose: Documents the public API contract across process boundaries

# The public contract for cross-process communication runtime_interfaces: - id: RT-xBank-API kind: service-api level: runtime # Used when system is live # Provided vs Required (Slide 5) provided_by_component: WithdrawalService required_by_components: - ATM_Terminal - Mobile_App_User # Needs this from environment to provide its service requires_from_environment: - id: Central_Ledger_Service # Interaction Style: Sync required for banking (Slide 21) interaction: style: sync # Synchronous call for immediate ledger lock pattern: request-reply # Data Representation: Agreed format for interoperability (Slide 26) data: format: JSON # Error Handling Agreement (Slide 30) errors: - code: 402 meaning: "Insufficient Funds" - code: 404 meaning: "Account ID Invalid"
Key Difference from Design-Time:
  • Design-time = internal Java function signature
  • Runtime = external HTTP API endpoint

3. Connector Interface (Gateway Level)

Purpose: Documents HOW communication happens (protocols, timeouts, quality)

# Documentation of network and gateway 'plumbing' (Slide 20) connector_interfaces: - id: CN-xBank-Gateway kind: connector-interface level: connector # Reliability: Fault handling and delivery guarantees (Slide 5) reliability: timeout_ms: 2500 retries: 0 # Crucial: prevent double-withdrawal on network lag delivery: exactly-once idempotency: true # Quality Attributes: Performance guarantees (Slide 5) quality: latency: "200ms P95" # 95% of transactions under 0.2s availability: "99.999%"

🤔 Why retries: 0?

Banking is special! If a withdrawal request times out on the network but actually went through, retrying could withdraw money TWICE from the account. So xBank disables retries and relies on idempotency (same request ID = same result).

Putting It All Together

Interface Type Answers Example from xBank
Design-Time What functions exist? What do they do? executeDebit(String accId, Decimal amt)
Runtime What data is exchanged? What errors occur? JSON format, error code 402 = insufficient funds
Connector How is it sent? How fast? How reliable? HTTPS, timeout 2500ms, no retries, 99.999% available
💡 The Big Insight: "What" vs "How" (Slide 3)
  • Runtime spec = WHAT data (account ID, amount)
  • Connector spec = HOW it's sent (HTTPS, JSON, timeout)

Architecturally Significant Requirements (ASRs) ⚡

What is an ASR?

Not all requirements affect architecture. ASRs are the special subset that fundamentally shape the system's structure.

🎯 The Test: If removing a requirement would change your components, connectors, or deployment strategy → It's an ASR!

ASR vs Non-ASR

ASR ✅ Non-ASR ❌
"System must handle 10,000 concurrent users"
→ Affects architecture (need load balancers, caching)		 "Login button should be blue"
→ Just UI, no architectural impact
"99.99% uptime required"
→ Affects architecture (need redundancy, failover)		 "User profile shows photo"
→ Feature, not architectural

ASRs and Quality Attributes

Most ASRs are about quality attributes (non-functional requirements):

Performance

  • Response time
  • Throughput
  • Latency

Availability

  • Uptime percentage
  • Zero-downtime deploys
  • Fault tolerance

Modifiability

  • Easy to change
  • Add features quickly
  • Update without breaking

Security

  • Authentication
  • Authorization
  • Data encryption

The Problem: Vague Requirements

Requirements documents often have statements like:

❌ "The system shall be fast" ❌ "The system shall be user-friendly" ❌ "The system shall be modular"
⚠️ Why These Are Bad:
  • Not measurable - how fast is "fast"?
  • Don't guide design - what structure makes it "modular"?
  • Can't verify - how do you test "user-friendly"?

Quality Attribute Scenarios - The Solution

Transform vague requirements into concrete scenarios with 6 parts:

Part Description Example
Source Who/what generates the stimulus Hospital staff member
Stimulus What happens Submits patient data update
Artifact What part of system is affected Patient administration subsystem
Environment Under what conditions Peak working hours
Response What the system does System processes the update
Response Measure How you measure success Completes within 1 second

Complete Scenario Example

Performance Scenario:

A hospital staff member (source) submits an administrative data update (stimulus) to the patient administration subsystem (artifact) during peak working hours (environment). The system processes the update (response) and completes within 1 second (response measure).

From Scenarios to ASRs

Once you have a scenario, convert it to an ASR by adding:

  • Business Value: High (H), Medium (M), or Low (L)
  • Technical Risk: High (H), Medium (M), or Low (L)

ASR-1 (Performance)

Requirement: The system shall support concurrent administrative updates during peak working hours such that each update transaction completes within 1 second.

  • Business Value: H - Directly affects daily operations
  • Technical Risk: H - Requires careful concurrency handling

The Utility Tree

A utility tree is a tool to organize and prioritize ASRs when you don't have complete requirements.

Utility (System Success)
├── Performance
│   ├── Transaction Response Time
│   │   └── [H,H] Staff updates complete within 1s during peak hours
│   └── Throughput
│       └── [M,M] System handles 150 transactions/sec
├── Availability
│   ├── Uptime
│   │   └── [H,L] 99.99% availability, 24/7/365
│   └── Zero-Downtime Deployment
│       └── [H,L] Updates applied without interrupting operations
└── Modifiability
    └── Report Format Changes
        └── [M,M] Report changes completed within 1 working day
💡 How to Read [H,H]:
  • First letter: Business Value (H = High priority for business)
  • Second letter: Technical Risk (H = High risk to implement)
  • [H,H] scenarios are your PRIMARY architectural drivers!

Step-by-Step: Requirements → ASRs

1
Read the Requirements Paragraph

Look for hints about quality attributes

2
Identify Quality Attributes

Signals: "peak hours", "revised several times", "without interrupting"

3
Create Concrete Scenarios

Use the 6-part format (Source, Stimulus, Artifact, Environment, Response, Response Measure)

4
Rate Business Value & Technical Risk

Assign H, M, or L to each

5
Write the ASR Statement

"The system shall..." with measurable criteria

Practice Exercises ✍️

Exercise 1: Identify Interface Types

Read each description and identify if it's a Design-Time, Runtime, or Connector interface:

A. Java method signature: public Receipt processPayment(String cardId, double amount)

B. HTTP REST API: POST /api/payment with JSON body containing cardId and amount

C. Gateway specification: HTTPS protocol, 3000ms timeout, retry policy: exactly-once delivery

Exercise 2: Write a YAML Runtime Interface

Scenario: You're building a "LoginService" that provides authentication for a mobile app. Write the runtime interface YAML including:

  • ID and kind
  • Provided by component (LoginService)
  • Required by components (MobileApp)
  • Interaction style (sync)
  • Data format (JSON)
  • At least 2 error codes
Example Solution: 
runtime_interfaces:
  - id: RT-LoginService-API
    kind: service-api
    level: runtime
    
    provided_by_component: LoginService
    required_by_components:
      - MobileApp
    
    interaction:
      style: sync
      pattern: request-reply
    
    data:
      format: JSON
    
    errors:
      - code: 401
        meaning: "Invalid credentials"
      - code: 429
        meaning: "Too many login attempts"

Exercise 3: Convert Requirement to ASR

Requirement: "The e-commerce system must handle Black Friday traffic where thousands of users browse and purchase simultaneously. The system should remain responsive even during peak load."

Step 1: What quality attribute is this about?

Step 2: Create a concrete scenario. Fill in the blanks:

Source:

Stimulus:

Environment:

Response Measure:

Final Quiz 🎓

Your Progress

0%

Score: 0 / 10

1. What does an interface define? (Select all that apply)

2. In C&C notation, which symbol represents a PROVIDED interface?

3. Why does xBank set retries to 0 in the connector interface?

4. What is the difference between design-time and runtime interfaces?

5. What makes a requirement "architecturally significant"?

6. A quality attribute scenario has 6 parts. Which is NOT one of them?

7. In YAML, what does the anchor symbol (&) do?

8. Which interaction style requires the caller to wait for a response?

9. In a utility tree, what does [H,H] mean?

10. What is the main purpose of a Gateway in interface design?