methodatlas
Session Builder

Plan my session

Plan a concrete work block with agenda, roles, preparation, and a copyable result artifact.

Method session1-2 days initial, then 1-2 h maintenance per sprintWorkshop or asyncArchitecture Document

Session: arc42

The plan translates the method into a concrete facilitated work block. Your inputs flow directly into the session brief and work artifact.

Derived automatically

Method session with 1-4. The plan uses the existing method logic and the runsheet.

Runsheet
Participation logic
Team round, shared work and alignment

Use the session for shared understanding. Contributions are collected visibly, assumptions are aligned, and open differences remain traceable in the artifact.

Outcome logic
Finish artifact

The session works directly toward Architecture Document. After the session, the artifact should be shareable, reviewable, or reusable.

  1. 1

    Chapter 1-2: Introduction, goals, constraints

    2-3 h

    Describe the problem in 5-10 sentences. List three to five quality goals in prioritized order. Add a stakeholder table with information needs. Include constraints (technical, organizational, conventional). Hint: Quality goals must be prioritized. Anyone who marks all quality attributes as important has no decision basis and the document becomes arbitrary.

    FacilitatorArchitecture Document
  2. 2

    Chapter 3-4: Context and solution strategy

    3-4 h

    Document business context and technical context as a diagram plus table. Summarize the solution strategy (architecture approach, top-level decisions, frameworks) in 1-2 pages. Hint: Chapter 4 is NOT detailed design, but the short answer to how the system is built. More than 2 pages is too much and belongs in chapter 5.

    FacilitatorContext View
  3. 3

    Chapter 5: Building block view

    3-5 h

    Create a white-box view in 2-3 levels (C4 container, C4 component). For each block, add responsibility, interfaces, and fulfilled requirements. No code classes. Hint: Not every block needs a white-box view. Only the ones with complexity or risk. Otherwise the document explodes and nobody keeps reading.

    FacilitatorRuntime View
  4. 4

    Chapter 6-7: Runtime view and deployment view

    3-4 h

    Runtime: 3-5 important scenarios as sequence diagrams. Deployment: hardware or cloud topology with nodes, networks, and deployment units. Hint: Choose scenarios that make architecture decisions visible (failover, scaling, critical paths). The happy-path sequence is secondary.

    FacilitatorDeployment View
  5. 5

    Chapter 8-9: Cross-cutting concerns and decisions

    2-3 h

    Cross-cutting concepts (security, logging, error handling, persistence). Architecture decisions as a list with ADR links and a short rationale. Hint: Make concepts concrete, not generic. 'Logging via ELK with trace ID correlation' is better than 'logging is important'.

    FacilitatorArchitecture Document
  6. 6

    Chapter 10-12: Quality, risks, glossary

    2-3 h

    Quality scenarios, ideally from QAW, in a table. Technical risks and debt with owner and escalation status. Glossary with domain and tech terms. Hint: Name risks openly. An arc42 doc without a risks chapter is marketing material, not an architecture document.

    OwnerContext View
  7. 7

    Publish artifact

    10 min

    Check the artifact for completeness, define location, set version or status, and name review recipients.

    OwnerArchitecture Document
Usable artifact

Session Brief

For invitations, boards, tickets, PR descriptions, or workshop notes.

session-brief.md

Session Brief: arc42

Goal

Artifact: Architecture Document

Working Question

Which architecture decisions, structures, and quality attributes does the reader need in order to understand, operate, and evolve the system?

Context

Current system overview; list of external interfaces; known quality goals, ideally from a Quality Attribute Workshop; constraints (regulatory, technical, organizational); existing diagrams.

Setup

  • Format: Method session
  • Duration: 1-2 days initial, then 1-2 h maintenance per sprint
  • Mode: Workshop or async
  • Participants: One main author, often an architect or tech lead, as owner; one to three reviewers from Engineering and Ops; optional stakeholder from Business for chapter 1 (goals).
  • Owner: One main author, often an architect or tech lead, as owner
  • Participation mode: Team round, shared work and alignment
  • Outcome logic: Finish artifact

Participation Logic

Use the session for shared understanding. Contributions are collected visibly, assumptions are aligned, and open differences remain traceable in the artifact.

Outcome Logic

The session works directly toward Architecture Document. After the session, the artifact should be shareable, reviewable, or reusable.

Input

arc42 template (Markdown version of arc42/arc42-template on GitHub); diagram tool (PlantUML, Structurizr, draw.io); repo directory docs/architecture/; glossary file; links to the ADR directory and possibly C4 diagrams.

Preparation

Clone the template repository and store it in docs/architecture/ as a Markdown structure. Use separate files for chapters 1-12 or one combined file. Define a diagram inclusion convention, for example PlantUML in the repo, rendered during the build.

