Agile، Scrum، UML و مهندسی نیازمندیAgile, Scrum, UML & Requirements Engineering

Almost every backend job ad contains a clause engineers skim past: "familiar with Agile and Scrum", "proficient with Jira", "able to analyse and document requirements", "knowledge of UML". Then, in the interview, that clause turns into questions that are harder to answer than a tricky concurrency problem — because nobody ever taught you this material. You just sat in meetings for years while nobody explained why they existed.

The gap between a mid-level and a senior engineer shows up more in this layer than in the code layer. Both can write an endpoint. But when a vague request arrives from the business, one asks "what should I code?" and the other asks "what is the real problem, how will we know it is solved, which part can ship this week, and what are we giving up?" None of this is "the manager's job". Mature organisations expect the engineer to challenge a requirement, slice a story, write acceptance criteria, record the decision, and improve both the code and the person in a review.

1. Why "process" is an engineering skill

Three engineering — not managerial — reasons process matters. The cost of a requirements mistake grows exponentially: a misunderstanding that one question in analysis would have resolved turns into a data migration and lost trust once it reaches production. Software work is inherently uncertain: you are building something you have not built before, so you need short feedback and course correction. And organisational memory does not live in people: people leave; tickets, ADRs, runbooks and tests remain.

2. The software development lifecycle: from waterfall to Agile

SDLC is the order in which software moves from idea to retirement: requirements, design, implementation, testing, delivery, maintenance. The models differ only in how those phases are arranged and how often they repeat.

2.1 Waterfall

Do each phase once, in order, and do not enter the next phase until the previous one is signed off. A nice historical detail: the famous paper that first drew this diagram described the single-pass model as risky and recommended running it at least twice — the diagram survived, the warning did not.

The one-way waterfall flow — مسیر یک‌طرفه‌ی آبشار.

flowchart LR
  A[Requirements] --> B[Design]
  B --> C[Implementation]
  C --> D[Verification]
  D --> E[Deployment]
  E --> F[Maintenance]

The fundamental problem is feedback timing: the first moment a real user sees the software is after the entire budget has been spent.

2.2 The V-model and iterative-incremental development

The V-model is waterfall with one valuable addition: every design level has a matching test level written at the same time (user requirements → acceptance tests, architectural design → integration tests, module design → unit tests). Even in an Agile team the idea that every level of decision has a corresponding level of testing is extremely useful; the testing chapter covers it in depth.

Two words that constantly get mixed up: incremental means you deliver the product in pieces (first login, then the cart, then payment); iterative means you improve the same piece repeatedly (first a simple payment, then with retries, then with reconciliation). Agile uses both at once.

The iterative feedback loop — حلقه‌ی بازخورد تکراری.

flowchart LR
  P[Plan a thin slice] --> B[Build]
  B --> R[Release to real users]
  R --> M[Measure and learn]
  M --> P

2.3 An honest comparison

3. The Agile Manifesto, read critically

The manifesto (2001) has four comparative statements, and most people skip the closing line: "That is, while there is value in the items on the right, we value the items on the left more." The right-hand side is not worthless.

The real content sits in the twelve principles behind the manifesto. Four that engineers most often ignore: "Deliver working software frequently... with a preference to the shorter timescale"; "Continuous attention to technical excellence and good design enhances agility" (technical quality is part of the definition of agile, not a sacrifice to speed); "Simplicity — the art of maximizing the amount of work not done — is essential"; and "should be able to maintain a constant pace indefinitely" (chronic overtime is anti-Agile).

4. Scrum, in full and without mercy

Scrum is a lightweight framework for building complex products, founded on empiricism and lean thinking. The three pillars of empiricism are transparency (the work and its state must be visible to the people who decide), inspection (look at it often) and adaptation (change based on what you saw). Every Scrum event institutionalises one of these; an event that does none of them should be deleted. The five values are not slogans either: "courage" means daring to say "this story is not ready" or "that estimate is unrealistic" in front of a manager.

One full Scrum sprint — یک sprint کامل.

flowchart LR
  PB[(Product Backlog)] --> SP[Sprint Planning]
  SP --> SB[(Sprint Backlog)]
  SB --> DEV[Sprint work + Daily Scrum]
  DEV --> INC[Increment meeting the DoD]
  INC --> SR[Sprint Review]
  SR --> PB
  INC --> RETRO[Sprint Retrospective]
  RETRO --> SP

