Skip to content

Commit 12c26d3

Browse files
kanfilkanfil
committed
fix(architect): add --views flag support and enforce Context View blackbox
- Add --views flag documentation to architect.implement command - core (default): 5 views (Context, Functional, Information, Development, Deployment) - all: all 7 views including Concurrency and Operational - Custom comma-separated selection - Mark Concurrency (3.4) and Operational (3.7) views as OPTIONAL - Skip entirely when not requested (no empty placeholders) - Add skip instructions and conditional generation rules - Fix Context View blackbox violation in all diagram generators - Remove internal components (Database, Cloud Services) from Context diagrams - Show system as single blackbox node - Only include stakeholders and external third-party systems - Add CRITICAL comments explaining blackbox requirement - Update AD-template.md with correct Context View example Files changed: - templates/commands/architect.implement.md - scripts/bash/ascii-generator.sh - scripts/bash/mermaid-generator.sh - scripts/powershell/ASCII-Generator.ps1 - scripts/powershell/Mermaid-Generator.ps1 - templates/AD-template.md
1 parent f9e8ab4 commit 12c26d3

File tree

6 files changed

+253
-78
lines changed

6 files changed

+253
-78
lines changed

‎scripts/bash/ascii-generator.sh‎

Lines changed: 47 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,61 @@
11
#!/usr/bin/env bash
22
# ASCII diagram generator for architecture views
33
# Generates ASCII art for all 7 Rozanski & Woods architectural views
4+
#
5+
# Core Views (always generated with --views=core):
6+
# - Context, Functional, Information, Development, Deployment
7+
#
8+
# Optional Views (only with --views=all or --views=concurrency,operational):
9+
# - Concurrency (3.4)
10+
# - Operational (3.7)
411

512
# Generate Context View diagram (system boundary)
13+
# CRITICAL: System must be shown as a SINGLE BLACKBOX - no internal components
14+
# Only show: Stakeholders (human actors) + External systems (third-party, outside your control)
15+
# DO NOT show: Internal databases, services, caches (those go in Deployment/Functional views)
616
generate_context_ascii() {
717
local system_name="${1:-System}"
818

919
cat <<'EOF'
1020
┌─────────────────────────────────────────────────────────────┐
1121
│ Context View Diagram │
22+
│ (System shown as single blackbox) │
1223
└─────────────────────────────────────────────────────────────┘
1324
14-
┌──────────────┐
15-
│ Users │
16-
└──────┬───────┘
17-
│
18-
▼
19-
┌───────────────────────────────────────┐
20-
│ │
21-
│ System (Main App) │
22-
│ │
23-
└───┬───────────┬───────────┬───────┬───┘
24-
│ │ │ │
25-
▼ ▼ ▼ ▼
26-
┌──────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐
27-
│ Database │ │ External │ │ Cloud │ │ Other │
28-
│ │ │ APIs │ │ Services │ │ Systems │
29-
└──────────┘ └──────────┘ └────────────┘ └──────────┘
25+
STAKEHOLDERS EXTERNAL SYSTEMS
26+
──────────── ────────────────
27+
28+
┌──────────────┐ ┌────────────────┐
29+
│ Users │ │ Payment │
30+
│ (End Users) │ │ Provider │
31+
└──────┬───────┘ │ (External) │
32+
│ └───────┬────────┘
33+
│ Uses │
34+
│ │ Processes
35+
▼ │ payments
36+
┌─────────────────────────────────────────────────────────┐
37+
│ │
38+
│ ┌─────────────────┐ │
39+
│ │ │ │
40+
│ │ SYSTEM │◄─────────────────┘
41+
│ │ (This App) │
42+
│ │ │──────────────────┐
43+
│ └─────────────────┘ │
44+
│ ▲ │
45+
│ │ │
46+
└─────────────────────────│───────────────────────────────┘
47+
│ Manages │
48+
┌──────────────┐ │ ▼
49+
│ Admins │──────────┘ ┌────────────────┐
50+
│(Administrators) │ Identity │
51+
└──────────────┘ │ Provider │
52+
│ (External) │
53+
└────────────────┘
54+
55+
Legend:
56+
─────► Data/control flow crossing system boundary
57+
[SYSTEM] = Single blackbox (internal details in Functional/Deployment views)
58+
(External) = Third-party services outside your control
3059
EOF
3160
}
3261

