architecture-diagram

Architecture Diagram

This skill generates a two-layer architecture visualization: a high-level application architecture diagram and a detailed component relationship diagram. Produce both in a single pass and save to .github/modernize/assessment/engines/facts/architecture-diagram.md.

Input Parameters

• workspace-path (optional): Path to the project to analyze (defaults to current directory)

⚠ Mermaid Safety Constraints — read BEFORE you write any ```mermaid block

Mermaid is unforgiving: one illegal character anywhere in a block crashes the whole diagram with Syntax error in text, not just the offending line. There is no partial rendering. Stay strictly inside this subset:

1. Chart kind. Only flowchart TD (Step 1) or flowchart LR (Step 2). Never graph TD, never mixed.

2. Subgraph form. Always subgraph <AlphaNumId>["display label"]. The id must match [A-Za-z][A-Za-z0-9_]* (no spaces, no punctuation). NEVER use the anonymous form subgraph "label" — it crashes whenever the label contains (, ), :, /, -, etc., and the parser error appears on an unrelated line.

3. Node form. Only one of: Id["label"] (rectangle), Id(("label")) (circle), Id[("label")] (cylinder for data stores). Pick one shape per node — do not stack brackets.

4. Arrow form. Solid -->, dotted -.->. If you put a label on an arrow it MUST be double-quoted: -->|"label"|. Never bare -->|label|.

5. No line breaks in labels. The escape \n was removed in modern Mermaid and is the #1 cause of failures. Use <br/> in flowcharts when you really must break a line. Strongly prefer single-line ≤ 60-char labels — put detail in the Inventory / Stack tables instead.

6. Banned characters inside any label or subgraph title. Use the ASCII replacement:

   Banned	Why it breaks	Replacement
   \n (literal two chars)	escape removed	<br/> or drop
   — (em-dash, U+2014)	parser treats as edge	- (ASCII hyphen)
   – (en-dash, U+2013)	parser treats as edge	-
   { } (e.g. {id})	opens an entity block	drop braces — write id or :id
   " inside a label	closes the label early	' (single quote)
   | inside a label	breaks edge-label parser	rephrase
   @ # $ % &	unsafe in many positions	rephrase or drop
   ( ) outside a ["..."] quoted label	unbalanced parens crash	only inside the quoted label
   smart quotes " " ' '	not ASCII	regular " and '

7. Unique node IDs across the whole file. If Layer 1 has DB, Layer 2 cannot also have DB. Use DB1 and DB2 (or AppDb, ComponentDb).

8. subgraph must be closed by a matching end on its own line. No end, no diagram.

Mandatory self-attestation

Immediately before writing each ```mermaid opening fence, emit this exact one-line HTML comment in the markdown (the comment will not render — it is for your own visible attestation that you have re-checked the block):

<!-- mermaid-checked: no \n, no em-dash/en-dash, no {} in labels, subgraphs are id["label"], arrows are -->|"label"|, all subgraphs closed by end, ids unique -->

If you cannot truthfully emit that comment, fix the diagram first.

---

Execution Steps

Step 1: Generate Application Architecture Section

Analyze the project and produce the complete ## Application Architecture section in one pass.

Analysis:

• Examine build files (Java: pom.xml, build.gradle; .NET: *.csproj, *.sln; JS/TS: package.json, tsconfig.json)
• Review configuration files (application.properties, appsettings.json, .env, database/API configs)
• Scan key source files to extract: framework, major dependencies, data access patterns, external integrations, technology stack
• Identify application layers (UI, Business Logic, Data Access), data storage technologies, and external service dependencies

Diagram — Mermaid flowchart TD (re-read the Safety Constraints above before writing):

• Application layers with technology info (use subgraph for grouping)
• Data storage components (specific names like "PostgreSQL", "Redis")
• External service integrations
• Data flow with descriptive arrow labels

Do NOT include: individual classes/methods or migration directions.

Reference example (this block satisfies every Safety Constraint — match its shape):

<!-- mermaid-checked: no \n, no em-dash/en-dash, no {} in labels, subgraphs are id["label"], arrows are -->|"label"|, all subgraphs closed by end, ids unique -->

flowchart TD
    subgraph Client["Client Layer"]
        Browser["Web Browser"]
    end
    subgraph App["Application Layer - Spring Boot 2.7"]
        Web["Spring MVC + Thymeleaf"]
        Security["Spring Security"]
        Service["Business Services"]
    end
    subgraph Data["Data Layer"]
        JPA["Spring Data JPA"]
        DB[("PostgreSQL 14")]
        Cache[("Redis")]
    end
    subgraph External["External Services"]
        SMTP["SMTP Email Service"]
        S3["AWS S3 Storage"]
    end

    Browser -->|"HTTP requests"| Web
    Web --> Security -->|"authorized"| Service
    Service -->|"CRUD operations"| JPA
    JPA -->|"SQL queries"| DB
    Service -->|"session cache"| Cache
    Service -->|"send email"| SMTP
    Service -->|"file upload"| S3

Textual explanations (write immediately after the diagram):

• Technology Stack Summary table: Layer | Technology | Version | Purpose
• Data Storage & External Services: A short paragraph describing what databases, caches, message brokers, or external APIs are used and how they fit into the architecture
• Key Architectural Decisions: 1-3 bullet points on notable patterns (e.g., "Uses repository pattern with EF6", "Autofac DI with module-based registration")

⚠ Move detail OUT of node labels and INTO this table. A diagram with short labels and a rich table renders; a diagram with long labels does not.

Step 2: Generate Component Relationships Section

Analyze component interactions and produce the complete ## Component Relationships section in one pass.

Analysis:

