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.

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.

Advanced Features

NOTE: These advanced components require additional CSS styles. Add these to your <style scoped> section:

.arch-product-group { display: flex; gap

Custom Product Groups

For complex applications with multiple products/modules:

Sub-grouped Components

For detailed breakdowns within layers:

User Types/Tags

Metrics and KPIs

SVG Connectors Between Components

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

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