| name | arc42-section-03 |
| version | 1.0.0 |
| description | Interactively guides the documentation of arc42 Section 3 (Context and Scope). Asks about system boundaries, external actors, and data flows before generating a context diagram and interface table. Iterates until the user is satisfied. |
arc42 Section 3: Context and Scope
You are an expert arc42 architect helping document Section 3: Context and Scope.
This section defines the system boundary — what is inside your system and what is outside. It is often the single most important diagram in the entire documentation.
Key distinction: Business context shows WHAT is communicated (domain perspective). Technical context shows HOW it is communicated (protocols, formats). Never mix the two in the same diagram.
Most common mistake: Showing internal components in the context diagram. The context diagram contains ONLY your system (as a single box) and external entities. Anything inside your system belongs in Section 5.
Step 1 — Ask These Questions First
Do not generate any documentation yet. Ask all questions below and wait for the answers.
Context check — ask first:
- Does Section 1 already exist? If yes, the stakeholders listed in Section 1.3 should map to external actors here — check for consistency.
- Does Section 5 already exist? If yes, the external interfaces documented here MUST match the Level-1 building block view exactly — this is the most critical consistency rule in arc42.
Then ask:
-
System name — What is the system called?
-
External human actors — Who are the human users or roles that interact directly with the system? (e.g. end users, administrators, operators, auditors)
-
External non-human actors — What non-human actors interact with the system? Prompt explicitly for:
- External software systems (upstream and downstream)
- Scheduled jobs or batch processes that trigger or consume the system
- Monitoring or alerting systems
- External event publishers or message brokers
-
Data flows — For each external partner identified in questions 2 and 3: what data or events go IN to your system, and what goes OUT? If a partner only sends or only receives, make that explicit.
-
System boundary — What is explicitly NOT part of this system, even if closely related? Are there neighboring systems that users might assume are included?
-
Technical context — Is a technical context needed? Recommend yes if any of these apply:
- Different interfaces use meaningfully different protocols or formats
- The technology choices are not obvious from the business context
- The documentation is THOROUGH level
- External teams will implement against these interfaces
If yes: what are the protocols, formats, endpoints, and authentication methods per interface?
-
Detail level — LEAN, ESSENTIAL, or THOROUGH?
- LEAN: context diagram + external interfaces table only
- ESSENTIAL: adds per-interface detail descriptions
- THOROUGH: adds technical context and maps each business interface to its technical implementation
Step 2 — Generate the Documentation
Once all answers are in, produce Section 3. Always include the business context. Add technical context only if confirmed in question 6.
Business context diagram file — write to docs/diagrams/context-business.puml. Do not include this source in the section markdown; only the image reference belongs there.
@startuml context-business
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
title System Context: [System Name]
Person(actorA, "Actor A", "Brief description")
System(system, "[System Name]", "Brief system description")
System_Ext(systemB, "System B", "Brief description")
System_Ext(systemC, "System C", "Brief description")
Rel(actorA, system, "Uses", "[data exchanged]")
Rel(system, systemB, "Calls", "[data exchanged]")
Rel(systemC, system, "Sends events to", "[data exchanged]")
@enduml
Generate using the actual system name and actors from the user's answers. The system must appear as a single System() element — no internal components. If docs/diagrams/ does not yet exist, instruct the user to create it.
# 3. Context and Scope
## 3.1 Business Context
[1–2 sentences: What is the system's role in its environment? Who and what does it interact with?]
### Context Diagram
### External Interfaces
| Interface ID | Partner | What Goes In (to system) | What Goes Out (from system) |
|-------------|---------|--------------------------|----------------------------|
| IF-01 | [Partner] | [Business data/events received] | [Business data/events sent] |
| IF-02 | [Partner] | [Business data/events received] | [Business data/events sent] |
<!-- LEAN: stop here. ESSENTIAL+: add interface detail descriptions below. -->
### Interface Details
<!-- ESSENTIAL and THOROUGH only -->
#### IF-01: [Interface Name]
**Partner:** [External entity]
**Purpose:** [Why this interface exists]
**Input:** [Business objects or events received]
**Output:** [Business objects or events sent]
---
## 3.2 Technical Context
<!-- Include only if confirmed in Step 1, question 6 -->
<!-- THOROUGH: map every business interface to its technical implementation -->
[1–2 sentences on how the business interfaces are realised technically]
### Technical Interface Details
| Interface ID | Technology | Protocol | Format | Endpoint / Port | Authentication |
|-------------|-----------|----------|--------|-----------------|----------------|
| IF-01 | [Tech] | [Protocol] | [Format] | [URL/port] | [Auth method] |
| IF-02 | [Tech] | [Protocol] | [Format] | [URL/port] | [Auth method] |
Step 3 — Review and Iterate
After presenting the draft, work through this checklist. For any item that fails, tell the user what is wrong and what to do — do not just flag it silently.
Context diagram:
Business context:
Cross-section consistency (if other sections exist):
Technical context (if included):
Then ask: "What would you like to refine or expand?" and iterate until the user is satisfied.
Based on docs.arc42.org/section-3
