The solution architect on an SAP program

#The 60-second version

An SAP program makes thousands of small decisions. Which process to change, which gap to close, what to build, how systems talk, who may do what. Each decision is made by a specialist, in a workshop, under deadline pressure.

The solution architect is the person who makes sure those decisions add up to one system that works, can be upgraded and is worth what it cost. They don't configure every screen. They own the shape of the solution: which requirements become extensions, which become process changes, how the landscape fits together, and which non-functional requirements (volumes, batch windows, availability) the design must meet.

The job has three tools: fit-to-standard workshops, where requirements are sorted; a design authority, the regular meeting where significant decisions are reviewed and recorded; and a decision log, the written record of why each choice was made.

This topic follows the role through SAP's implementation method, using Calder Pumpworks, the fictional pump maker this course uses, as it moves its German company onto the US company's S/4HANA system. It ends with the step from solution architect to forward deployed engineer (FDE): the architect who also builds.

#Why it matters to the business

Most of the cost of an SAP program is decided early, in conversations that look harmless.

• Every "yes" to custom code is a ten-year cost. An extension has to be tested and fixed at each upgrade for as long as it lives. SAP's own guidance is to extend at the highest level possible and to remediate the riskiest kind (level D) right away (SAP Learning). A solution architect who says no to the wrong 30 extensions saves more than any project manager's schedule.
• Workstreams optimize locally. The finance lead wants clean postings, the sales lead wants fast orders, the integration lead wants few interfaces. Without one person who sees all of it, each lead makes a sound decision that breaks someone else's.
• Late surprises are the expensive ones. A month-end job that doesn't fit the batch window, a role that breaks segregation of duties, an interface nobody owns. These are found in a design review in week 8, or in hypercare in week 40.
• Decisions get reopened. A program without a decision log debates the same question every quarter, with a new person each time.

A concrete case at Calder: in order-to-cash, the sales director asks for his own screen to release credit-blocked orders. The sales lead is inclined to agree; it's a small build. The solution architect asks one question: who should approve credit? The answer turns a build into a process change. The analyst releases orders in standard SAP, and the person who sells no longer approves his own customer's credit.

#How SAP does it

As of November 2026, SAP gives the role a method and a governance frame, but not a job title.

• SAP Activate is SAP's implementation method. It has four core phases, Prepare, Explore, Realize and Deploy, plus Discover before and Run after, and its work is organized in workstreams such as Design and Configuration, Integration, Extensibility, Data Management, and Technical Architecture and Infrastructure (SAP Learning). A solution architect works across all of those workstreams.
• Fit-to-standard workshops run in Explore. SAP's experts demonstrate standard processes, the team collects the "delta requirements" that don't fit, and the result is a prioritized backlog (SAP Learning).
• Key design decisions and a standardization board. SAP's clean core training describes a Solution Standardization Board that reviews deviations from standard, recorded as key design decisions, and allows them only for industry compliance, local regulation or a differentiating capability with measurable value (SAP Learning).
• Quality gates. For RISE with SAP customers, the project manager confirms each phase through clean core quality gates in SAP Cloud ALM, SAP's application lifecycle tool. SAP reviews the answers, and a RISE with SAP Enterprise Architect from SAP goes through the feedback with the project (SAP Learning).

The SAP Learning role lessons opened for this topic name steering committees, project managers, configuration experts and business experts, but no "solution architect" (SAP Learning). The role is defined by the customer and its implementation partner. That is why it varies so much between programs, and why you should write its decision rights down.

#The role phase by phase

The first 90 days on a new program follow the same logic:

• Days 1 to 30: listen and map. Meet every workstream lead, the business process owners, security, basis and the partner. Draw the landscape. Read every decision already made, written or not.
• Days 31 to 60: set the rules. Agree architecture principles, the decision template and who decides what. Start the design authority. Write the first three decision records on live debates.
• Days 61 to 90: show value. Run the first design reviews, close the oldest open decisions, and report the extension count and clean core levels to the steering committee.

#Questions to ask

Ask your partner, your program lead or a candidate for the role:

1. Who is the solution architect, and what can they decide alone, without the steering committee?
2. Where is the decision log, and how many decisions are open right now? How old is the oldest?
3. How often does the design authority meet, who attends, and how long does a decision take?
4. How many extensions are planned, at which clean core levels, and who approved those below level A?
5. Which non-functional requirements are written down with a target and an owner?
6. How does a business request for custom code get handled, and who can say no?
7. Does the solution architect attend fit-to-standard workshops, or only read their output?
8. Who takes over the decision log after go-live?

#Common misconceptions

• "The solution architect designs everything." They design the shape and review the rest. Functional and technical experts own the detail.
• "Architecture is a document delivered in Explore." It is a set of decisions that keeps changing. SAP's agile approach avoids large blueprints and keeps documentation next to the processes (SAP Learning).
• "A design authority slows the program down." A good one is fast and small. What slows programs down is reopening decisions nobody wrote down.
• "Saying no to custom code makes the business unhappy." Saying no without an alternative does. A good architect says no to the design and yes to the need.
• "SAP's enterprise architect does this job." In RISE, SAP's enterprise architect reviews quality gate feedback with the project. The program still needs its own decision owner every day.

#Key terms

All course terms, A to Z, in the glossary