@@ -99,6 +128,7 @@ EOF
99128
}
100129

101130
# Generate Concurrency View diagram (process timeline)
131+
# OPTIONAL VIEW: Only generated when --views=all or --views=concurrency
102132
generate_concurrency_ascii() {
103133
cat <<'EOF'
104134
┌─────────────────────────────────────────────────────────────┐
@@ -219,6 +249,7 @@ EOF
219249
}
220250

221251
# Generate Operational View diagram (operational workflow)
252+
# OPTIONAL VIEW: Only generated when --views=all or --views=operational
222253
generate_operational_ascii() {
223254
cat <<'EOF'
224255
┌─────────────────────────────────────────────────────────────┐

‎scripts/bash/mermaid-generator.sh‎

Lines changed: 38 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,52 @@
11
#!/usr/bin/env bash
22
# Mermaid diagram generator for architecture views
33
# Generates Mermaid code for all 7 Rozanski & Woods architectural views
4+
#
5+
# Core Views (always generated with --views=core):
6+
# - Context, Functional, Information, Development, Deployment
7+
#
8+
# Optional Views (only with --views=all or --views=concurrency,operational):
9+
# - Concurrency (3.4)
10+
# - Operational (3.7)
411

512
# Generate Context View diagram (system boundary)
13+
# CRITICAL: System must be shown as a SINGLE BLACKBOX - no internal components
14+
# Only show: Stakeholders (human actors) + External systems (third-party, outside your control)
15+
# DO NOT show: Internal databases, services, caches (those go in Deployment/Functional views)
616
generate_context_mermaid() {
717
local system_name="${1:-System}"
818

919
cat <<'EOF'
1020
graph TD
11-
Users["👥 Users"]
12-
System["🏢 System<br/>(Main Application)"]
13-
Database["🗄️ Database"]
14-
ExternalAPI["🌐 External APIs"]
15-
CloudServices["☁️ Cloud Services"]
16-
17-
Users -->|Requests| System
18-
System -->|Queries| Database
19-
System -->|Integrates| ExternalAPI
20-
System -->|Deploys to| CloudServices
21-
22-
classDef systemNode fill:#f47721,stroke:#333,stroke-width:2px,color:#fff
21+
%% Stakeholders (human actors interacting with the system)
22+
Users["👥 Users/Clients"]
23+
Admins["👤 Administrators"]
24+
25+
%% THE SYSTEM - Single blackbox (NO internal components)
26+
System["🏢 System<br/>(This Application)"]
27+
28+
%% External Systems (third-party services outside your control)
29+
ExtPayment["💳 Payment Provider<br/>(External)"]
30+
ExtAuth["🔐 Identity Provider<br/>(External)"]
31+
ExtAPI["🌐 Partner API<br/>(External)"]
32+
33+
%% Stakeholder interactions
34+
Users -->|"Uses"| System
35+
Admins -->|"Manages"| System
36+
37+
%% External system integrations
38+
System -->|"Processes payments"| ExtPayment
39+
System -->|"Authenticates via"| ExtAuth
40+
System -->|"Exchanges data"| ExtAPI
41+
42+
%% Styling
43+
classDef systemNode fill:#f47721,stroke:#333,stroke-width:3px,color:#fff
44+
classDef stakeholderNode fill:#4a9eff,stroke:#333,stroke-width:1px,color:#fff
2345
classDef externalNode fill:#e0e0e0,stroke:#333,stroke-width:1px
2446
2547
class System systemNode
26-
class Users,Database,ExternalAPI,CloudServices externalNode
48+
class Users,Admins stakeholderNode
49+
class ExtPayment,ExtAuth,ExtAPI externalNode
2750
EOF
2851
}
2952

@@ -89,6 +112,7 @@ EOF
89112
}
90113