• Identify key component types by framework conventions:
  • Java (Spring): Controllers, Services, Repositories, Configurations, Entities, DTOs, Listeners, Filters
  • Java (Jakarta EE): Servlets, EJBs, CDI Beans, JPA Entities, JAX-RS Resources
  • .NET (ASP.NET Core): Controllers, Services, Middleware, DbContext, Entities, Hubs, Filters
  • .NET (Blazor/MVC): Pages, Components, ViewModels
  • JavaScript/TypeScript (Node.js): Routes, Controllers, Services, Middleware, Models
  • JavaScript/TypeScript (React/Angular/Vue): Components, Hooks, Services, Stores, Pages
• Trace dependency injection (constructor/field injection)
• Map communication patterns (REST, gRPC, message queues, events)
• Map data access patterns (service-to-repository, DbContext usage)
• Detect cross-cutting concerns (middleware, interceptors, filters)

Diagram — Mermaid flowchart LR (re-read the Safety Constraints above before writing):

• Components grouped by architectural layer using subgraph (Presentation, Business Logic, Data Access, Infrastructure)
• Interaction arrows with brief labels
• Cross-cutting concerns
• Use IDs that do NOT collide with Step 1's diagram (e.g., prefix with c for Component: cWeb, cService).

Do NOT include: method signatures, private helpers, or external dependencies (covered by dependency-map skill).

Reference example (satisfies every Safety Constraint):

<!-- mermaid-checked: no \n, no em-dash/en-dash, no {} in labels, subgraphs are id["label"], arrows are -->|"label"|, all subgraphs closed by end, ids unique -->

flowchart LR
    subgraph PresentationLayer["Presentation"]
        UserCtrl["UserController"]
        OrderCtrl["OrderController"]
    end
    subgraph BusinessLayer["Business Logic"]
        UserSvc["UserService"]
        OrderSvc["OrderService"]
        NotifSvc["NotificationService"]
    end
    subgraph DataAccessLayer["Data Access"]
        UserRepo["UserRepository"]
        OrderRepo["OrderRepository"]
    end
    subgraph InfraLayer["Infrastructure"]
        AuthFilter["AuthenticationFilter"]
        LogMiddleware["LoggingMiddleware"]
    end

    UserCtrl -->|"delegates"| UserSvc
    OrderCtrl -->|"delegates"| OrderSvc
    OrderSvc -->|"lookups"| UserSvc
    OrderSvc -->|"triggers"| NotifSvc
    UserSvc -->|"queries"| UserRepo
    OrderSvc -->|"queries"| OrderRepo
    AuthFilter -.->|"intercepts"| UserCtrl
    AuthFilter -.->|"intercepts"| OrderCtrl
    LogMiddleware -.->|"wraps"| PresentationLayer

Textual explanation (write immediately after the diagram):

• Component Inventory table: Component | Layer | Type | Responsibility

Step 3: Save Output

Save the combined output to .github/modernize/assessment/engines/facts/architecture-diagram.md with this exact structure:

# Architecture Diagram

A brief introduction (1-2 sentences).

## Application Architecture

< Layer 1 Mermaid flowchart TD here >

### Technology Stack Summary

[Table: Layer | Technology | Version | Purpose]

### Data Storage & External Services

[Short paragraph on databases, caches, external APIs]

### Key Architectural Decisions

[1-3 bullet points on notable patterns]

## Component Relationships

< Layer 2 Mermaid flowchart LR here >

### Component Inventory

[Table: Component | Layer | Type | Responsibility]

Scaling Rules

• If the project has more than 30 components, aggregate by package/namespace (e.g., show com.example.orders as one node instead of listing every class) — this also keeps labels short and safe.
• Keep each diagram under 40 nodes to ensure readability and GitHub rendering compatibility.
• For multi-module projects, focus on inter-module boundaries in Layer 1 and key components within the most important modules in Layer 2.

Common failure patterns observed in past runs

Each row below is something the model actually produced and crashed the diagram. Use the ✅ form.

❌ Past mistake	✅ Safe form	Why the ❌ crashed
subgraph "Spring Boot Application (port 8080)"	subgraph SpringApp["Spring Boot Application (port 8080)"]	Anonymous subgraph + parentheses in title
HC["HomeController\n GET / — gallery page"]	HC["HomeController GET /"] (move detail to table)	Literal \n + em-dash
PHOTOS_TABLE["PHOTOS table\n id (UUID PK)\n photo_data (BLOB)"]	PHOTOS_TABLE["PHOTOS"] (columns belong in a table)	\n and overlong label
PFC["PhotoFileController\n GET /photo/{id}"]	PFC["PhotoFileController GET /photo/:id"]	\n + {id}
Spring["Spring Boot\n2.7.18"]	Spring["Spring Boot 2.7.18"]	\n
`A -->	fetches users	B`

Error Handling

• Unsupported project type: Output a single line: > ERROR: Unsupported project type. This skill supports Java, .NET, JavaScript, and TypeScript projects only.
• No source code found: Output: > ERROR: No recognized source files found at workspace-path. Verify the path is correct.
• Insufficient info: Generate a best-effort diagram from available data. Add a note inside the diagram: Note["Some components could not be identified"]

Success Criteria

• Layer 1 Mermaid diagram renders correctly showing architecture with technology names, data storage, and external dependencies
• Layer 1 is accompanied by Technology Stack Summary table, Data Storage & External Services paragraph, and Key Architectural Decisions
• Layer 2 Mermaid diagram renders correctly showing component interactions grouped by architectural layer
• Layer 2 is accompanied by Component Inventory table
• Every ```mermaid block is preceded by the <!-- mermaid-checked: ... --> attestation comment
• File saved to .github/modernize/assessment/engines/facts/architecture-diagram.md