• Solution architect: the person accountable for how a program's decisions fit together into one working, upgradeable solution.
• Design authority: a regular, small meeting with the right to review and record significant design decisions for the program.
• Decision log: the list of a program's architecture decisions, each with context, options, decision and consequences.
• Key design decision (KDD): SAP's term for a recorded design decision, used when a deviation from standard is reviewed.
• Solution Standardization Board: SAP's suggested body that reviews deviations from the standard and the business case behind them.
• Quality gate: a checkpoint at a phase transition where deliverables are reviewed before the program moves on.
• Delta requirement: a requirement that standard SAP, as demonstrated in fit-to-standard, doesn't meet.

#Check yourself

#Mental model

A solution architect on an SAP program owns the decision log. Everything else follows from that.

An FDE owns a number: move metric M from X to Y. A solution architect owns the record of choices that makes the whole system hang together: which requirement went where, at which clean core level, against which non-functional target, with which consequences. If a decision isn't in the log, it hasn't been made; it has only been assumed.

Two habits make the log useful:

1. Standard first, every time. Each record lists a no-build option (standard, configuration, process change, a standard feature, or declining) next to whatever is being proposed. If nobody can say why standard fails, the gap isn't proven.
2. Decisions are cheap to change on paper and expensive in code. The architect's leverage is earliest in Explore. By Realize, every reversal costs a rebuild, a retest and a transport.

The rest of this topic is mechanics: where the decisions come from (workshops), where they are reviewed (the design authority), how they are tested before review (a checklist you will build), and how to hold the line when people push for custom code.

#How it works

#Responsibilities by phase, in more detail

SAP Activate's phases are the frame (SAP Learning). What the architect does inside each one is your program's choice. A workable split:

Two phase transitions matter most. Explore to Realize is where the design hardens into a backlog: after it, every change costs a rebuild. Realize to Deploy is where design debt becomes cutover risk. For RISE with SAP programs, both sit inside SAP's clean core quality gates, tracked in SAP Cloud ALM (SAP Learning).

#Running fit-to-standard workshops

SAP's partner and implementation team usually runs the workshops; configuration experts demonstrate each process (SAP Learning). The solution architect's job in the room is different: protect the standard, spot cross-process effects, and turn real gaps into decisions.

Before the workshops:

• Order matters. SAP recommends running the chart of accounts and organizational structure workshops first; the others can run in parallel (SAP Learning). The architect should be in both, because company codes, plants and sales organizations shape every later decision.
• The right people. The same SAP lesson suggests at least two and no more than four customer representatives per business role, so discussion stays focused. Ask for the people who do the work, not only their managers.
• Realistic time. SAP's example is one to two processes per half-day workshop, sized by the length of the test procedure. Book the architect's time where processes cross teams: order-to-cash meets credit, intercompany meets both procurement and sales.
• Evidence ready. Usage data for custom programs, transaction volumes, and the open questions from Discover.

In the room:

1. Let the expert show standard first, end to end. Hold questions about the old system until after the demo.
2. When someone says "we need", ask what happens today, how often, and what it costs when it goes wrong.
3. Sort each gap on the spot into the six places a requirement can go, using the decision guide from fit-to-standard and extension choices.
4. Write down every cross-process effect ("if the analyst releases, sales needs a list of blocked orders") as an open point with an owner.
5. Park design debates that need more than ten minutes. They go to the design authority with a draft record.

After: SAP's Explore guidance has the product owner validate deltas into the backlog, and only top-priority items go to design workshops that settle design decisions (SAP Learning). The architect makes sure each validated delta has a decision record before build starts.

#The design authority

The design authority is the program's decision forum. It is not in SAP's role lessons; it's a common way programs give the architect a place to decide. SAP's clean core training describes the companion body for deviations, the Solution Standardization Board, which reviews key design decisions against design principles (SAP Learning). Small programs merge the two; large ones keep the board as an escalation above the design authority.

A design authority that works:

sequenceDiagram
  participant W as Workshop
  participant A as Architect
  participant DA as Design authority
  participant SB as Standardization board
  participant B as Backlog
  W->>A: Delta requirement
  A->>A: Draft record, run checklist
  A->>DA: Record (ready)
  DA-->>A: Accept, reject or send back
  DA->>SB: Deviation or level C/D
  SB-->>DA: Approve with exit plan, or refuse
  DA->>B: Accepted record linked to requirement

The checklist is the part teams skip. A record that arrives without options, owner or clean core level wastes the meeting. You will build a checker for exactly this in Build it yourself.

#Non-functional requirements

The architect owns the list of non-functional requirements: volumes, batch windows, response times, availability, recovery, retention and audit. They decide the design more often than any functional requirement. Calder's list N01 to N15, and how each is sized and split between the customer and SAP, is built in non-functional design for SAP. In design reviews the architect's question is simple: which of these does this decision touch, and does it still meet the target?

#Managing pressure toward custom code

Every program has steady pressure to build. It comes in recognizable forms:

SAP's guidance gives you the scale: an extension takes the level of its riskiest component, and level D (modifications, writes to SAP tables, implicit enhancements) should be remediated (SAP Learning). Use it in every conversation. "That's level D" ends more debates than "that's not clean".

At Calder, the clearest case is Augsburg's ZSD_PRICE_FIX. It writes straight into the pricing table, and the custom code migration topic marked it level D, run 9 times in 14 months. The sales team wants it copied as it is. The architect's job is to make sure the request reaches the design authority as a complete record, with a no-build option beside it.

