Writing a Solution Architecture Definition for SAP Commerce: The Views That Actually Communicate

Most solution architecture documents fail one of two ways: they are a 200-page doorstop nobody reads, or a diagram-free wall of prose nobody understands. The Solution Architecture Definition (SAD) format solves both by describing the solution through a set of architectural views, each answering a different concern for a different audience, and by ruthlessly not duplicating what other documents already own. This guide covers the SAD structure for a SAP Commerce solution and, more importantly, the editorial discipline that keeps it useful: reference, do not repeat; summarize external systems; and make every architectural decision traceable to the requirement it serves.

The Governing Idea: Views for Concerns#

An architecture serves many concerns (what it does, how it processes, how it performs, how it deploys) and no single diagram shows all of them without becoming unreadable. The SAD splits these into views, each a section, each showing one aspect. A reader interested in integration reads the context and logical views; one interested in performance reads the non-functional view; one interested in the roadmap reads the project view. The document is navigable by concern rather than read cover to cover, which is what makes a large architecture communicable.

The Editorial Rule: Reference, Do Not Repeat#

The single discipline that keeps a SAD from bloating into uselessness: do not duplicate content that other deliverables own. The SAD references them and adds architectural context, no more:

• Requirements live in the requirements documents; the SAD references functionality only to justify architectural decisions.
• User stories and acceptance criteria live in the backlog; the functional view summarizes functional scope to frame architecture, not to restate stories.
• NFRs live in the NFR catalog (the NFR guide); the non-functional view maps architecture to them without repeating the numbers.
• Project management detail lives in the project plan; the project view references releases only to explain architectural sequencing.

A SAD that repeats the requirements is a SAD that goes stale the moment a requirement changes, and a document that goes stale stops being trusted. Reference-and-contextualize keeps it current and lean.

The Views, for a Commerce Solution#

Assumptions and Constraints. The significant constraints, assumptions, and requirements shaping the architecture, with explicit in-scope and out-of-scope architecture components. The out-of-scope list here does the same fight-prevention job as the NFR catalog's out-of-scope rows.

Context View. The high-level picture: main components, user types, and interactions with external entities, defining the solution's boundaries. The discipline: external systems' internal workings are out of scope even when they perform e-commerce functionality; document them only in summary and only where relevant to the Commerce solution. This view is the one-page "what talks to what" that every stakeholder needs.

Project View. How key architecturally-relevant functionality maps to releases and milestones, at a high level, to put architecture decisions in strategic context (why this piece is built first). Explicitly not a duplicate of the project plan.

Functional View. The key functional areas, providing the context that justifies the architecture: all software does something, and defining that functional scope is what determines the architecture. References functionality to frame technical decisions, does not restate user stories.

Process View. How processing steps fit together to implement the functional requirements: necessary when the solution relies on workflow, forked, or parallel processing (business processes, the events and cronjobs guides). Skip it if the solution has no significant process orchestration; include it in depth if order management or approval workflows are central.

Non-Functional View. The architecturally significant decisions that enable the solution to meet the agreed NFRs, each mapped to its NFR category (ISO 25010). This is the view that makes performance and reliability traceable: the NFR says "page response under 1 second," and the SAD says "to achieve that, the solution uses caching layers X, Y, Z configured as follows." The NFR states the target; the SAD states the mechanism. Document caching architecture, load balancing, and the redundancy approach here, and cross-reference the NFR rather than copying it.

Logical View. The core structure: components and their interactions, high-level technology choices, and critically for commerce, which areas extend the base SAP Commerce platform. This is where the platform-versus-custom line (the side-by-side and headless guides) gets drawn on paper: what is out-of-the-box, what is configured, what is custom-built, and what is side-by-side. The most technically consequential view.

Deployment View (where the format includes it): how the logical components map to the CCv2 environments and aspects (the clustering and Cloud Portal guides), the integration topology, and the network shape (the web architecture guide). What runs where.

Every View Has a File Behind It#

The reason most SAP Commerce SADs go stale is that they are written from workshops instead of from the repository. Each view has an artifact in the codebase that is its source of truth, and a view that contradicts its artifact is wrong by definition. Anchor them explicitly:

The deployment view is the one that earns the most, because the manifest already answers "what runs where" and most SADs redraw it wrong from memory:

"aspects": [
  { "name": "accstorefront", "webapps": [ { "name": "yacceleratorstorefront", "contextPath": "" } ] },
  { "name": "api",           "webapps": [ { "name": "commercewebservices", "contextPath": "/occ" } ] },
  { "name": "backoffice",    "webapps": [ { "name": "backoffice", "contextPath": "" },
                                          { "name": "hac", "contextPath": "/hac" } ] },
  { "name": "backgroundProcessing",
    "properties": [ { "key": "cluster.node.groups", "value": "integration,yHotfolderCandidate,backgroundProcessing" } ] }
]

Paste the project's real aspect block into the deployment view and annotate it. It cannot go stale silently, because a manifest change is a pull request somebody reviews. A hand-drawn box diagram of the same thing goes stale the first time an aspect is added and nobody notices for a year.

The logical view gets the same treatment from the other direction. Take the extension list, put it in three columns (out of the box, configured, custom), and the platform-versus-custom line is drawn by evidence rather than by opinion. That table is also the input the upgrade effort analysis needs later, so writing it once serves two purposes.

Making It Live, Not Shelfware#

A SAD earns its keep only if it stays current and gets used:

• Diagrams carry the load. Each view should be a diagram plus supporting prose, not prose alone. The context and logical views especially are pictures first; a component diagram communicates in seconds what paragraphs bury. (Keep diagrams in a maintainable format so they update with the architecture.)
• Update it iteratively. The SAD is produced and refined across the project (heavily in Explore, refined in Realize), not written once and abandoned. Architectural decisions made in sprints land in the relevant view.
• It is the onboarding document. A new architect or a reviewing party should be able to understand the solution's shape from the SAD. If they cannot, the SAD has failed regardless of its length.
• It feeds the reviews. The security review, the go-live readiness assessment, and any external architecture review start from the SAD. A current SAD makes those reviews efficient; a stale one makes them archaeology.

Checklist#

• Structured as views by concern, navigable without cover-to-cover reading
• Reference-not-repeat discipline held: no duplicated requirements, stories, NFR numbers, or project detail
• Assumptions/constraints with explicit in-scope and out-of-scope architecture components
• Context view defines boundaries; external systems summarized, not detailed
• Non-functional view maps each architectural decision to its NFR category (mechanism, not target)
• Logical view draws the platform-versus-custom line explicitly (OOTB / configured / custom / side-by-side)
• Deployment view maps components to CCv2 environments, aspects, and network topology
• Diagrams first, prose supporting; document updated iteratively across the project

The SAD is the architecture's memory: what was decided, why, and how it satisfies the requirements. Written as views, kept current by reference rather than repetition, and led by diagrams, it becomes the document every review and every new team member starts from. Written as a one-time prose dump, it becomes the file everyone knows is out of date and nobody opens.