Agenda

  1. Chapter 1-2: Introduction, goals, constraints (2-3 h) Owner: Facilitator Action: Describe the problem in 5-10 sentences. List three to five quality goals in prioritized order. Add a stakeholder table with information needs. Include constraints (technical, organizational, conventional). Hint: Quality goals must be prioritized. Anyone who marks all quality attributes as important has no decision basis and the document becomes arbitrary. Output: Architecture Document

  2. Chapter 3-4: Context and solution strategy (3-4 h) Owner: Facilitator Action: Document business context and technical context as a diagram plus table. Summarize the solution strategy (architecture approach, top-level decisions, frameworks) in 1-2 pages. Hint: Chapter 4 is NOT detailed design, but the short answer to how the system is built. More than 2 pages is too much and belongs in chapter 5. Output: Context View

  3. Chapter 5: Building block view (3-5 h) Owner: Facilitator Action: Create a white-box view in 2-3 levels (C4 container, C4 component). For each block, add responsibility, interfaces, and fulfilled requirements. No code classes. Hint: Not every block needs a white-box view. Only the ones with complexity or risk. Otherwise the document explodes and nobody keeps reading. Output: Runtime View

  4. Chapter 6-7: Runtime view and deployment view (3-4 h) Owner: Facilitator Action: Runtime: 3-5 important scenarios as sequence diagrams. Deployment: hardware or cloud topology with nodes, networks, and deployment units. Hint: Choose scenarios that make architecture decisions visible (failover, scaling, critical paths). The happy-path sequence is secondary. Output: Deployment View

  5. Chapter 8-9: Cross-cutting concerns and decisions (2-3 h) Owner: Facilitator Action: Cross-cutting concepts (security, logging, error handling, persistence). Architecture decisions as a list with ADR links and a short rationale. Hint: Make concepts concrete, not generic. 'Logging via ELK with trace ID correlation' is better than 'logging is important'. Output: Architecture Document

  6. Chapter 10-12: Quality, risks, glossary (2-3 h) Owner: Owner Action: Quality scenarios, ideally from QAW, in a table. Technical risks and debt with owner and escalation status. Glossary with domain and tech terms. Hint: Name risks openly. An arc42 doc without a risks chapter is marketing material, not an architecture document. Output: Context View

  7. Publish artifact (10 min) Owner: Owner Action: Check the artifact for completeness, define location, set version or status, and name review recipients. Output: Architecture Document

Closeout

  • Update result artifact: Architecture Document
  • Define location, version, and review recipients.
  • Define owner, next step, and review date.
Usable artifact

Work artifact

Pre-filled starting point based on the matching template.

work-artifact.md

Architecture Document: arc42

Working Question

Which architecture decisions, structures, and quality attributes does the reader need in order to understand, operate, and evolve the system?

Context

Current system overview; list of external interfaces; known quality goals, ideally from a Quality Attribute Workshop; constraints (regulatory, technical, organizational); existing diagrams.

Participants

  • Owner: One main author, often an architect or tech lead, as owner
  • Participants: One main author, often an architect or tech lead, as owner; one to three reviewers from Engineering and Ops; optional stakeholder from Business for chapter 1 (goals).

Input

arc42 template (Markdown version of arc42/arc42-template on GitHub); diagram tool (PlantUML, Structurizr, draw.io); repo directory docs/architecture/; glossary file; links to the ADR directory and possibly C4 diagrams.

Template

arc42 Working Template

Goal

Pragmatic template for structured, living software architecture documentation.

Context

When and for what do we use this method?

Input

Which data, observations, decisions, or materials are available?

Execution

Short notes along the runsheet.

Output artifacts

  • Architecture Document:
  • Context View:
  • Runtime View:
  • Deployment View:

Assumptions and open questions

  • ...

Decision / Next step

Owner, date, and success signal.

Completion Check

  • Architecture Document is complete enough for review:
  • Location:
  • Version / status:
  • Review by:
  • Next step:

Next Step

  • Review result
  • Mark open questions
  • Schedule review or decision
Template base

arc42 Working Template

View templateCompact working template for arc42 with context, input, output artifacts, and next step.
markdown

arc42-working-template.md

Compact working template for arc42 with context, input, output artifacts, and next step.

arc42 Working Template

Goal

Pragmatic template for structured, living software architecture documentation.

Context

When and for what do we use this method?

Input

Which data, observations, decisions, or materials are available?

Execution

Short notes along the runsheet.

Output artifacts

  • Architecture Document:
  • Context View:
  • Runtime View:
  • Deployment View:

Assumptions and open questions

  • ...

Decision / Next step

Owner, date, and success signal.

Ready to use when
  • Working question, owner, and target artifact are visible.
  • The result fits Architecture Document.
  • Docs are versioned in the same repo as the code. Changes go through pull requests with an architecture reviewer. Doc releases are tied to system releases (tag), so each code version has matching docs.
  • Open questions are noted as follow-ups.
  • The next review or decision point is scheduled.
ProfileRunsheet