Deployment/Physical Architecture Lens
Cognitive Mode: Physical
Primary Question: "Where does it run?"
Focus: Infrastructure Topology, Process Boundaries, Data Storage Locations, Network Communication
When to Use
- Need to understand physical deployment
- Documenting infrastructure and processes
- Analyzing where components execute
- User invokes
/autoskillit:arch-lens-deployment or /autoskillit:make-arch-diag deployment
Critical Constraints
NEVER:
- Modify any source code files
- Include code-level details
- Show internal logic
- Run subagents in the background (
run_in_background: true is prohibited)
ALWAYS:
Arguments
/autoskillit:arch-lens-deployment [context_path]
- context_path (optional) — Absolute path to a PR context file containing new files
(★-prefixed) and modified files (●-prefixed) from the PR diff. When provided, read
this file before beginning analysis and focus the diagram on the architectural areas
affected by these specific files. When absent, explore the full CWD.
Analysis Workflow
Step 0: Read PR context (when provided)
If a context_path positional argument is present:
- Read the file at
context_path
- Extract: new files list (★-prefixed), modified files list (●-prefixed)
- Focus Step 1 exploration on the modules/components these files belong to
- Apply ★ prefix on diagram nodes representing new files/components
- Apply ● prefix on diagram nodes representing modified files/components
If no context_path is provided, skip this step and explore the full CWD in Step 1.
Step 1: Launch Parallel Exploration Subagents
Spawn Explore subagents to investigate:
Process Boundaries
- Find main process entry points
- Identify subprocess spawning
- Look for: main, entry_points, subprocess, process spawning, daemon processes
Container/Docker
- Find containerization config
- Identify services
- Look for: Dockerfile, docker-compose.yml, container definitions, Kubernetes configs
Local Storage
- Find file storage locations
- Identify database paths
- Look for: data directories, database files, storage volumes, persistent storage
Network Services
- Find service definitions
- Identify ports and protocols
- Look for: port, bind, listen, server, API, endpoint, network services
External Services
- Find external API calls
- Identify cloud services
- Look for: external APIs, cloud services, third-party integrations
Web/Frontend
- Find frontend deployment
- Identify static file serving
- Look for: web servers, frontend builds, static assets, CDN
Step 2: Map Physical Topology
| Component |
Location |
Technology |
Port/Protocol |
| {name} |
{where} |
{tech} |
{port/protocol} |
CRITICAL - Analyze Read/Write Direction:
For EVERY process and storage location:
- Reads from: What does this process READ? (files, databases, APIs)
- Writes to: What does this process WRITE? (files, databases, APIs)
- Network direction: Client->Server or bidirectional?
For storage locations:
- Read/write storage: Process both reads and writes (databases, state files)
- Write-only storage: Process writes, humans or other systems read (logs, artifacts)
- Read-only sources: Process reads, doesn't modify (config, external APIs)
Label all connections with direction (reads, writes, or both)
Step 3: Identify Communication Paths
- Process-to-process (IPC, subprocess)
- Network (HTTP, WebSocket, gRPC)
- File system (shared files)
- Database (connections)
Step 4: Create the Diagram
Use flowchart with:
Direction: TB for infrastructure layers
Subgraphs by Physical Location:
- Developer Machine (local processes)
- Local Storage (files, DBs)
- Docker Stack (if containerized)
- Web Stack (if applicable)
- External Services (cloud, APIs)
Node Styling:
cli class: Main processes
stateNode class: Local storage, databases
output class: File artifacts
handler class: Services, APIs
phase class: Frontend, web UI
integration class: External services
Connection Labels:
- Show protocols (HTTP, subprocess, file)
- Show ports where relevant
Step 5: Write Output
Write the diagram to: {{AUTOSKILLIT_TEMP}}/arch-lens-deployment/arch_diag_deployment_{YYYY-MM-DD_HHMMSS}.md (relative to the current working directory)
After writing the diagram file, emit a structured output line:
IMPORTANT: Emit the structured output tokens as literal plain text with no
markdown formatting on the token names. Do not wrap token names in **bold**,
*italic*, or any other markdown. The adjudicator performs a regex match on the
exact token name — decorators cause match failure.
diagram_path = {absolute_path_to_diagram_file}
Output Template
# Deployment Diagram: {System Name}
**Lens:** Deployment/Physical
**Question:** Where does it run?
**Date:** {YYYY-MM-DD}
**Scope:** {What was analyzed}
## Deployment Topology
| Component | Port | Technology | Purpose |
|-----------|------|------------|---------|
| {name} | {port} | {tech} | {purpose} |
## Deployment Diagram
```mermaid
%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 60, 'curve': 'basis'}}}%%
flowchart TB
%% CLASS DEFINITIONS %%
classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
classDef integration fill:#c62828,stroke:#ef9a9a,stroke-width:2px,color:#fff;
subgraph LocalMachine ["LOCAL MACHINE"]
direction TB
MAIN["Main Process<br/>━━━━━━━━━━<br/>Runtime<br/>Orchestration"]
SUB["Subprocess<br/>━━━━━━━━━━<br/>Isolated execution"]
end
subgraph LocalStorage ["LOCAL STORAGE"]
direction TB
DB[("Database<br/>━━━━━━━━━━<br/>Technology<br/>Location")]
FILES["Files<br/>━━━━━━━━━━<br/>Artifacts<br/>Path"]
end
subgraph Docker ["DOCKER STACK"]
direction TB
SERVICE1["Service<br/>━━━━━━━━━━<br/>:port<br/>Purpose"]
end
subgraph Web ["WEB STACK"]
direction TB
API["API Server<br/>━━━━━━━━━━<br/>:port<br/>Protocol"]
FRONTEND["Frontend<br/>━━━━━━━━━━<br/>:port<br/>Technology"]
end
subgraph External ["EXTERNAL"]
direction TB
CLOUD["Cloud API<br/>━━━━━━━━━━<br/>Protocol<br/>Third-party"]
end
%% CONNECTIONS %%
MAIN -->|"spawns"| SUB
MAIN -->|"reads/writes"| DB
MAIN -->|"writes"| FILES
MAIN -->|"HTTPS"| CLOUD
SERVICE1 -->|"connects"| DB
API -->|"REST"| FRONTEND
%% CLASS ASSIGNMENTS %%
class MAIN,SUB cli;
class DB,FILES stateNode;
class SERVICE1,API handler;
class FRONTEND phase;
class CLOUD integration;
Color Legend:
| Color |
Category |
Description |
| Dark Blue |
Processes |
Local CLI and subprocess |
| Teal |
Storage |
Databases and file storage |
| Orange |
Services |
Backend services and APIs |
| Purple |
Frontend |
Web UI |
| Red |
External |
External/cloud services |
Communication Protocols
| From |
To |
Protocol |
Purpose |
| {source} |
{target} |
{protocol} |
{purpose} |
Storage Locations
| Data |
Location |
Technology |
| {data} |
{path} |
{tech} |
---
## Pre-Diagram Checklist
Before creating the diagram, verify:
- [ ] LOADED `/autoskillit:mermaid` skill using the Skill tool
- [ ] Using ONLY classDef styles from the mermaid skill (no invented colors)
- [ ] Diagram will include a color legend table
---
## Related Skills
- `/autoskillit:make-arch-diag` - Parent skill for lens selection
- `/autoskillit:mermaid` - MUST BE LOADED before creating diagram
- `/autoskillit:arch-lens-c4-container` - For container-level view
1---2name: arch-lens-deployment3categories: [arch-lens]4activate_deps: [mermaid]5description: Create Deployment/Physical architecture diagram showing infrastructure topology, process boundaries, and network communication. Physical lens answering "Where does it run?"6hooks:7 PreToolUse:8 - matcher: "*"9 hooks:10 - type: command11 command: "echo 'Deployment Lens - Analyzing infrastructure topology...'"12 once: true13metadata:14 source: https://skillmd.com/skills/talont-org/arch-lens-deployment15---1617# Deployment/Physical Architecture Lens1819**Cognitive Mode:** Physical20**Primary Question:** "Where does it run?"21**Focus:** Infrastructure Topology, Process Boundaries, Data Storage Locations, Network Communication2223## When to Use2425- Need to understand physical deployment26- Documenting infrastructure and processes27- Analyzing where components execute28- User invokes `/autoskillit:arch-lens-deployment` or `/autoskillit:make-arch-diag deployment`2930## Critical Constraints3132**NEVER:**33- Modify any source code files34- Include code-level details35- Show internal logic36- Run subagents in the background (`run_in_background: true` is prohibited)3738**ALWAYS:**39- Focus on PHYSICAL deployment40- Show process boundaries41- Include network/communication protocols42- Document storage locations43- BEFORE creating any diagram, LOAD the `/autoskillit:mermaid` skill using the Skill tool - this is MANDATORY44- If the Skill tool cannot be used (disable-model-invocation) or refuses this invocation, do NOT proceed with diagram creation. Abort this step and omit the diagram from output.45- After writing the diagram file, emit the **absolute path** as a structured output46 token as your final output. Resolve the relative `temp/arch-lens-deployment/...`47 save path to absolute by prepending the full CWD:48 ```49 diagram_path = /absolute/cwd/temp/arch-lens-deployment/{filename}.md50 ```51 This token is MANDATORY — the pipeline cannot proceed without it.5253## Arguments5455`/autoskillit:arch-lens-deployment [context_path]`5657- **context_path** (optional) — Absolute path to a PR context file containing new files58 (★-prefixed) and modified files (●-prefixed) from the PR diff. When provided, read59 this file before beginning analysis and focus the diagram on the architectural areas60 affected by these specific files. When absent, explore the full CWD.6162---6364## Analysis Workflow6566### Step 0: Read PR context (when provided)6768If a `context_path` positional argument is present:691. Read the file at `context_path`702. Extract: new files list (★-prefixed), modified files list (●-prefixed)713. Focus Step 1 exploration on the modules/components these files belong to724. Apply ★ prefix on diagram nodes representing new files/components735. Apply ● prefix on diagram nodes representing modified files/components7475If no `context_path` is provided, skip this step and explore the full CWD in Step 1.7677### Step 1: Launch Parallel Exploration Subagents7879Spawn Explore subagents to investigate:8081**Process Boundaries**82- Find main process entry points83- Identify subprocess spawning84- Look for: main, entry_points, subprocess, process spawning, daemon processes8586**Container/Docker**87- Find containerization config88- Identify services89- Look for: Dockerfile, docker-compose.yml, container definitions, Kubernetes configs9091**Local Storage**92- Find file storage locations93- Identify database paths94- Look for: data directories, database files, storage volumes, persistent storage9596**Network Services**97- Find service definitions98- Identify ports and protocols99- Look for: port, bind, listen, server, API, endpoint, network services100101**External Services**102- Find external API calls103- Identify cloud services104- Look for: external APIs, cloud services, third-party integrations105106**Web/Frontend**107- Find frontend deployment108- Identify static file serving109- Look for: web servers, frontend builds, static assets, CDN110111### Step 2: Map Physical Topology112113| Component | Location | Technology | Port/Protocol |114|-----------|----------|------------|---------------|115| {name} | {where} | {tech} | {port/protocol} |116117**CRITICAL - Analyze Read/Write Direction:**118For EVERY process and storage location:119- **Reads from**: What does this process READ? (files, databases, APIs)120- **Writes to**: What does this process WRITE? (files, databases, APIs)121- **Network direction**: Client->Server or bidirectional?122123For storage locations:124- **Read/write storage**: Process both reads and writes (databases, state files)125- **Write-only storage**: Process writes, humans or other systems read (logs, artifacts)126- **Read-only sources**: Process reads, doesn't modify (config, external APIs)127128Label all connections with direction (reads, writes, or both)129130### Step 3: Identify Communication Paths131132- Process-to-process (IPC, subprocess)133- Network (HTTP, WebSocket, gRPC)134- File system (shared files)135- Database (connections)136137### Step 4: Create the Diagram138139Use flowchart with:140141**Direction:** `TB` for infrastructure layers142143**Subgraphs by Physical Location:**144- Developer Machine (local processes)145- Local Storage (files, DBs)146- Docker Stack (if containerized)147- Web Stack (if applicable)148- External Services (cloud, APIs)149150**Node Styling:**151- `cli` class: Main processes152- `stateNode` class: Local storage, databases153- `output` class: File artifacts154- `handler` class: Services, APIs155- `phase` class: Frontend, web UI156- `integration` class: External services157158**Connection Labels:**159- Show protocols (HTTP, subprocess, file)160- Show ports where relevant161162### Step 5: Write Output163164Write the diagram to: `{{AUTOSKILLIT_TEMP}}/arch-lens-deployment/arch_diag_deployment_{YYYY-MM-DD_HHMMSS}.md` (relative to the current working directory)165166After writing the diagram file, emit a structured output line:167168> **IMPORTANT:** Emit the structured output tokens as **literal plain text with no169> markdown formatting on the token names**. Do not wrap token names in `**bold**`,170> `*italic*`, or any other markdown. The adjudicator performs a regex match on the171> exact token name — decorators cause match failure.172173```174diagram_path = {absolute_path_to_diagram_file}175```176177---178179## Output Template180181```markdown182# Deployment Diagram: {System Name}183184**Lens:** Deployment/Physical185**Question:** Where does it run?186**Date:** {YYYY-MM-DD}187**Scope:** {What was analyzed}188189## Deployment Topology190191| Component | Port | Technology | Purpose |192|-----------|------|------------|---------|193| {name} | {port} | {tech} | {purpose} |194195## Deployment Diagram196197```mermaid198%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 60, 'curve': 'basis'}}}%%199flowchart TB200 %% CLASS DEFINITIONS %%201 classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;202 classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;203 classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;204 classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;205 classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;206 classDef integration fill:#c62828,stroke:#ef9a9a,stroke-width:2px,color:#fff;207208 subgraph LocalMachine ["LOCAL MACHINE"]209 direction TB210 MAIN["Main Process<br/>━━━━━━━━━━<br/>Runtime<br/>Orchestration"]211 SUB["Subprocess<br/>━━━━━━━━━━<br/>Isolated execution"]212 end213214 subgraph LocalStorage ["LOCAL STORAGE"]215 direction TB216 DB[("Database<br/>━━━━━━━━━━<br/>Technology<br/>Location")]217 FILES["Files<br/>━━━━━━━━━━<br/>Artifacts<br/>Path"]218 end219220 subgraph Docker ["DOCKER STACK"]221 direction TB222 SERVICE1["Service<br/>━━━━━━━━━━<br/>:port<br/>Purpose"]223 end224225 subgraph Web ["WEB STACK"]226 direction TB227 API["API Server<br/>━━━━━━━━━━<br/>:port<br/>Protocol"]228 FRONTEND["Frontend<br/>━━━━━━━━━━<br/>:port<br/>Technology"]229 end230231 subgraph External ["EXTERNAL"]232 direction TB233 CLOUD["Cloud API<br/>━━━━━━━━━━<br/>Protocol<br/>Third-party"]234 end235236 %% CONNECTIONS %%237 MAIN -->|"spawns"| SUB238 MAIN -->|"reads/writes"| DB239 MAIN -->|"writes"| FILES240 MAIN -->|"HTTPS"| CLOUD241242 SERVICE1 -->|"connects"| DB243 API -->|"REST"| FRONTEND244245 %% CLASS ASSIGNMENTS %%246 class MAIN,SUB cli;247 class DB,FILES stateNode;248 class SERVICE1,API handler;249 class FRONTEND phase;250 class CLOUD integration;251```252253**Color Legend:**254| Color | Category | Description |255|-------|----------|-------------|256| Dark Blue | Processes | Local CLI and subprocess |257| Teal | Storage | Databases and file storage |258| Orange | Services | Backend services and APIs |259| Purple | Frontend | Web UI |260| Red | External | External/cloud services |261262## Communication Protocols263264| From | To | Protocol | Purpose |265|------|-----|----------|---------|266| {source} | {target} | {protocol} | {purpose} |267268## Storage Locations269270| Data | Location | Technology |271|------|----------|------------|272| {data} | {path} | {tech} |273```274275---276277## Pre-Diagram Checklist278279Before creating the diagram, verify:280281- [ ] LOADED `/autoskillit:mermaid` skill using the Skill tool282- [ ] Using ONLY classDef styles from the mermaid skill (no invented colors)283- [ ] Diagram will include a color legend table284285---286287## Related Skills288289- `/autoskillit:make-arch-diag` - Parent skill for lens selection290- `/autoskillit:mermaid` - MUST BE LOADED before creating diagram291- `/autoskillit:arch-lens-c4-container` - For container-level view