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 colors for layer types:

• User Layer: Blue gradient (#dbeafe to #bfdbfe)
• Application Layer: Yellow/Orange gradient (#fef3c7 to #fde68a)
• AI/Logic Layer: Green gradient (#dcfce7 to #bbf7d0)
• Data Layer: Pink gradient (#fce7f3 to #fbcfe8)
• Infrastructure Layer: Purple gradient (#e0e7ff to #c7d2fe)
• External Services: Gray gradient (#f1f5f9 to #e2e8f0) with dashed border

Basic Architecture Template

USAGE NOTE: Copy the HTML below directly into your Markdown document. Do NOT wrap it in code blocks. Remove all empty lines to keep it continuous.

Advanced Features

NOTE: These advanced components require additional CSS styles. Add these to your <style scoped> 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; }

Custom Product Groups

For complex applications with multiple products/modules:

<div class="arch-product-group">
  <div class="arch-product">
    <div class="arch-product-title">🎯 Product A</div>
    <div class="arch-grid arch-grid-2">
      <div class="arch-box">Feature 1<br><small>Description</small></div>
      <div class="arch-box highlight">Feature 2<br><small>Key Feature</small></div>
    </div>
  </div>
  <div class="arch-product">
    <div class="arch-product-title">📊 Product B</div>
    <div class="arch-grid arch-grid-2">
      <div class="arch-box">Feature 3<br><small>Description</small></div>
      <div class="arch-box">Feature 4<br><small>Description</small></div>
    </div>
  </div>
</div>

Sub-grouped Components

For detailed breakdowns within layers:

<div class="arch-subgroup">
  <div class="arch-subgroup-box">
    <div class="arch-subgroup-title">Component Group A</div>
    <div class="arch-grid arch-grid-3">
      <div class="arch-box tech">Service 1<br><small>Details</small></div>
      <div class="arch-box tech">Service 2<br><small>Details</small></div>
      <div class="arch-box tech">Service 3<br><small>Details</small></div>
    </div>
  </div>
  <div class="arch-subgroup-box">
    <div class="arch-subgroup-title">Component Group B</div>
    <div class="arch-grid arch-grid-2">
      <div class="arch-box tech">Service 4<br><small>Details</small></div>
      <div class="arch-box tech">Service 5<br><small>Details</small></div>
    </div>
  </div>
</div>

User Types/Tags

Add user type indicators:

<div class="arch-user-types">
  <span class="arch-user-tag">Admin Users</span>
  <span class="arch-user-tag">End Users</span>
  <span class="arch-user-tag">API Clients</span>
  <span class="arch-user-tag">Partners</span>
</div>

Metrics and KPIs

Highlight important metrics in sidebar:

<div class="arch-sidebar-item metric">99.9% Uptime</div>
<div class="arch-sidebar-item metric">&lt;200ms Response</div>
<div class="arch-sidebar-item metric">1M+ Users</div>

Styling Reference

Layer Classes

• .arch-layer.user - Blue gradient for user-facing components
• .arch-layer.application - Yellow/Orange for application services
• .arch-layer.ai - Green for AI/ML/Logic components
• .arch-layer.data - Pink for data storage and processing
• .arch-layer.infra - Purple for infrastructure components
• .arch-layer.external - Gray dashed for external dependencies

Box Classes

• .arch-box - Standard component box
• .arch-box.highlight - Highlighted/key components (yellow)
• .arch-box.tech - Technical components (smaller text)

Grid Classes

• .arch-grid-2 to .arch-grid-6 - 2 to 6 column responsive grids

Sidebar Classes

• .arch-sidebar-panel - Panel container
• .arch-sidebar-item - Regular sidebar item
• .arch-sidebar-item.metric - Highlighted metric item

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 <small> 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

Use Cases

• Microservices Architecture - Show service boundaries and dependencies
• Enterprise Application Architecture - Display multi-tier application structure
• Cloud Infrastructure - Illustrate cloud service dependencies
• Data Pipeline Architecture - Show data flow through processing layers
• AI/ML System Architecture - Highlight ML components and data flows
• Security Architecture - Emphasize security controls across layers
• DevOps Architecture - Show CI/CD and deployment infrastructure