fix(architect): enforce blackbox system representation in Context View

kanfil · kanfil · commit f9e8ab441c2f · 2026-02-10T22:23:56.000+02:00
Updated architect commands to ensure Context View shows the system as a
single unified node with only external connections:

- Added critical constraint callout explaining blackbox requirement
- System must appear as ONE node (no internal components)
- Only stakeholders/users and external systems allowed
- Internal databases, services, caches excluded from Context View
- Added validation checklist with 5 verification points
- Updated diagram templates with proper styling for entity types
- Clear guidance on what belongs in Context vs Functional/Deployment views
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **Context View Blackbox Enforcement**: Updated architect commands to strictly enforce blackbox system representation in Context View
+  - System MUST appear as a single unified node (no internal components)
+  - Only external actors (stakeholders/users) and external systems shown
+  - Internal databases, services, caches explicitly excluded from Context View
+  - Added validation checklist to `architect.implement` command
+  - Updated diagram templates with proper styling for stakeholders vs external systems
+  - Clear guidance on what belongs in Context View vs Functional/Deployment views
+
 ### Added
 
 - **Lean Architecture Views**: Configurable view generation with core vs optional views
diff --git a/templates/architecture-template.md b/templates/architecture-template.md
@@ -51,6 +51,13 @@
 
 **Purpose**: Define system scope and external interactions
 
+> **CRITICAL CONSTRAINT**: The Context View presents the system as a **single blackbox**. Internal components, services, or implementation details must NOT appear here. Only show:
+>
+> - The system as ONE unified node
+> - External actors (users, stakeholders)
+> - External systems the system integrates with
+> - Data flows crossing the system boundary
+
 #### 3.1.1 System Scope
 
 [High-level description of what the system does and its boundaries]
@@ -59,32 +66,54 @@
 
 | Entity | Type | Interaction Type | Data Exchanged | Protocols |
 |--------|------|------------------|----------------|-----------|
-| [ENTITY_1] | User/System/API | [e.g., REST API, UI] | [e.g., User credentials, requests] | [e.g., HTTPS, WebSocket] |
+| [ENTITY_1] | User/Stakeholder | [e.g., Web UI, Mobile App] | [e.g., User credentials, requests] | [e.g., HTTPS] |
 | [ENTITY_2] | [External System] | [Integration method] | [Data format] | [Protocol] |
 
+**Entity Types** (for Context View):
+
+- **Stakeholders/Users**: Human actors who interact with the system
+- **External Systems**: Third-party services, APIs, or systems outside your control
+- **Data Sources**: External databases or data feeds the system consumes
+- **Data Sinks**: External systems that receive data from this system
+
 #### 3.1.3 Context Diagram
 
 **Note**: Diagrams are auto-generated based on your configured format (mermaid or ascii).
 To change format, edit `~/.config/specify/config.json` and set `architecture.diagram_format`.
 
+> **Blackbox Requirement**: The system MUST appear as a single node. Do NOT show internal components (databases, caches, services) that are part of this system. Internal details belong in the Functional View (3.2) and Deployment View (3.6).
+
 ```mermaid
 graph TD
-    Users["👥 Users"]
-    System["🏢 System<br/>(Main Application)"]
-    Database["🗄️ Database"]
-    ExternalAPI["🌐 External APIs"]
-    CloudServices["☁️ Cloud Services"]
+    %% Stakeholders/Users (external actors)
+    Users["👥 End Users"]
+    Admins["👤 Administrators"]
+    
+    %% THE SYSTEM (single blackbox)
+    System["🏢 [SYSTEM_NAME]<br/>(This System)"]
+    
+    %% External Systems (third-party, outside your control)
+    PaymentGateway["💳 Payment Gateway<br/>(External)"]
+    EmailService["📧 Email Service<br/>(External)"]
+    IdentityProvider["🔐 Identity Provider<br/>(External)"]
+    
+    %% Connections: Stakeholders to System
+    Users -->|"Uses via Web/Mobile"| System
+    Admins -->|"Manages via Admin Portal"| System
     
-    Users -->|Requests| System
-    System -->|Queries| Database
-    System -->|Integrates| ExternalAPI
-    System -->|Deploys to| CloudServices
+    %% Connections: System to External Systems
+    System -->|"Processes payments"| PaymentGateway
+    System -->|"Sends notifications"| EmailService
+    System -->|"Authenticates users"| IdentityProvider
     
-    classDef systemNode fill:#f47721,stroke:#333,stroke-width:2px,color:#fff
-    classDef externalNode fill:#e0e0e0,stroke:#333,stroke-width:1px
+    %% Styling: System as prominent blackbox, externals as grey
+    classDef systemNode fill:#f47721,stroke:#333,stroke-width:3px,color:#fff,font-weight:bold
+    classDef stakeholderNode fill:#4a9eff,stroke:#333,stroke-width:1px,color:#fff
+    classDef externalNode fill:#e0e0e0,stroke:#333,stroke-width:1px,color:#333
     
     class System systemNode
-    class Users,Database,ExternalAPI,CloudServices externalNode
+    class Users,Admins stakeholderNode
+    class PaymentGateway,EmailService,IdentityProvider externalNode
 ```
 
 #### 3.1.4 External Dependencies