4.1 The roles — which the Guide calls accountabilities

The 2020 Guide deliberately dropped the word "role" in favour of accountability: these are not job titles, they are responsibilities. The Scrum Team is one unit, typically ten or fewer people, with no sub-teams.

4.2 Artifacts and their commitments

Every artifact carries a "commitment" that makes it transparent. The Product Backlog is the ordered, always-living list of everything that might be needed, and its commitment is the Product Goal (the team's long-term objective). The Sprint Backlog is the why of the sprint plus the selected items plus the plan to deliver them; it belongs to the Developers, and its commitment is the Sprint Goal, a single objective for the whole sprint. The Increment is a concrete step toward the Product Goal, and its commitment is the Definition of Done — the Guide is blunt about this: work that does not meet the DoD is not part of the increment at all.

4.3 Events: timebox, real purpose, failure mode

Timeboxes below are for a one-month sprint; shorter sprints usually get shorter events.

Sprint Planning answers three questions: why is this sprint valuable, what can be done, and how. If most of it is spent haggling over numbers, the problem is not planning — the backlog was not refined enough, and refinement is an ongoing activity during the sprint, not a formal event.

The Daily Scrum is not a reporting meeting; it is a 15-minute re-planning session for the Developers. The right question is not "what did you do yesterday" but "given what we learned yesterday, how do we get closer to the Sprint Goal today, and what is blocking us?" A good technique: instead of walking the people, walk the board right to left — the work closest to done first.

The Sprint Review is not a sign-off; it is a working session with stakeholders where a real increment is shown and the backlog is adjusted on the spot. The Retrospective has an effective pattern: gather data (not just feelings) → pick one or two problems → find the root cause → define at most one or two actions with a named owner → put that action into the Sprint Backlog so it actually happens.

4.4 Definition of Done and Definition of Ready

The DoD is a shared quality contract: the list every item must fully satisfy to count as finished. It must not be aspirational; it has to be genuinely met every sprint.

## Definition of Done — Payments squad
- [ ] acceptance criteria met and verified by someone else
- [ ] code reviewed with at least one approval
- [ ] unit tests for new logic + integration test for the main path
- [ ] pipeline green (build, tests, lint, dependency scan)
- [ ] database migration is backward-compatible and rollback tested
- [ ] logs and metrics for the new path visible on the dashboard
- [ ] OpenAPI document and, if needed, the runbook updated
- [ ] deployed to staging behind a feature flag
- [ ] every deliberate shortcut captured as a ticket

The DoR is the list of conditions an item should meet before entering a sprint: a clear goal, acceptance criteria, known dependencies, available test data.

5. The backlog: from epic to a buildable item

A user story is a reminder to have a conversation, not a documentation template: "As a I want so that ". The most important part is the "so that", because it preserves the why and lets the team propose a cheaper solution. The three parts of a story are remembered as the 3Cs: Card, Conversation, Confirmation.

5.1 INVEST

5.2 Acceptance criteria

A bullet list is enough for simple cases; Gherkin earns its keep when behaviour is conditional and you want it wired straight into automated tests:

Feature: Pay with a saved card

  Scenario: Successful payment with a valid saved card
    Given a customer with a saved card ending in 4242
    And an open order of 250000 IRR
    When the customer confirms payment with that card
    Then the order status becomes PAID
    And a payment receipt is stored with the gateway reference

  Scenario: Payment declined by the issuer
    Given a customer with a saved card that the issuer will decline
    When the customer confirms payment with that card
    Then the order status stays PENDING_PAYMENT
    And no receipt is stored

5.3 Slicing: the most important backlog skill

An epic is an item too big for one sprint. The most important rule: slice vertically, not horizontally.

Horizontal versus vertical slicing — تفاوت برش افقی و عمودی.

flowchart TD
  subgraph H[Horizontal slicing - nothing usable until the end]
    H1[Sprint 1: all DB tables] --> H2[Sprint 2: all services] --> H3[Sprint 3: all UI]
  end
  subgraph V[Vertical slicing - usable output every sprint]
    V1[Slice 1: pay with new card, happy path] --> V2[Slice 2: saved cards] --> V3[Slice 3: refunds]
  end

Practical slicing patterns (the SPIDR set plus a couple more): spike when not knowing is the blocker — a timeboxed piece of work whose output is a decision, not code; path — build one path only (pay with a new card) and defer the rest; interface — a minimal interface first; data — one data subset first (one currency, then multi-currency); rules — simple rules first (no discounts, then coupons and caps); error handling later (happy path with one generic error first); and manual before automated (a manual report first, scheduled later).

6. Estimation: story points, planning poker and the velocity trap

Why points beat hours: hours are person-dependent and always end in "you are faster than me"; humans are bad at absolute estimation and good at relative comparison ("this is about twice that one"); and hours turn into a contractual commitment almost instantly. The common scale is pseudo-Fibonacci (1, 2, 3, 5, 8, 13, 20, 40, 100 plus "?") and the widening gaps are deliberate: the bigger the item, the lower the precision.

Planning poker means everyone reveals their card simultaneously so nobody anchors on the first (or loudest) opinion. Its real value is not the number but the spread: when one person says 2 and another says 13, two very different mental models of the work exist, and that discussion is the most valuable output of the session.

The more mature approach is forecasting instead of committing: throughput (items finished per week) plus Monte Carlo simulation over historical data, which lets you say "85% confidence it lands between six and nine weeks" — an honest, defensible sentence, unlike "seven weeks". If you keep items small and reasonably uniform, counting items works about as well as summing points.

7. The metrics that actually matter

Burndown shows remaining work against time; burnup shows completed work and total scope as separate lines, and that is exactly why it is better: if scope grows mid-flight, a burnup shows the ceiling line rising, while a burndown just makes it look like the team is slow.

Always pick metrics in pairs — one speed metric and one stability metric, for example cycle time together with change failure rate. Measure only speed and the team sacrifices quality; measure only quality and the team becomes slow and defensive. And always at team level, never per person.

8. Kanban and managing flow

Kanban is a way to improve an existing workflow without imposing new roles or events. The official guide defines three practices: defining and visualising the workflow, actively managing items in the workflow, and improving the workflow.

The Definition of Workflow (DoW) must at minimum specify: what a work item is, where "started" and "finished" are, the states in between, how WIP is controlled, the explicit policies for each state, and the SLE (Service Level Expectation) — for example "85% of items finish within seven days". The four flow metrics the guide makes mandatory are WIP, throughput, work item age and cycle time.

A Kanban board with WIP limits — بردی با محدودیت WIP.

flowchart LR
  A[Backlog] --> B["Ready (3)"]
  B --> C["In Progress (2)"]
  C --> D["In Review (2)"]
  D --> E["Ready to Deploy (3)"]
  E --> F[Done]

Little's law for a stable system says average cycle time ≈ average work in progress ÷ average throughput. So if throughput is constant and you halve WIP, cycle time halves — the work does not get faster, it just waits less. This is the highway analogy: a motorway does not gain capacity as it fills; past a point, more cars means everyone is slower. When each person has three open items, nothing finishes, everyone is context-switching, and the manager sees "everyone is busy and nothing ships".

A cumulative flow diagram shows the number of items in each state over time as stacked bands. Reading it is easy: any band that keeps widening is a bottleneck — work is entering that state faster than it leaves. It is usually "In Review".

In practice many teams blend the two ("Scrumban"): they keep Scrum's cadence and events but run the board with WIP limits and measure flow instead of sprint commitment. That is entirely legitimate as long as it is deliberate.

9. Scaling: SAFe, LeSS and Nexus at a glance

When several teams work on one product, the new problem is coordinating dependencies, integrating frequently and prioritising jointly. SAFe is the heaviest and most prescriptive answer; the concepts you should recognise are ART (Agile Release Train, a set of teams that release together), PI Planning (a shared planning event for a multi-week increment) and WSJF for prioritisation. LeSS is minimalist: plain Scrum with one Product Owner and one Product Backlog across all teams and shared events — its philosophy is "scale by removing, not by adding". Nexus is a thin layer on top of Scrum for three to nine teams, focused on resolving dependencies and producing one integrated increment.

10. Working with Jira in practice

Nobody expects you to be a Jira administrator. The expectation is that you can write a good ticket, read a board, build a filter and connect your code to an issue.

10.1 Issue types and workflows

The standard hierarchy, top to bottom, is Epic → Story / Task / Bug → Sub-task (premium plans allow a higher level such as Initiative). An epic is an umbrella for related items serving a larger goal; a story is a change with user value; a task is work with no direct user value (an upgrade, configuration, a migration); a bug is a deviation from expected behaviour; a sub-task is an internal split for daily coordination.

A workflow is the set of statuses and the transitions allowed between them. Every status belongs to a status category — To Do, In Progress or Done — and boards and reports are driven by that.

A realistic Jira workflow — یک workflow واقعی.

stateDiagram-v2
  [*] --> Backlog
  Backlog --> Ready: refined and accepted
  Ready --> InProgress: developer starts
  InProgress --> InReview: pull request opened
  InReview --> InProgress: changes requested
  InReview --> Testing: merged to main
  Testing --> InProgress: defect found
  Testing --> Done: acceptance criteria verified
  Done --> [*]

10.2 JQL

The basic shape is field operator value, combined with AND / OR / NOT and closed with ORDER BY.

project = PAY AND sprint in openSprints() AND assignee = currentUser() ORDER BY rank ASC

project = PAY AND statusCategory != Done AND priority in (Highest, High) ORDER BY created ASC

project = PAY AND status changed to "In Progress" after -7d ORDER BY updated DESC

project = PAY AND parent = PAY-1200 AND type in (Story, Bug)

That last row is the work item age view from the Kanban section, and it is a far better daily-standup topic than walking around the people. Save it as a filter and put it on a dashboard.

10.3 Linking code to issues

Put the issue key in the branch name, the commit message and the PR title, and the tooling connects everything for you.

# branch name carries the issue key
git switch -c PAY-1234-saved-card-payment

# commit message with the issue key first
git commit -m "PAY-1234 add saved-card payment flow"

# smart commit: log time, add a comment and transition in one commit
git commit -m "PAY-1234 #time 3h 30m #comment gateway retry added #review"

Smart commit rules worth knowing: the issue key must use the default format (two or more uppercase letters, a hyphen, a number — such as PAY-1234) and appear at the start of the message; #comment turns the text after it into a comment; #time logs work; and for a transition, the first word of the transition name is enough (#review for a transition called "review changes"). The feature must be enabled organisation-wide and depends on a Jira-connected tool.

10.4 What a good ticket looks like

# PAY-1234 — Pay an order with a saved card

## Context
38% of users abandon at the card-entry step (funnel dashboard, last 30 days).

## Goal / Value
Reduce payment abandonment by removing card re-entry for returning customers.

## Scope
- Choose a saved card on the checkout page and pay with the card token
Out of scope: adding a new card here, wallets, instalment payments.

## Acceptance criteria
1. A customer with at least one saved card sees the list with the last four digits.
2. Successful payment -> order becomes PAID and a receipt with the gateway reference is stored.
3. Issuer decline -> order status is unchanged and a comprehensible message is shown.
4. Gateway timeout -> the transaction is idempotently retryable and the customer is not charged twice.

## Non-functional
- p95 latency of the payment endpoint under 800ms at normal load
- no full card data written to logs

## Links
Design: <link> · Gateway spec: <link> · Depends on PAY-1187

Three things make this ticket good: a why backed by a number, an explicit scope boundary (what is out), and testable acceptance criteria that include failure modes.

11. Requirements engineering

Requirements engineering is the process of discovering, analysing, documenting, validating and managing what a system must do. For a backend engineer this is not "the analyst's job"; it is the skill that decides whether your next two weeks are wasted.

11.1 Elicitation

Requirements are not "gathered", they are discovered — because stakeholders describe solutions, not problems. The main techniques: interviews with open questions ("walk me through your current process end to end") and resisting the jump to a solution; field observation, which almost always differs from what was described (the hidden spreadsheet, the workaround); workshops and event storming for collective discovery of the process and domain events (this connects to the DDD chapter); analysing the existing system's data and logs, which usually tells the truth better than people do; prototypes, the cheapest way to convert "I don't know what I want" into concrete feedback; and five whys to get from a want to a need.

11.2 Functional and non-functional requirements

An FR says what the system does; an NFR says how well it does it — and that is where projects die, because NFRs are usually unwritten and discovered after release. ISO/IEC 25010 (2023 revision) defines nine quality characteristics, which make an excellent NFR checklist:

11.3 Writing testable requirements

ISO/IEC/IEEE 29148 lists the characteristics of a good requirement: necessary, appropriate, unambiguous, complete, singular, feasible, verifiable, correct, conforming and traceable. Two are violated most often: singular (the word "and" usually means you have two requirements) and verifiable (if you cannot design a test that would show it violated, it is not a requirement).

An under-appreciated but excellent template is EARS (Easy Approach to Requirements Syntax), with five patterns:

Ubiquitous:   The <system> shall <response>.
Event-driven: WHEN <trigger>, the <system> shall <response>.
State-driven: WHILE <state>, the <system> shall <response>.
Unwanted:     IF <unwanted condition>, THEN the <system> shall <response>.
Optional:     WHERE <feature is included>, the <system> shall <response>.

WHEN a payment authorisation request times out after 30 seconds,
the payment service shall retry the authorisation with the same idempotency key
at most twice, and shall mark the payment as UNKNOWN if all attempts time out.

IF the account balance is insufficient,
THEN the payment service shall reject the request with error code INSUFFICIENT_FUNDS
and shall not create a ledger entry.

The power of EARS is that it removes ambiguity without requiring a formal language, and each sentence converts almost directly into a test.

11.4 Prioritisation

RICE in detail: reach is the number of people affected in a defined period; impact uses a discrete scale (3 = massive, 2 = high, 1 = medium, 0.5 = low, 0.25 = minimal); confidence is a percentage (100% solid data, 80% good evidence, 50% informed guess); effort is person-months across all roles.

11.5 Traceability

Traceability means you can walk from any requirement to the work item, to the code, to the test that verifies it — and back. It is mandatory in regulated environments and a lifesaver everywhere else when you need to answer "what breaks if we delete this?". The lightweight version: put the issue key in the test name and keep a simple coverage table. The query below finds approved requirements with no passing test:

SELECT r.req_key,
       r.title,
       count(t.id) FILTER (WHERE t.last_result = 'PASS') AS passing_tests
FROM requirement r
LEFT JOIN requirement_test rt ON rt.req_id = r.id
LEFT JOIN test_case t        ON t.id = rt.test_id
WHERE r.status = 'APPROVED'
GROUP BY r.req_key, r.title
HAVING count(t.id) FILTER (WHERE t.last_result = 'PASS') = 0
ORDER BY r.req_key;

SELECT r.req_key,
       r.title,
       COUNT(CASE WHEN t.last_result = 'PASS' THEN 1 END) AS passing_tests
FROM requirement r
LEFT JOIN requirement_test rt ON rt.req_id = r.id
LEFT JOIN test_case t         ON t.id = rt.test_id
WHERE r.status = 'APPROVED'
GROUP BY r.req_key, r.title
HAVING COUNT(CASE WHEN t.last_result = 'PASS' THEN 1 END) = 0
ORDER BY r.req_key;

11.6 Change management, scope creep and feasibility

Scope creep is the silent growth of scope with no change in time or capacity — usually arriving as "could you just add one small thing". It differs from legitimate change in that legitimate change is deliberate and something else is set aside for it. Three practical tools: capture instead of refusing ("I'll log that as an item and we'll prioritise it with the PO"); the trade rule (anything new entering the current sprint must push something of similar size out, and that decision belongs to the PO, not to the requester); and an explicit boundary in the ticket (an "out of scope" section prevents more creep than any meeting).

Before committing to a feature, check four feasibility dimensions: technical (possible with the current architecture and skills?), operational (can it be supported and monitored?), economic (is the value worth the cost?) and legal (personal data, retention, audit). The engineering tool for this is a spike: timeboxed investigation with a specific question and a written outcome.

12. UML for a backend engineer: only what pays off

UML has more than ten diagram types and a backend engineer really uses five. The goal is neither "complete documentation" nor "generating code from a model"; the goal is transferring an idea to another human with minimal ambiguity.

12.1 Class diagram

The relationship notation to know: <|-- inheritance, *-- composition (the part cannot exist without the whole), o-- aggregation (the part is independent), --> association, ..> dependency, ..|> interface realisation. Visibility markers: + public, - private, # protected.

An order domain model — مدل دامنه‌ی یک سفارش.

classDiagram
  class Order {
    +UUID id
    +OrderStatus status
    +Money total()
    +void addLine(Product p, int qty)
  }
  class OrderLine {
    +int quantity
    +Money unitPrice
  }
  class Customer {
    +UUID id
    +String email
  }
  class Payment {
    +UUID id
    +Money amount
    +PaymentStatus status
  }
  class PaymentMethod {
    <<interface>>
    +authorize(Money amount) AuthResult
  }
  class SavedCard
  Customer "1" --> "0..*" Order : places
  Order "1" *-- "1..*" OrderLine : contains
  Order "1" --> "0..*" Payment : paid by
  Payment ..> PaymentMethod : uses
  SavedCard ..|> PaymentMethod

Draw class diagrams for the domain, not for all your code. Nobody reads a sixty-class diagram and nobody keeps it current. If your IDE can generate the diagram automatically, drawing it is probably not worth it; if it requires human judgement — which entities exist, which are aggregate roots, what belongs to what — it is. Aggregates and bounded contexts are covered in the DDD chapter.

12.2 Sequence diagram — the highest-value diagram for backend work

A payment flow with a gateway timeout — مسیر پرداخت با timeout.

sequenceDiagram
  autonumber
  participant C as Client
  participant API as Order API
  participant PS as Payment Service
  participant GW as Card Gateway
  participant DB as Ledger DB

  C->>API: POST /orders/{id}/pay (Idempotency-Key)
  API->>PS: authorize(orderId, cardToken, key)
  PS->>DB: insert payment attempt (PENDING, key)
  PS->>GW: authorize request
  GW--xPS: timeout after 30s
  PS->>GW: retry with same key
  GW-->>PS: approved (auth ref)
  PS->>DB: update payment to AUTHORIZED
  PS-->>API: AuthResult(approved)
  API-->>C: 200 OK (order PAID)

In a design discussion or a review this diagram is worth two pages of prose, because it shows ordering, network boundaries and failure points at the same time. Always draw a separate version for the error paths; the happy path is usually obvious.

12.3 State machine

Any entity with a status field is already a state machine. Drawing it exposes three things: illegal transitions, dead-end states, and duplicate states that are really the same state.

The payment lifecycle — چرخه‌ی حیات پرداخت.

stateDiagram-v2
  [*] --> Pending
  Pending --> Authorized: gateway approves
  Pending --> Declined: gateway declines
  Pending --> Unknown: timeout, result not known
  Unknown --> Authorized: reconciliation finds a match
  Unknown --> Declined: reconciliation finds no charge
  Authorized --> Captured: funds captured
  Captured --> Refunded: refund requested
  Declined --> [*]
  Refunded --> [*]
  Captured --> [*]

12.4 Activity, component, deployment and use case

Activity diagrams map to a Mermaid flowchart with decision nodes; they are useful for conditional processes.

Order approval activity — فرایند تأیید سفارش.

flowchart TD
  S([Order submitted]) --> V{Stock available?}
  V -- no --> B[Backorder and notify customer]
  V -- yes --> R{Risk score acceptable?}
  R -- no --> M[Send to manual review]
  R -- yes --> P[Authorize payment]
  P --> Q{Authorized?}
  Q -- no --> F[Mark order as payment failed]
  Q -- yes --> A[Reserve stock and confirm order]
  A --> E([Order confirmed])

Component diagrams show what pieces the system is made of and which interfaces they talk over; their best home is the first page of a service README.

Components of an order service — اجزای سرویس سفارش.

flowchart LR
  subgraph OrderService[Order Service]
    API[REST API layer]
    APP[Application services]
    DOM[Domain model]
    OUT[Outbox publisher]
    REP[JPA repositories]
  end
  API --> APP --> DOM
  APP --> REP
  APP --> OUT
  REP --> DB[(PostgreSQL)]
  OUT --> MQ[[Kafka topic: order-events]]
  API --> PAY[Payment Service REST]

Deployment diagrams map software to infrastructure: what runs where and where the network boundaries are.

A deployment topology — توپولوژی استقرار.

flowchart TB
  subgraph Edge[Public zone]
    LB[Load balancer / TLS termination]
  end
  subgraph K8s[Kubernetes cluster - private zone]
    ING[Ingress controller]
    P1[order-service pods x3]
    P2[payment-service pods x2]
  end
  subgraph Data[Data zone]
    PG[(PostgreSQL primary + replica)]
    RD[(Redis cache)]
    KF[[Kafka cluster]]
  end
  LB --> ING --> P1
  ING --> P2
  P1 --> PG
  P1 --> RD
  P1 --> KF
  P2 --> PG

Use case diagrams are the simplest and most political: you sit with a non-technical stakeholder and draw the actors and their goals so the system boundary becomes explicit.

Actors and goals — بازیگران و اهداف.

flowchart LR
  CU([Customer]) --> UC1[Place an order]
  CU --> UC2[Pay for an order]
  CU --> UC3[Track order status]
  OP([Operations staff]) --> UC4[Issue a refund]
  OP --> UC5[Resolve a stuck payment]
  UC2 --> GW([Card gateway])
  UC4 --> GW

13. The C4 model: the modern alternative for architecture diagrams

The problem with typical architecture diagrams is that everything ends up in one picture and nobody knows whether a rectangle is a server, a process, a module or a team. C4 solves this with four levels of zoom, like a map that zooms from a country to a street. System Context: our system as one box, plus users and external systems — the audience is everyone, including non-technical people. Container: the separately runnable or deployable units inside the system — a server-side application, a SPA, a database, a message broker (note that "container" here is an architectural concept and does not necessarily mean Docker). Component: the building blocks inside one container and their responsibilities. Code: class-level detail, usually left to the IDE. There are also supplementary views: system landscape, dynamic and deployment.

C4 level 1, system context — سطح یک C4.

flowchart TB
  U([Customer]) -->|places and pays for orders| S[Order Platform]
  OPS([Operations staff]) -->|handles refunds| S
  S -->|authorises payments| GW[Card Gateway - external]
  S -->|sends receipts| MAIL[Email provider - external]
  S -->|reports| BI[Data warehouse - internal]

C4 level 2, containers — سطح دو C4.

flowchart TB
  U([Customer]) --> SPA[Web SPA - TypeScript]
  SPA -->|JSON over HTTPS| API[Order API - Spring Boot]
  API -->|JDBC| DB[(Order DB - PostgreSQL)]
  API -->|publishes events| K[[Kafka]]
  API -->|REST| PAY[Payment Service - Spring Boot]
  PAY -->|JDBC| PDB[(Payment DB - PostgreSQL)]
  K --> PROJ[Reporting projector - Spring Boot]
  PROJ --> WH[(Reporting store)]

C4 can be kept as text (diagrams-as-code), for example with the Structurizr DSL:

workspace "Order Platform" {
  model {
    customer = person "Customer"
    platform = softwareSystem "Order Platform" {
      spa = container "Web SPA" "TypeScript"
      api = container "Order API" "Spring Boot"
      db  = container "Order DB" "PostgreSQL"
    }
    gateway = softwareSystem "Card Gateway" "External"

    customer -> spa "Uses"
    spa -> api "Calls" "JSON/HTTPS"
    api -> db "Reads from and writes to" "JDBC"
    api -> gateway "Authorises payments"
  }

  views {
    systemContext platform "Context" {
      include *
      autoLayout lr
    }
    container platform "Containers" {
      include *
      autoLayout lr
    }
    theme default
  }
}

The value of diagrams-as-code is not only version control: you keep one model and generate several views from it, so the views can never contradict each other — unlike drawing tools, where three inconsistent versions of the same architecture typically live in three different slide decks. If Structurizr is too heavy, Mermaid in the repository with one simple rule is enough: any architectural change updates the diagram in the same PR.

14. BPMN at a glance

BPMN is the standard notation for modelling business processes. Its key difference from an activity diagram is that besides being readable by humans it is executable: process engines can run the model directly. The elements to know are pools and lanes (actors and responsibilities), tasks (human or service work), gateways (exclusive, parallel, event-based), events (start, end, timer, message, error) and sequence flows. When a process runs for days, involves human approval, or needs compensation, modelling it in BPMN and running it on a process engine is far more sensible than hand-rolling it with a status column. The workflow-engine chapter covers this fully with runnable examples; here you only need to know when to reach for it.

15. Documentation that survives

Bad documentation is documentation nobody updates. The answer is not "more documentation" but less documentation, closer to the code, with a defined lifespan.

15.1 ADRs — recording architecture decisions

An ADR is a short file that records one important decision and why it was made. Its value is not explaining the decision; it is preserving the options that were rejected and the reasons, so nobody restarts the same argument a year later. The common template is MADR (version 4), with files named NNNN-title-with-dashes.md under docs/decisions/:

---
status: accepted
date: 2026-03-11
decision-makers: payments team
consulted: platform team, security
informed: product
---

# 0007 — Use an outbox table for publishing payment events

## Context and Problem Statement
The payment service must publish an event after every state change. Writing to the
database and the message broker at the same time is not atomic; if the service dies
between the two, we either lose an event or publish one whose transaction never committed.

## Decision Drivers
* no event may be lost if the service crashes; no distributed transaction; publish delay under 5s is acceptable

## Considered Options
* publish directly to the broker after commit
* a distributed (XA) transaction between database and broker
* an outbox table plus a separate publisher
* change data capture on the payment table

## Decision Outcome
Chosen: outbox table plus publisher, because it guarantees atomicity using the same
database transaction and requires no new infrastructure.

### Consequences
* Good: no event is lost; at-least-once delivery with an idempotency key on the consumer
* Bad: one more table and one more background process to operate, and publish latency
  depends on the polling interval

### Confirmation
An integration test that kills the service between commit and publish and proves eventual
delivery, plus an alert on outbox queue depth.

The usual statuses are proposed, accepted, rejected, deprecated and superseded by ADR-NNNN. The golden rule: do not edit an ADR, supersede it — the history of decisions is the part with value.

15.2 README, runbooks and diagrams-as-code

A README is for someone who wants to run and change the code: what the service does and who owns it, how to start it locally (ideally one command), external dependencies, how to run tests, one architecture diagram, and links to the ADRs. A runbook is for someone paged at three in the morning: operational, step by step, no theory.

# Runbook — payment-service

## Health and dashboards
Health: GET /actuator/health · Dashboard: <link> · Alerts: <link>

## Alert: payment_outbox_lag_high
Meaning: the outbox queue is more than 5 minutes behind; events are not being published.
1. Check the publisher is running: kubectl get pods -l app=payment-outbox
2. Look for broker connection errors: kubectl logs deploy/payment-outbox --since=15m
3. If the broker is down, notify the platform team and wait — no data is lost.
4. If the publisher is crash-looping, roll back to the previous version: <rollback command>
5. If the queue exceeds 100k rows, scale the publisher horizontally.
Escalation: if unresolved within 30 minutes, page the payments on-call engineer.

API documentation should be generated from the code or the contract, not written by hand (the API design chapter covers OpenAPI); the process point here is to push generation and publication into the pipeline so it never lags:

name: docs
on:
  push:
    branches: [main]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '21'
      - name: Generate OpenAPI document
        run: ./mvnw -B verify -Dtest=OpenApiExportTest
      - name: Upload API docs
        uses: actions/upload-artifact@v4
        with:
          name: openapi
          path: target/openapi.json

Any wiki page explaining "how to deploy" that has not been touched in six months is actively dangerous, because someone will trust it. Two rules: keep operational documentation next to the code so it is updated in the same PR, and give every document an owner and a review date — and when it is obsolete, delete it. Deleting wrong documentation is an improvement, not a loss.

16. Code review culture

Code review has two goals and one is usually forgotten: raising code quality, and spreading knowledge through the team. Pursue only the first and you end up with an irritating quality gate.

The further down the list you go, the less human feedback is worth; leave style and formatting to a formatter and linter (see the clean-code chapter) so humans spend their attention on design and risk.

For feedback that lands: label the level — a simple and widely used convention is to prefix comments with blocking: (I will not merge without this), suggestion: (better, but optional), nit: (taste), question: (explain this to me) and praise: (this was well done). Talk about the code, not the person ("this method has three responsibilities", not "you always write huge methods"). Say why ("this query runs inside a loop and causes N+1; a fetch join fixes it" beats "not optimal"). If a thread reaches its third round, a five-minute call saves ten comments. And the receiver has duties too: apply every comment or answer it — an ignored comment teaches the reviewer to care less next time.

Review latency is the team's most expensive invisible waste: while a PR waits two days the author loses context, starts new work (WIP rises) and merge conflicts accumulate. A simple rule that dramatically reduces cycle time is clear the review queue before starting new work — Kanban's "stop starting, start finishing". Pair and mob programming are another form of review rather than a replacement: for complex, unfamiliar or high-stakes work (security, money, data migration) pairing is often faster and less risky than solo work plus a later review, while for routine work it rarely pays.

17. How to describe your process experience in an interview

Most candidates lose points here, not because they lack experience but because they describe it in clichés. Three rules. Move from generalities to a specific narrative: "we did Agile" carries no information; "two-week sprints, a DoD that included an integration test and an OpenAPI update, and after one retrospective we agreed to keep PRs under 400 lines" paints a real picture. Give numbers: cycle time, deploys per week, team size, the percentage of unplanned work. Use STAR (situation, task, action, result) and always add one sentence about what you would do differently.