Architecture

Architecture Diagram Generator

Quick Start: Create HTML structure with flexible layout (single/double/triple column) → Define CSS styles for layers and grids → Add content with categorized panels → Use semantic colors for different layers.

Critical Rules

Rule 1: Direct HTML Embedding

IMPORTANT: Write architecture diagrams as direct HTML in Markdown. NEVER use code blocks ( `html ). The HTML should be embedded directly in the document without any fencing.

Rule 2: No Empty Lines in HTML Structure

CRITICAL: Do NOT add any empty lines within the HTML architecture diagram structure. Keep the entire HTML block continuous to prevent parsing errors.

Rule 3: Incremental Creation Approach

RECOMMENDED: Create architecture diagrams in multiple steps:

1. First: Create the overall framework (wrapper, sidebars, main structure) and define all CSS styles
2. Second: Add layer containers with titles
3. Third: Fill in components layer by layer
4. Fourth: Add detailed content and refinements

Rule 4: Flexible Layout Structure

Architecture diagrams can use flexible layouts based on complexity:

• Single Column: Main content only (for simple architectures)
• Two Column: Main content + one sidebar (left or right)
• Three Column: Full layout with both sidebars (for complex systems)
• Left Sidebar: Supporting systems (monitoring, operations, analytics)
• Main Content: Core architecture layers (user, application, data, infrastructure)
• Right Sidebar: Cross-cutting concerns (security, compliance, governance)

Rule 5: Layer-Based Organization

Each layer should have:

• Clear semantic meaning (User, Application, AI/Logic, Data, Infrastructure)
• Consistent color coding
• Grid-based layout for components
• Appropriate nesting for sub-components

Rule 6: Color Semantics

Use consistent semantic meaning for layers — the exact color palette varies by style (see examples). The standard semantic mapping:

• User Layer — user-facing interfaces and clients
• Application Layer — business logic and API services
• AI/Logic Layer — intelligence, rules, processing engines
• Data Layer — databases, caches, storage
• Infrastructure Layer — containers, networking, DevOps
• External Services — third-party APIs, cloud services (typically dashed border)

Style Examples

Choose a visual style that matches your project's tone and audience. Each example contains a complete, copy-ready HTML template.

| # | Style | File | Suitable For | |---|---|---|---| | 1 | Steel Blue | [styles/steel-blue.md](styles/steel-blue.md) | Consulting reports, banking/finance, government projects, RFP proposals | | 2 | Ember Warm | [styles/ember-warm.md](styles/ember-warm.md) | Retail/e-commerce, education platforms, lifestyle brands, cultural institutions | | 3 | Neon Dark | [styles/neon-dark.md](styles/neon-dark.md) | Tech talks, developer conferences, gaming platforms, cybersecurity dashboards | | 4 | Stark Block | [styles/stark-block.md](styles/stark-block.md) | Creative studios, education platforms, indie developers, tech blogs | | 5 | Ocean Teal | [styles/ocean-teal.md](styles/ocean-teal.md) | Travel platforms, logistics/shipping, green tech, weather/ocean projects | | 6 | Dusk Glow | [styles/dusk-glow.md](styles/dusk-glow.md) | Social media, entertainment platforms, martech, content creation tools | | 7 | Rose Bloom | [styles/rose-bloom.md](styles/rose-bloom.md) | Fashion/beauty, luxury brands, wedding platforms, premium memberships | | 8 | Sage Forest | [styles/sage-forest.md](styles/sage-forest.md) | Healthcare, agritech, clean energy, sustainability, bioinformatics | | 9 | Frost Clean | [styles/frost-clean.md](styles/frost-clean.md) | Design tools, developer docs, API references, minimalist SaaS | | 10 | Indigo Deep | [styles/indigo-deep.md](styles/indigo-deep.md) | Brand-consistent systems, enterprise white papers, internal platforms | | 11 | Pastel Mix | [styles/pastel-mix.md](styles/pastel-mix.md) | SaaS products, startups, general tech architecture, product docs | | 12 | Slate Dark | [styles/slate-dark.md](styles/slate-dark.md) | Enterprise dark mode, internal tools, developer dashboards |

Layout Examples

Choose a layout structure that fits your architecture's complexity. Layouts use wireframe style (no colors) to focus on structural patterns. Combine any layout with any style above.

| # | Layout | File | Best For | |---|---|---|---| | 1 | Three-Column | [layouts/three-column.md](layouts/three-column.md) | Complex systems with cross-cutting concerns and monitoring sidebars | | 2 | Single Stack | [layouts/single-stack.md](layouts/single-stack.md) | Simple services, microservice detail views, focused documentation | | 3 | Left Sidebar | [layouts/left-sidebar.md](layouts/left-sidebar.md) | Systems with operations/monitoring emphasis, DevOps-centric views | | 4 | Right Sidebar | [layouts/right-sidebar.md](layouts/right-sidebar.md) | Systems with security/compliance emphasis, governance-focused views | | 5 | Pipeline | [layouts/pipeline.md](layouts/pipeline.md) | Data pipelines, CI/CD flows, ETL processes, horizontal stage-based flows | | 6 | Two-Column Split | [layouts/two-column-split.md](layouts/two-column-split.md) | Before/after comparisons, dual-system views, migration architecture | | 7 | Dashboard | [layouts/dashboard.md](layouts/dashboard.md) | System overviews with KPIs, monitoring dashboards, executive summaries | | 8 | Grid Catalog | [layouts/grid-catalog.md](layouts/grid-catalog.md) | Service catalogs, component libraries, equal-weight microservices | | 9 | Banner + Center | [layouts/banner-center.md](layouts/banner-center.md) | Gateway-centric architectures, user-facing systems with shared infrastructure | | 10 | Nested Containers | [layouts/nested-containers.md](layouts/nested-containers.md) | Cloud deployments, VPC/network topology, environment isolation | | 11 | Layer Layouts | [layouts/layer-layouts.md](layouts/layer-layouts.md) | Per-layer layout patterns: grid, sub-group, product group, KPI, vertical stack, zones, inline pipeline, mixed width | | 12 | Connectors | [layouts/connectors.md](layouts/connectors.md) | SVG overlay connectors between components: solid/dashed lines, arrows, labels, curved & orthogonal paths |

Advanced Features

NOTE: These advanced components require additional CSS styles. Add these to your `` section:

.arch-product-group { display: flex; gap: 10px; }
.arch-product { flex: 1; border-radius: 8px; padding: 10px; background: rgba(255, 255, 255, 0.6); border: 1px dashed #d97706; }
.arch-product-title { font-size: 12px; font-weight: bold; color: #92400e; margin-bottom: 8px; text-align: center; }
.arch-subgroup { display: flex; gap: 8px; margin-top: 8px; }
.arch-subgroup-box { flex: 1; border-radius: 6px; padding: 8px; background: rgba(255, 255, 255, 0.5); border: 1px solid rgba(0, 0, 0, 0.08); }
.arch-subgroup-title { font-size: 10px; font-weight: bold; color: #374151; text-align: center; margin-bottom: 6px; }
.arch-user-types { display: flex; gap: 4px; justify-content: center; margin-top: 6px; }
.arch-user-tag { font-size: 9px; padding: 2px 6px; border-radius: 10px; background: rgba(59, 130, 246, 0.15); color: #1d4ed8; }
/* SVG connector lines between components */
.arch-conn { stroke: #94a3b8; stroke-width: 1.5; fill: none; }
.arch-conn-dashed { stroke: #94a3b8; stroke-width: 1.5; fill: none; stroke-dasharray: 6 4; }
.arch-conn-label { font-size: 9px; fill: #64748b; font-family: sans-serif; }

Custom Product Groups

For complex applications with multiple products/modules:

  
    🎯 Product A
    
      Feature 1Description
      Feature 2Key Feature
    
  
  
    📊 Product B
    
      Feature 3Description
      Feature 4Description
    
  

Sub-grouped Components

For detailed breakdowns within layers:

  
    Component Group A
    
      Service 1Details
      Service 2Details
      Service 3Details
    
  
  
    Component Group B
    
      Service 4Details
      Service 5Details
    
  

User Types/Tags

  Admin Users
  End Users
  API Clients
  Partners

Metrics and KPIs

99.9% Uptime
<200ms Response
1M+ Users

SVG Connectors Between Components

Use an SVG overlay to draw orthogonal (right-angle) connectors between components. Always use ` with M/L commands for strictly horizontal and vertical segments. Do NOT use `, Bézier curves, or diagonal lines. See [layouts/connectors.md](layouts/connectors.md) for full reference.

  
  
  
    
      
        
      
    
    
    
    
    
    
    data flow
  

Styling Reference

Common Classes (shared across all styles)

• .arch-wrapper — flex container for sidebar + main layout
• .arch-sidebar — fixed-width sidebar column
• .arch-main — flexible main content area
• .arch-layer — layer container (add semantic class: .user, .application, .ai, .data, .infra, .external)
• .arch-box — component box; .arch-box.highlight for key items; .arch-box.tech for smaller tech items
• .arch-grid-2 to .arch-grid-6 — grid column layouts
• .arch-sidebar-panel — sidebar panel container
• .arch-sidebar-item — sidebar item; .arch-sidebar-item.metric for highlighted metrics

Best Practices

HTML Usage Guidelines

1. Direct embedding only — Always embed HTML directly in Markdown, never use `html code blocks
2. No empty lines in structure — Keep the entire HTML block continuous without any empty lines
3. Incremental development — Build diagrams step by step:

• Start with basic framework and layout structure (single/two/three column as needed)
• Add empty layer containers with proper CSS classes
• Fill in content layer by layer from top to bottom
• Refine content and add highlights last

Architecture Design

1. Keep layers logically separated — Each layer should represent a clear architectural tier
2. Use consistent naming — Follow naming conventions for components and services
3. Highlight key components — Use .highlight class for critical components
4. Add technical details — Include technology stack info in `` tags
5. Balance information density — Don't overcrowd components with text
6. Use icons sparingly — Add emojis to titles for visual hierarchy
7. Maintain color semantics — Stick to the established color meanings
8. Consider responsive design — Grids automatically adapt to content

Capability Upgrade

Mode Selection

• Quick: 生成一张清晰的分层架构图。
• Standard: 输出业务、应用、数据、集成、基础设施和安全层的完整架构视图。
• Deep: 结合非功能需求、部署约束、数据流、系统边界和演进路线，形成架构说明包。

Architecture Decision Logic

架构图必须先明确目标：现状说明、目标蓝图、迁移路线、微服务拓扑、数据平台、AI 系统或安全架构。目标不同，层级、组件和连接关系不同。

Quality Gates

• [ ] 图中每个组件都有明确职责。
• [ ] 数据流、控制流和依赖关系不混淆。
• [ ] 关键非功能需求如性能、安全、可用性已反映。
• [ ] 没有为了美观加入无业务含义的组件。
• [ ] 输出能直接嵌入方案、PPT 或技术文档。

Deliverable Catalog

| Deliverable | When to use | Minimum content | Format | |-------------|-------------|-----------------|--------| | Layered architecture diagram | 展示系统总体架构 | 层级、组件、职责、连接和关键技术 | HTML / Markdown | | Target architecture blueprint | 设计目标状态 | 业务能力、应用、数据、集成、基础设施和安全 | HTML / PPT | | Deployment topology | 说明部署 | 环境、节点、网络、服务、存储和边界 | HTML / Markdown | | Non-functional requirement map | 架构评审 | 性能、可用性、安全、扩展性和运维要求 | Markdown / PPT | | Migration architecture view | 演进规划 | 当前、过渡、目标、依赖和风险 | PPT / Markdown | | Architecture review checklist | 评审前 | 范围、组件、接口、NFR、安全和可维护性 | Checklist |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: guoliang1114-boop
• Source: guoliang1114-boop/AriaAI
• License: MIT
• Homepage: https://aria.d2cgo.co/

Install and usage instructions live in the source repository linked above.