diff --git a/templates/commands/architect.implement.md b/templates/commands/architect.implement.md
@@ -107,30 +107,74 @@ Generate views in this order (earlier views inform later ones):
 
 **ADRs to Reference**: System style, integration patterns, external dependencies
 
+> **CRITICAL: Blackbox Requirement**
+>
+> The Context View MUST show the system as a **single blackbox node**. This view answers: "What does the system connect to?" NOT "What's inside the system?"
+>
+> **DO include**:
+>
+> - The system as ONE unified node (no internal components)
+> - Stakeholders/Users (human actors)
+> - External systems (third-party services outside your control)
+> - Data flows crossing the system boundary
+>
+> **DO NOT include**:
+>
+> - Internal databases (those go in Deployment View)
+> - Internal services/microservices (those go in Functional View)
+> - Internal caches, queues, or storage (those go in Deployment View)
+> - Implementation details of any kind
+
 **Generate**:
 
 - System scope description (from system style ADR)
-- External entities table (from integration ADRs)
-- Context diagram (Mermaid format)
+- External entities table - ONLY stakeholders and external systems
+- Context diagram showing system as single blackbox
 - External dependencies table (from dependency ADRs)
 
 **Diagram Template**:
 
 ```mermaid
 graph TD
-    subgraph "External Entities"
-        Users["Users/Clients"]
-        ExtSystem["External System"]
-        ExtAPI["External API"]
-    end
+    %% Stakeholders (human actors interacting with the system)
+    Users["Users/Clients"]
+    Admins["Administrators"]
     
+    %% THE SYSTEM - Single blackbox (NO internal components)
     System["[System Name]<br/>(This System)"]
     
-    Users -->|"[Interaction]"| System
-    System -->|"[Interaction]"| ExtSystem
-    System -->|"[Interaction]"| ExtAPI
+    %% External Systems (third-party, outside your control)
+    ExtPayment["Payment Provider<br/>(External)"]
+    ExtAuth["Identity Provider<br/>(External)"]
+    ExtAPI["Partner API<br/>(External)"]
+    
+    %% Stakeholder interactions
+    Users -->|"Uses"| System
+    Admins -->|"Manages"| System
+    
+    %% External system integrations
+    System -->|"Processes payments"| ExtPayment
+    System -->|"Authenticates"| ExtAuth
+    System -->|"Exchanges data"| ExtAPI
+    
+    %% Styling
+    classDef systemNode fill:#f47721,stroke:#333,stroke-width:3px,color:#fff
+    classDef stakeholderNode fill:#4a9eff,stroke:#333,stroke-width:1px,color:#fff
+    classDef externalNode fill:#e0e0e0,stroke:#333,stroke-width:1px
+    
+    class System systemNode
+    class Users,Admins stakeholderNode
+    class ExtPayment,ExtAuth,ExtAPI externalNode
 ```
 
+**Validation Checklist** (verify before finalizing Context View):
+
+- [ ] System appears as exactly ONE node
+- [ ] No internal databases shown (e.g., PostgreSQL, Redis)
+- [ ] No internal services shown (e.g., AuthService, UserService)
+- [ ] All entities are either stakeholders OR external systems
+- [ ] All connections cross the system boundary
+
 #### 3.2 Functional View
 
 **Purpose**: Internal components, responsibilities, interactions