91114
# Generate Concurrency View diagram (process timeline)
115+
# OPTIONAL VIEW: Only generated when --views=all or --views=concurrency
92116
generate_concurrency_mermaid() {
93117
cat <<'EOF'
94118
sequenceDiagram
@@ -189,6 +213,7 @@ EOF
189213
}
190214

191215
# Generate Operational View diagram (operational workflow)
216+
# OPTIONAL VIEW: Only generated when --views=all or --views=operational
192217
generate_operational_mermaid() {
193218
cat <<'EOF'
194219
flowchart TD

‎scripts/powershell/ASCII-Generator.ps1‎

Lines changed: 47 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,18 @@
11
#!/usr/bin/env pwsh
22
# ASCII diagram generator for architecture views
33
# Generates ASCII art for all 7 Rozanski & Woods architectural views
4+
#
5+
# Core Views (always generated with --views=core):
6+
# - Context, Functional, Information, Development, Deployment
7+
#
8+
# Optional Views (only with --views=all or --views=concurrency,operational):
9+
# - Concurrency (3.4)
10+
# - Operational (3.7)
411

512
# Generate Context View diagram (system boundary)
13+
# CRITICAL: System must be shown as a SINGLE BLACKBOX - no internal components
14+
# Only show: Stakeholders (human actors) + External systems (third-party, outside your control)
15+
# DO NOT show: Internal databases, services, caches (those go in Deployment/Functional views)
616
function New-ContextAscii {
717
param(
818
[string]$SystemName = "System"
@@ -11,24 +21,43 @@ function New-ContextAscii {
1121
return @'
1222
┌─────────────────────────────────────────────────────────────┐
1323
│ Context View Diagram │
24+
│ (System shown as single blackbox) │
1425
└─────────────────────────────────────────────────────────────┘
1526
16-
┌──────────────┐
17-
│ Users │
18-
└──────┬───────┘
19-
│
20-
▼
21-
┌───────────────────────────────────────┐
22-
│ │
23-
│ System (Main App) │
24-
│ │
25-
└───┬───────────┬───────────┬───────┬───┘
26-
│ │ │ │
27-
▼ ▼ ▼ ▼
28-
┌──────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐
29-
│ Database │ │ External │ │ Cloud │ │ Other │
30-
│ │ │ APIs │ │ Services │ │ Systems │
31-
└──────────┘ └──────────┘ └────────────┘ └──────────┘
27+
STAKEHOLDERS EXTERNAL SYSTEMS
28+
──────────── ────────────────
29+
30+
┌──────────────┐ ┌────────────────┐
31+
│ Users │ │ Payment │
32+
│ (End Users) │ │ Provider │
33+
└──────┬───────┘ │ (External) │
34+
│ └───────┬────────┘
35+
│ Uses │
36+
│ │ Processes
37+
▼ │ payments
38+
┌─────────────────────────────────────────────────────────┐
39+
│ │
40+
│ ┌─────────────────┐ │
41+
│ │ │ │
42+
│ │ SYSTEM │◄─────────────────┘
43+
│ │ (This App) │
44+
│ │ │──────────────────┐
45+
│ └─────────────────┘ │
46+
│ ▲ │
47+
│ │ │
48+
└─────────────────────────│───────────────────────────────┘
49+
│ Manages │
50+
┌──────────────┐ │ ▼
51+
│ Admins │──────────┘ ┌────────────────┐
52+
│(Administrators) │ Identity │
53+
└──────────────┘ │ Provider │
54+
│ (External) │
55+
└────────────────┘
56+
57+
Legend:
58+
─────► Data/control flow crossing system boundary
59+
[SYSTEM] = Single blackbox (internal details in Functional/Deployment views)
60+
(External) = Third-party services outside your control
3261
'@
3362
}
3463

@@ -101,6 +130,7 @@ Key: PK = Primary Key, FK = Foreign Key
101130
}
102131

103132
# Generate Concurrency View diagram (process timeline)
133+
# OPTIONAL VIEW: Only generated when --views=all or --views=concurrency
104134
function New-ConcurrencyAscii {
105135
return @'
106136
┌─────────────────────────────────────────────────────────────┐
@@ -221,6 +251,7 @@ function New-DeploymentAscii {
221251
}
222252

223253
# Generate Operational View diagram (operational workflow)
254+
# OPTIONAL VIEW: Only generated when --views=all or --views=operational
224255
function New-OperationalAscii {
225256
return @'
226257
┌─────────────────────────────────────────────────────────────┐

‎scripts/powershell/Mermaid-Generator.ps1‎

Lines changed: 38 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,54 @@
11
#!/usr/bin/env pwsh
22
# Mermaid diagram generator for architecture views
33
# Generates Mermaid code for all 7 Rozanski & Woods architectural views
4+
#
5+
# Core Views (always generated with --views=core):
6+
# - Context, Functional, Information, Development, Deployment
7+
#
8+
# Optional Views (only with --views=all or --views=concurrency,operational):
9+
# - Concurrency (3.4)
10+
# - Operational (3.7)
411

512
# Generate Context View diagram (system boundary)
13+
# CRITICAL: System must be shown as a SINGLE BLACKBOX - no internal components
14+
# Only show: Stakeholders (human actors) + External systems (third-party, outside your control)
15+
# DO NOT show: Internal databases, services, caches (those go in Deployment/Functional views)
616
function New-ContextMermaid {
717
param(
818
[string]$SystemName = "System"
919
)
1020

1121
return @'
1222
graph TD
13-
Users["👥 Users"]
14-
System["🏢 System<br/>(Main Application)"]
15-
Database["🗄️ Database"]
16-
ExternalAPI["🌐 External APIs"]
17-
CloudServices["☁️ Cloud Services"]
18-
19-
Users -->|Requests| System
20-
System -->|Queries| Database
21-
System -->|Integrates| ExternalAPI
22-
System -->|Deploys to| CloudServices
23-
24-
classDef systemNode fill:#f47721,stroke:#333,stroke-width:2px,color:#fff
23+
%% Stakeholders (human actors interacting with the system)
24+
Users["👥 Users/Clients"]
25+
Admins["👤 Administrators"]
26+
27+
%% THE SYSTEM - Single blackbox (NO internal components)
28+
System["🏢 System<br/>(This Application)"]
29+
30+
%% External Systems (third-party services outside your control)
31+
ExtPayment["💳 Payment Provider<br/>(External)"]
32+
ExtAuth["🔐 Identity Provider<br/>(External)"]
33+
ExtAPI["🌐 Partner API<br/>(External)"]
34+
35+
%% Stakeholder interactions
36+
Users -->|"Uses"| System
37+
Admins -->|"Manages"| System
38+
39+
%% External system integrations
40+
System -->|"Processes payments"| ExtPayment
41+
System -->|"Authenticates via"| ExtAuth
42+
System -->|"Exchanges data"| ExtAPI
43+
44+
%% Styling
45+
classDef systemNode fill:#f47721,stroke:#333,stroke-width:3px,color:#fff
46+
classDef stakeholderNode fill:#4a9eff,stroke:#333,stroke-width:1px,color:#fff
2547
classDef externalNode fill:#e0e0e0,stroke:#333,stroke-width:1px
2648
2749
class System systemNode
28-
class Users,Database,ExternalAPI,CloudServices externalNode
50+
class Users,Admins stakeholderNode
51+
class ExtPayment,ExtAuth,ExtAPI externalNode
2952
'@
3053
}
3154

@@ -91,6 +114,7 @@ erDiagram
91114
}
92115

93116
# Generate Concurrency View diagram (process timeline)
117+
# OPTIONAL VIEW: Only generated when --views=all or --views=concurrency
94118
function New-ConcurrencyMermaid {
95119
return @'
96120
sequenceDiagram
@@ -191,6 +215,7 @@ graph TB
191215
}
192216

193217
# Generate Operational View diagram (operational workflow)
218+
# OPTIONAL VIEW: Only generated when --views=all or --views=operational
194219
function New-OperationalMermaid {
195220
return @'
196221
flowchart TD

0 commit comments

Comments
 (0)