#Working with the other leads

#From solution architect to FDE

A solution architect who also builds is most of the way to forward deployed engineering. The two roles share the habits that matter: start from the business need, prefer standard, write decisions down, design for operations. The FDE adds three things:

• A number. The architect's goal is a solution that fits; the FDE's is a business metric that moves.
• Building in days. The FDE writes the prototype, the evaluation and the service, rather than reviewing someone else's spec.
• AI patterns. Retrieval, agents, evaluation and model cost, on top of the SAP architecture you already know.

The practical route: take one decision from your own log where AI was an option, prototype it in a week (rapid prototyping), and add it to your portfolio. Your decision records are themselves portfolio material: they show judgment, which is what reviewers hire for.

#Build it yourself

You will build a small tool that checks decision records before they reach the design authority. It reads Calder's register of requirements, non-functional requirements and interfaces, a design-review checklist, and a folder of decision records. It flags what would block a review and writes the questions the board should ask.

Before you start: complete Set up your computer for this course and Set up for Unit 14. They create your orchestrate-course folder, its .venv and the unit14 folder. The script uses only Python's built-in modules, so there is nothing new to install and no requirements.txt change.

flowchart LR
  S[sample] --> R[(register.json<br/>checklist.json)]
  S --> D[(adr/*.md)]
  R --> C[check]
  D --> C
  C --> T[findings in the terminal]
  C --> M[review_report.md]

#What you need

• Your course folder from the setup topics.
• About 40 minutes.
• No accounts and no cost. Calder Pumpworks is fictional; every record, meeting reference and number is made up.

#Step 1: Open your course folder

1. Open VS Code, choose File > Open Folder, and open orchestrate-course.

2. Open a terminal: Terminal > New Terminal.

3. If the prompt doesn't start with (.venv), turn it on:

   • Windows (PowerShell):

     Copy

     .venv\Scripts\Activate.ps1

   • macOS / Linux:

     Copy

     source .venv/bin/activate

4. Check that the unit14 folder exists:

   • Windows (PowerShell):

     Copy

     dir unit14

   • macOS / Linux:

     Copy

     ls unit14

   If you see an error saying the folder doesn't exist, create it with mkdir unit14.

#Step 2: Create the script

1. In VS Code, right-click the unit14 folder, choose New File, name it design_review.py, paste the code below and save.

"""Design review: check decision records before they reach the design authority.

Commands:
  sample      write Calder Pumpworks' (fictional) register, checklist and four decision records
  checklist   print the design-review checklist
  check       check every decision record; --md also writes design/review_report.md
  new         start a new decision record from the template: new ADR-006 "Title"

Options:
  --strict    with check: exit with code 1 when any record has a BLOCK finding
"""
import json
import re
import sys
from pathlib import Path

HERE = Path(__file__).resolve().parent
DESIGN = HERE / "design"
ADR_DIR = DESIGN / "adr"

NO_BUILD = {"Standard", "Configuration", "Process change", "Standard feature", "Decline"}
EXTENSION = {"Key user", "ABAP Cloud", "Side-by-side", "Classic"}
KINDS = NO_BUILD | EXTENSION
STATUSES = {"Proposed", "Accepted", "Rejected", "Superseded"}
FIELDS = ["Status", "Date", "Owner", "Deciders", "Requirements", "Kind"]
SECTIONS = ["Context", "Options", "Decision", "Consequences"]

# ---------------------------------------------------------------- sample data
REGISTER = {
    "requirements": {
        "R01": "Hold orders when a customer is over its credit limit",
        "R02": "Pump test certificate number on order item and delivery note",
        "R03": "Distributors see order status and dates without SAP users",
        "R04": "Sales director releases credit blocks by phone",
        "R05": "Plant manager approves POs above 25,000 USD",
        "R06": "Rebuild CP20's custom report ZMM_OPEN_PO_AGING",
        "R07": "Keep Augsburg's program that writes dates into PO items",
        "R08": "Monthly intercompany price for CP-IMP200 at cost plus 8%",
        "R09": "Final inspection at goods receipt for ES-300 only",
        "R10": "See TEST1 load against capacity",
    },
    "nfrs": {
        "N01": "Billing documents on the last working day",
        "N02": "Materials in the MRP run",
        "N03": "Heavy month-end jobs end before the next site's day",
        "N04": "Sales order save during the month-end run",
        "N05": "Data layer fresh for the morning",
        "N06": "Production system availability",
        "N07": "Database backups of production",
        "N08": "Business check after any restore",
        "N09": "Disaster recovery",
        "N10": "Alert on failed interfaces",
        "N11": "No expensive SQL in custom code",
        "N12": "Billing documents kept, then archived",
        "N13": "Changes to supplier bank data logged and reviewed",
        "N14": "Emergency ID sessions reviewed",
        "N15": "Invoice agent inside its rate limit at peak",
    },
    "interfaces": {
        "I01": "SAP Business Network to CP10",
        "I02": "S/4HANA to MES and back",
        "I03": "S/4HANA to CRM",
        "I04": "Order confirmation output to customers",
        "I05": "S/4HANA to EWM RKDC and back",
        "I06": "TM to carriers",
        "I07": "S/4HANA to the data layer",
        "I08": "Bank to S/4HANA",
        "I09": "Events and read-only APIs to the agent on BTP",
        "I10": "Distributor purchase orders by EDI",
        "I11": "Intercompany orders and invoices with ECC CP20",
        "I12": "CRM availability check while quoting",
    },
}

CHECKLIST = [
    {"id": "DR01", "area": "Scope and evidence", "applies": "all",
     "ask": "Which requirement does this serve, and what evidence says the business needs it?"},
    {"id": "DR02", "area": "Standard first", "applies": "all",
     "ask": "Was standard SAP demonstrated for this need, and why didn't it fit?"},
    {"id": "DR03", "area": "Standard first", "applies": "extension",
     "ask": "Is there a standard feature or product not yet in scope that would cover it?"},
    {"id": "DR04", "area": "Clean core", "applies": "extension",
     "ask": "Which clean core level is it, and which SAP objects set that level?"},
    {"id": "DR05", "area": "Clean core", "applies": "extension",
     "ask": "How is it retested at each upgrade, and how many days does that take?"},
    {"id": "DR06", "area": "Non-functional", "applies": "extension",
     "ask": "Which volumes, batch windows and availability targets does it touch?"},
    {"id": "DR07", "area": "Integration", "applies": "all",
     "ask": "Which interfaces change, and has the integration lead signed the change?"},
    {"id": "DR08", "area": "Identity and authorizations", "applies": "all",
     "ask": "Whose identity does it run under, and which roles change? Any new segregation of duties conflict?"},
    {"id": "DR09", "area": "Data", "applies": "all",
     "ask": "Which master data or migration objects does it depend on, and who owns their quality?"},
    {"id": "DR10", "area": "Operations", "applies": "extension",
     "ask": "Who runs it after go-live, who gets the alert when it fails, and what does it cost a year?"},
    {"id": "DR11", "area": "Process and people", "applies": "no-build",
     "ask": "Who changes how they work, and when are they trained?"},
    {"id": "DR12", "area": "Process and people", "applies": "all",
     "ask": "Which test cases change or are added, and who runs them?"},
    {"id": "DR13", "area": "Reversibility", "applies": "all",
     "ask": "What would make us revisit this, and what does reversing it cost?"},
]

ADRS = {
    "ADR-002-credit-release-stays-standard.md": """# ADR-002: Credit-block releases stay with the credit analyst

- Status: Accepted
- Date: 2026-11-03
- Owner: Order-to-cash process owner
- Deciders: Design authority, meeting DA-07
- Requirements: R04, R01
- NFRs:
- Interfaces: I03
- Kind: Process change
- Level:
- Approval:
- Run owner:

## Context
Calder's sales director releases credit-blocked orders by phone today. He asked for an approval
screen of his own in CP10. Standard credit management already sends blocked orders to a credit
analyst, who releases them in a standard app. The person who sells should not approve credit.

## Options
1. Process change: the analyst releases in the standard app; the director sees blocked orders in a standard list.
2. Key user: a custom approval step that lets the director release, built with key user tools.
3. Side-by-side: a mobile approval app on SAP BTP for the director.

## Decision
Option 1. The need (fast decisions on large orders) is real; the requested design is not needed
and would put selling and approving credit with one person.

## Consequences
- The director loses a release he has today; the sponsor agreed in DA-07.
- The credit analyst gets a same-day target for orders above 50,000 USD (course value).
- New test case in the order-to-cash suite: a blocked order released by the analyst, refused for the director.
- Revisit if same-day release is missed in more than one week a month during hypercare.
""",
    "ADR-003-intercompany-price-job.md": """# ADR-003: Monthly intercompany price as an ABAP Cloud job

- Status: Accepted
- Date: 2026-11-03
- Owner: Solution architect
- Deciders: Design authority, meeting DA-07
- Requirements: R08
- NFRs: N03, N11
- Interfaces: I11
- Kind: ABAP Cloud
- Level: A
- Approval:
- Run owner: Intercompany team

## Context
CP-IMP200 moves from CP20 to CP10 at cost plus 8%, repriced every month. Augsburg's team wants
open purchase orders updated with the classic BAPI_PO_CHANGE, as their ECC program does. After the
July 2027 rollout both company codes share CP10's system, so the price can be set on both sides at once.

## Options
1. Process change: a buyer and a sales clerk key the new price each month in standard apps.
2. Classic: a job that updates open purchase orders with BAPI_PO_CHANGE (level B).
3. ABAP Cloud: a job that writes the sales condition record and the purchasing info record through released objects (level A).

## Decision
Option 3. The rule is fixed and runs monthly on core data, so a job beats manual keying, and
released objects keep it at level A.

## Consequences
- The job runs on the first working day, after the month-end jobs (N03), and must not add expensive SQL (N11).
- Upgrade retest: one automated test case in the regression suite, about half a day per upgrade.
- I11 retires at the rollout; until then the ECC price stays leading for CP20.
- The intercompany team owns the job and its alert; the solution architect owns the design.
""",
    "ADR-004-distributor-status-app.md": """# ADR-004: Distributor order status as a side-by-side app

- Status: Proposed
- Date: 2026-11-03
- Owner: Solution architect
- Deciders: Design authority, meeting DA-08
- Requirements: R03
- NFRs: N06
- Interfaces: I10
- Kind: Side-by-side
- Level: A
- Approval:
- Run owner: Customer service IT

## Context
Hallam and other distributors phone customer service for order status and confirmed dates.
They order by EDI (I10) and have no SAP users. Customer service answers about 40 such calls a
day (course value).

## Options
1. Standard: give distributors SAP users with a display role.
2. Standard feature: send the standard order confirmation output again whenever a date changes.
3. Side-by-side: a small app on SAP BTP that reads sales orders through released APIs, filtered by the distributor's customer number.

## Decision
Option 3, proposed. Option 1 puts external users in the ERP; option 2 helps but sends
documents, not answers to "where is my order".

## Consequences
- A running cost and an owner outside the S/4HANA team; customer service IT runs it.
- Each distributor sees only its own orders; the filter is tested in every release.
- Upgrade retest is small because it uses released APIs only.
- If option 2 cuts calls by half in the first month after go-live, stop and keep option 2.
""",
    "ADR-005-keep-price-fix.md": """# ADR-005: Keep ZSD_PRICE_FIX after the move

- Status: Proposed
- Date: 2026-11-02
- Owner: TBD
- Deciders: Augsburg sales team
- Requirements: R11
- NFRs:
- Interfaces:
- Kind: Classic
- Level: D
- Approval:
- Run owner:

## Context
Augsburg's sales team corrects condition prices after pricing errors with ZSD_PRICE_FIX, which
writes straight into the pricing table. They want it moved into CP10's system unchanged.

## Options
1. Classic: copy the program into CP10's system as it is.

## Decision
Option 1, because it works today.

## Consequences
- Nothing changes for the users.
""",
}

TEMPLATE = """# {id}: {title}

- Status: Proposed
- Date: YYYY-MM-DD
- Owner: (a role, not TBD)
- Deciders: Design authority, meeting DA-..
- Requirements: R..
- NFRs:
- Interfaces:
- Kind: (Standard, Configuration, Process change, Standard feature, Decline, Key user, ABAP Cloud, Side-by-side, Classic)
- Level: (A to D for extensions)
- Approval: (needed for level C or D)
- Run owner: (who runs it after go-live)

## Context
What is asked, by whom, and why now.

## Options
1. Standard: ...
2. ...

## Decision
Option .., because ...

## Consequences
- ...
"""


# ---------------------------------------------------------------- parsing
def parse_adr(path):
    text = path.read_text(encoding="utf-8")
    title = re.search(r"^# (.+)$", text, re.M)
    fields = {k.strip(): v.strip() for k, v in re.findall(r"^- ([A-Za-z ]+):[ \t]*(.*)$", text, re.M)
              if k.strip() in FIELDS + ["NFRs", "Interfaces", "Level", "Approval", "Run owner"]}
    sections = {}
    for m in re.finditer(r"^## (\w+)\n(.*?)(?=^## |\Z)", text, re.M | re.S):
        sections[m.group(1)] = m.group(2).strip()
    options = re.findall(r"^\d+\. ([A-Za-z -]+?):", sections.get("Options", ""), re.M)
    bullets = re.findall(r"^- ", sections.get("Consequences", ""), re.M)
    return {"file": path.name, "title": title.group(1) if title else path.name,
            "fields": fields, "sections": sections, "options": options,
            "consequences": len(bullets)}


def ids(value):
    return [x for x in re.split(r"[,\s]+", value or "") if x]


# ---------------------------------------------------------------- checks
def check_adr(adr, register):
    f, found = adr["fields"], []

    def add(sev, code, msg):
        found.append((sev, code, msg))

    for name in FIELDS:
        if not f.get(name):
            add("BLOCK", "C01", f"field '{name}' is empty")
    if f.get("Date") and not re.fullmatch(r"\d{4}-\d{2}-\d{2}", f["Date"]):
        add("BLOCK", "C01", "date is not written as YYYY-MM-DD")
    for name in SECTIONS:
        if not adr["sections"].get(name):
            add("BLOCK", "C02", f"section '{name}' is missing")
    if len(adr["options"]) < 2:
        add("BLOCK", "C03", "fewer than two options: a decision needs alternatives")
    if not NO_BUILD & set(adr["options"]):
        add("BLOCK", "C03", "no standard or no-build option was considered")
    kind = f.get("Kind", "")
    if kind and kind not in KINDS:
        add("BLOCK", "C04", f"kind '{kind}' is not one of the known kinds")
    elif kind and kind not in adr["options"]:
        add("BLOCK", "C04", f"the decision kind '{kind}' is not among the options")
    status = f.get("Status", "")
    if status and status not in STATUSES:
        add("BLOCK", "C08", f"status '{status}' is not Proposed, Accepted, Rejected or Superseded")
    if status == "Superseded" and "Superseded by" not in adr["sections"].get("Decision", ""):
        add("BLOCK", "C08", "superseded, but the decision doesn't name the record that replaces it")
    if f.get("Owner", "").upper() in {"TBD", "TBC", "?"}:
        add("BLOCK", "C09", "owner is TBD: every decision needs an accountable role")
    for rid in ids(f.get("Requirements")):
        if rid not in register["requirements"]:
            add("BLOCK", "C07", f"requirement {rid} is not in the register: add it there first")
    for nid in ids(f.get("NFRs")):
        if nid not in register["nfrs"]:
            add("BLOCK", "C07", f"non-functional requirement {nid} is not in the register")
    for iid in ids(f.get("Interfaces")):
        if iid not in register["interfaces"]:
            add("BLOCK", "C07", f"interface {iid} is not in the inventory")
    if kind in EXTENSION:
        level = f.get("Level", "")
        if level not in {"A", "B", "C", "D"}:
            add("BLOCK", "C05", "extension without a clean core level (A to D)")
        if level in {"C", "D"}:
            if not f.get("Approval"):
                add("BLOCK", "C05", f"level {level} needs a documented approval from the standardization board")
            if "exit" not in adr["sections"].get("Consequences", "").lower():
                add("BLOCK", "C05", f"level {level} needs an exit plan in the consequences")
        if not ids(f.get("NFRs")):
            add("WARN", "C06", "extension names no non-functional requirement")
        if not f.get("Run owner"):
            sev = "BLOCK" if kind == "Side-by-side" else "WARN"
            add(sev, "C06", "no run owner after go-live")
        if "test" not in adr["sections"].get("Consequences", "").lower():
            add("WARN", "C11", "consequences don't say how it is tested at upgrade")
    if adr["consequences"] < 2:
        add("WARN", "C10", "only one consequence: what does it cost, and who changes how they work?")
    return found


def load(design=DESIGN):
    register = json.loads((design / "register.json").read_text(encoding="utf-8"))
    checklist = json.loads((design / "checklist.json").read_text(encoding="utf-8"))
    adrs = [parse_adr(p) for p in sorted((design / "adr").glob("ADR-*.md"))]
    return register, checklist, adrs


def questions_for(adr, checklist):
    kind = adr["fields"].get("Kind", "")
    group = "extension" if kind in EXTENSION else "no-build"
    return [c for c in checklist if c["applies"] in ("all", group)]


def verdict(found):
    if any(s == "BLOCK" for s, _, _ in found):
        return "NOT READY"
    return "READY" if not found else "READY WITH WARNINGS"


# ---------------------------------------------------------------- commands
def cmd_sample():
    ADR_DIR.mkdir(parents=True, exist_ok=True)
    (DESIGN / "register.json").write_text(json.dumps(REGISTER, indent=2), encoding="utf-8")
    (DESIGN / "checklist.json").write_text(json.dumps(CHECKLIST, indent=2), encoding="utf-8")
    for name, text in ADRS.items():
        (ADR_DIR / name).write_text(text, encoding="utf-8")
    print(f"Wrote register.json, checklist.json and {len(ADRS)} decision records to {DESIGN}")
    print("Calder Pumpworks is fictional; requirement, NFR and interface IDs follow earlier topics.")


def cmd_checklist():
    _, checklist, _ = load()
    for c in checklist:
        print(f"{c['id']}  {c['area']:<28} [{c['applies']}]")
        print(f"      {c['ask']}")


def cmd_check(md=False, strict=False):
    register, checklist, adrs = load()
    blocked = 0
    lines = ["# Design review: decision records", "",
             "Calder Pumpworks is fictional. Generated by design_review.py.", ""]
    for adr in adrs:
        found = check_adr(adr, register)
        v = verdict(found)
        blocked += v == "NOT READY"
        f = adr["fields"]
        print(f"{adr['title']}")
        print(f"  {f.get('Status', '?')} | kind {f.get('Kind', '?')} | level {f.get('Level') or '-'} | {v}")
        for sev, code, msg in found:
            print(f"  {sev:<5} {code}  {msg}")
        print()
        lines += [f"## {adr['title']}", "",
                  f"Status {f.get('Status', '?')}, kind {f.get('Kind', '?')}, "
                  f"level {f.get('Level') or '-'}, owner {f.get('Owner') or '-'}. **{v}**", ""]
        lines += [f"- {sev} {code}: {msg}" for sev, code, msg in found] or ["- No findings."]
        lines += ["", "Questions for the board:", ""]
        lines += [f"- {c['id']} ({c['area']}): {c['ask']}" for c in questions_for(adr, checklist)]
        lines.append("")
    ready = len(adrs) - blocked
    print(f"{len(adrs)} records: {ready} ready for the design authority, {blocked} not ready")
    if md:
        out = DESIGN / "review_report.md"
        out.write_text("\n".join(lines), encoding="utf-8")
        print(f"Wrote {out}")
    if strict and blocked:
        sys.exit(1)


def cmd_new(adr_id, title):
    if not re.fullmatch(r"ADR-\d{3}", adr_id):
        sys.exit("Use an ID like ADR-006")
    slug = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")[:40]
    path = ADR_DIR / f"{adr_id}-{slug}.md"
    if path.exists():
        sys.exit(f"{path.name} already exists")
    ADR_DIR.mkdir(parents=True, exist_ok=True)
    path.write_text(TEMPLATE.format(id=adr_id, title=title), encoding="utf-8")
    print(f"Wrote {path}")


def main(argv):
    if not argv or argv[0] in {"-h", "--help"}:
        print(__doc__)
        return
    cmd = argv[0]
    if cmd != "sample" and not (DESIGN / "register.json").exists():
        sys.exit("No design folder yet. Run: python unit14/design_review.py sample")
    if cmd == "sample":
        cmd_sample()
    elif cmd == "checklist":
        cmd_checklist()
    elif cmd == "check":
        cmd_check(md="--md" in argv, strict="--strict" in argv)
    elif cmd == "new" and len(argv) >= 3:
        cmd_new(argv[1], " ".join(argv[2:]))
    else:
        print(__doc__)
        sys.exit(2)


if __name__ == "__main__":
    main(sys.argv[1:])

#Step 3: Write the sample design folder

1. Run:

   • Windows (PowerShell):

     Copy

     python unit14\design_review.py sample

   • macOS / Linux:

     Copy

     python unit14/design_review.py sample

2. You should see this (your folder path will differ):

Wrote register.json, checklist.json and 4 decision records to /Users/you/orchestrate-course/unit14/design
Calder Pumpworks is fictional; requirement, NFR and interface IDs follow earlier topics.

3. Open unit14/design/adr in VS Code. There are four records:

The first three are this topic's Calder decision records. The requirement IDs come from fit-to-standard and extension choices, the NFR IDs from non-functional design, and the interface IDs from the integration lead's toolkit.

#Step 4: Print the checklist

1. Run:

   • Windows (PowerShell):

     Copy

     python unit14\design_review.py checklist

   • macOS / Linux:

     Copy

     python unit14/design_review.py checklist

2. You should see 13 questions, DR01 to DR13. The first lines:

DR01  Scope and evidence           [all]
      Which requirement does this serve, and what evidence says the business needs it?
DR02  Standard first               [all]
      Was standard SAP demonstrated for this need, and why didn't it fit?
DR03  Standard first               [extension]
      Is there a standard feature or product not yet in scope that would cover it?

[all] questions apply to every record, [extension] only to records that build something, and [no-build] only to process changes, configuration and the like. These are the human questions: the board asks them. The script checks what a machine can check.

#Step 5: Check the records

1. Run the check and write the report:

   • Windows (PowerShell):

     Copy

     python unit14\design_review.py check --md

   • macOS / Linux:

     Copy

     python unit14/design_review.py check --md

2. You should see this:

ADR-002: Credit-block releases stay with the credit analyst
  Accepted | kind Process change | level - | READY

ADR-003: Monthly intercompany price as an ABAP Cloud job
  Accepted | kind ABAP Cloud | level A | READY

ADR-004: Distributor order status as a side-by-side app
  Proposed | kind Side-by-side | level A | READY

ADR-005: Keep ZSD_PRICE_FIX after the move
  Proposed | kind Classic | level D | NOT READY
  BLOCK C03  fewer than two options: a decision needs alternatives
  BLOCK C03  no standard or no-build option was considered
  BLOCK C09  owner is TBD: every decision needs an accountable role
  BLOCK C07  requirement R11 is not in the register: add it there first
  BLOCK C05  level D needs a documented approval from the standardization board
  BLOCK C05  level D needs an exit plan in the consequences
  WARN  C06  extension names no non-functional requirement
  WARN  C06  no run owner after go-live
  WARN  C11  consequences don't say how it is tested at upgrade
  WARN  C10  only one consequence: what does it cost, and who changes how they work?

4 records: 3 ready for the design authority, 1 not ready
Wrote /Users/you/orchestrate-course/unit14/design/review_report.md

3. Read ADR-005's findings against the record. Each one is a question the board would otherwise spend meeting time on. READY means the record can go on the agenda; it doesn't mean the decision is right. That is the board's job.
4. Open unit14/design/review_report.md. Each record has its findings and its board questions: twelve for an extension, ten for a process change.

#Step 6: Use it as a gate

1. Run the check with --strict:

   • Windows (PowerShell):

     Copy

     python unit14\design_review.py check --strict
     echo $LASTEXITCODE

   • macOS / Linux:

     Copy

     python unit14/design_review.py check --strict
     echo $?

2. The last line shows 1, because ADR-005 is not ready. With every record ready, it shows 0. A team can run this in its repository's pipeline so a record can't be merged for review until it passes.

#Step 7: Start a new record

1. Create a record from the template:

   • Windows (PowerShell):

     Copy

     python unit14\design_review.py new ADR-006 "Test certificate number as a custom field"

   • macOS / Linux:

     Copy

     python unit14/design_review.py new ADR-006 "Test certificate number as a custom field"

2. You should see Wrote .../unit14/design/adr/ADR-006-test-certificate-number-as-a-custom-fiel.md (the file name is cut at 40 characters).

3. Run check again. ADR-006 shows NOT READY until you fill it in. You will do that in the exercise.

#Step 8: Save your work in Git

1. Run:

git add unit14/design_review.py unit14/design
git commit -m "Unit 14: design review checker and Calder decision records"

#How the code works

#If something goes wrong

#The SAP way

SAP supplies the method, the tools and the governance vocabulary. As of November 2026:

• SAP Activate gives the phases and workstreams, and SAP's lessons describe what Explore produces: deltas, a prioritized backlog, key design decisions and process documentation, rather than large blueprints (SAP Learning).
• SAP Cloud ALM holds requirements and process documentation for cloud programs; configuration experts document requirements there during fit-to-standard (SAP Learning). For RISE with SAP, the clean core success plan, runbook and quality gate questionnaires live there too (SAP Learning).
• Clean core levels A to D, the ABAP test cockpit and the Cloudification Repository give the architect an objective measure for every extension (SAP Learning).
• The Solution Standardization Board and key design decisions are SAP's names for deviation governance, with three accepted reasons for deviating (SAP Learning).

What SAP doesn't supply is the role. The lessons on roles name centralized roles that run process workshops, document the to-be design and hand it over (SAP Learning), but no solution architect. Write the role's decision rights into the program charter in Prepare.

#Build vs. SAP

Most programs use both: SAP Cloud ALM as the system of record for requirements and tests, and short records in a repository the architects own, each naming the requirement ID it answers.

#Architecture view

Where it sits. The decision log sits beside the landscape, not inside it. Calder's records touch three places: CP10's S/4HANA system (credit management, the intercompany job), SAP BTP (the distributor app) and the ECC system of CP20 until the July 2027 rollout.

flowchart LR
  WS[Fit-to-standard] --> REQ[(Requirements<br/>Cloud ALM)]
  REQ --> ADR[(Decision records)]
  ADR --> DA[Design authority]
  DA --> S4[CP10 S/4HANA<br/>ADR-002 ADR-003]
  DA --> BTP[SAP BTP<br/>ADR-004]
  DA -.-> ECC[CP20 ECC<br/>until rollout]

Non-functional requirements of the governance itself.

Integration and identity. Decisions travel by ID: a requirement ID from the register appears in the record, and the record ID is noted against the requirement and later against the feature and its transports. Identity matters for records too: only named deciders can mark a record accepted, and the meeting reference on each record shows who decided. In a Git repository, that means protected branches and reviews; in SAP Cloud ALM, its own approval steps.

The decision to record.

• Context: Calder's program needs one place for architecture decisions that both the partner and Calder's IT can read after go-live, and that lasts beyond the partner's contract.
• Options: (1) the partner's own document tool; (2) records in SAP Cloud ALM's documentation only; (3) Markdown records in a Calder-owned repository, checked by design_review.py, with each record's ID noted on its Cloud ALM requirement.
• Decision: (3). Calder owns the log, the checks run automatically, and Cloud ALM stays the system of record for requirements and tests.
• Consequences: Two places to keep in step; the requirement ID is the link and is checked by C07. The partner's team needs access to the repository.

What a design review will ask.

1. How many decisions are open, and which work is waiting on them?
2. Which extensions are below level A, who approved them, and when do they exit?
3. Which non-functional requirements does each extension touch, and are the targets still met?
4. Who owns each side-by-side app and its running cost after go-live?
5. Where will the decision log live after the partner leaves?

#Production concerns

• Decision rights in writing. Put the architect's rights in the program charter: what they decide alone, what goes to the design authority, what goes to the standardization board or the steering committee.
• Authorizations follow decisions. Every accepted record that changes who does what (like ADR-002) needs a role change and a segregation of duties check before go-live.
• Evaluation of the governance. Report open decisions, their age, extensions by level and decisions reopened. Reopened decisions are the early warning that records are thin.
• Cost. Each extension record should carry its build and five-year running cost, so the steering committee sees the total.
• Operations. Hand the log to the operations team, with the owners named in each record. At the first upgrade, the extension records are the retest list.
• Clean core. Track levels per record, not per program. One level D component sets the whole extension to D.
• AI in reviews. A language model can draft records or summarize workshop notes. Treat its output as a draft for a named author; the design authority decides, and no tool should mark a record accepted.

#Pitfalls

• The architect who only reviews documents. Gaps are decided in workshops. Be in the room for cross-process ones.
• Records written after the build. They become justifications, not decisions. Require the record before the backlog item starts.
• No no-build option. If a record only compares two ways to build, the standard was never tested.
• "TBD" owners. A decision without an accountable role is an opinion.
• A design authority with 20 members. It turns into a status meeting. Keep it small and invite the business per topic.
• Editing accepted records. Write a new record and mark the old one superseded, so the reasoning of the time stays visible.
• Ignoring the run. Side-by-side apps and jobs need an owner and a budget after go-live, or they decay in the first year.
• Treating SAP's quality gates as the architecture review. They check method and clean core progress. Your own design reviews still check the design.

#Exercise

Turn ADR-005 into a record that can go to the design authority, and write ADR-006 for the test certificate number.

1. Open unit14/design/register.json. Under "requirements", add "R11": "Correct condition prices after pricing errors (ZSD_PRICE_FIX)" after R10 (add a comma after the R10 line).
2. Open unit14/design/adr/ADR-005-keep-price-fix.md. Rewrite it:
   • Set an owner role (for example, the order-to-cash process owner) and Deciders: Design authority, meeting DA-08.
   • List at least two options, including a no-build one, for example 1. Process change: correct prices in the standard condition apps and reprice the orders. and 2. Classic: copy the program as it is (level D).
   • Choose one in ## Decision and give the reason, using the 9 runs in 14 months.
   • Change Kind and Level to match your choice (no level for a process change).
   • Write at least two consequences, one naming the test case it adds.
3. Fill in ADR-006 (from Step 7) for requirement R02: kind Key user, level A, NFRs: N04, Interfaces: I04, run owner Sales IT, two options including a no-build one, and consequences that name the upgrade test.
4. Run python unit14/design_review.py check --md --strict (Windows: python unit14\design_review.py check --md --strict).
5. Fix what it reports until no record is NOT READY.

Done when: the check ends with 5 records: 5 ready for the design authority, 0 not ready, --strict exits with 0, and review_report.md lists the board questions for all five records. Keep the folder: the decision records are portfolio material for your FDE portfolio, and the same review habit applies to the design of the capstone.

#Check yourself