d-bis/smom-dbis-138
4
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity
Files
843cdbf71cc0551231e511d98cdd67a2932ef9d0
smom-dbis-138/docs/guides/ASSETS_GUIDE.md

7.0 KiB
Raw Blame History

Assets Guide

This guide explains how to use Azure Architecture Icons and other assets in the DeFi Oracle Meta Mainnet project.

Overview

The project includes Azure Architecture Icons and diagram templates for creating architecture diagrams, documentation, and presentations.

Directory Structure

assets/
├── azure-icons/          # Azure Architecture Icons
│   ├── svg/             # SVG format icons
│   ├── png/             # PNG format icons
│   └── metadata/        # Icon metadata and catalogs
├── diagrams/            # Architecture diagrams
│   ├── architecture/    # Architecture diagrams
│   ├── network/         # Network topology diagrams
│   ├── deployment/      # Deployment diagrams
│   └── templates/       # Diagram templates
├── stencils/            # Draw.io stencils
└── logos/               # Project and partner logos

Setting Up Assets

1. Create Directory Structure

./scripts/assets/setup-assets.sh

This creates the directory structure for assets.

2. Download Azure Icons

./scripts/assets/download-azure-icons.sh

This downloads the official Azure Architecture Icons from Microsoft.

3. Create Draw.io Stencil

./scripts/assets/create-diagram-stencil.sh

This creates a Draw.io stencil for easy icon access.

Using Azure Icons

In Draw.io / diagrams.net

  1. Import Icons Directly:

    • Open Draw.io
    • Click "More Shapes" (bottom left)
    • Click "+" to add a new library
    • Select "From Device"
    • Navigate to assets/azure-icons/svg/
    • Select the icons you want to use

  2. Use Icon Mapping:

    • See assets/azure-icons/metadata/icon-mapping.json for icon names
    • Import icons using the mapping file

  3. Manual Import:

    • Click "Insert" → "Image"
    • Select "From Device"
    • Navigate to assets/azure-icons/svg/
    • Select the icon file

In Documentation

Use icons in Markdown documentation:

../../assets/azure-icons/svg/<icon-file>.svg

In Presentations

Use PNG icons for presentations:

../../assets/azure-icons/png/<icon-file>.png

Icon Categories

Compute

  • Azure Kubernetes Service (AKS)
  • Virtual Machines
  • Container Instances
  • App Service
  • VM Scale Sets

Networking

  • Virtual Network
  • Application Gateway
  • Load Balancer
  • Network Security Groups
  • VPN Gateway
  • Private Endpoint

Storage

  • Storage Accounts
  • Blob Storage
  • File Shares
  • Managed Disks

Security

  • Key Vault
  • Azure Active Directory
  • Security Center
  • Firewall

Management

  • Resource Groups
  • Management Groups
  • Subscriptions
  • Monitor
  • Log Analytics Workspace

Database

  • Azure Database
  • Cosmos DB
  • SQL Database
  • PostgreSQL

Integration

  • API Management
  • Service Bus
  • Event Grid
  • Logic Apps

Creating Diagrams

Architecture Diagrams

  1. High-Level Architecture:

    • Overview of the entire system
    • Components and their relationships
    • Data flow

  2. Network Architecture:

    • Network topology
    • Subnets and security groups
    • Network connectivity

  3. Deployment Architecture:

    • Deployment topology
    • Resource groups
    • Deployment regions

  4. Security Architecture:

    • Security controls
    • Key Vault integration
    • Network security

Best Practices

  1. Use Consistent Icons: Use the same icon set across all diagrams
  2. Label Components: Label all components clearly
  3. Show Relationships: Show connections and data flows
  4. Include Legends: Add legends for complex diagrams
  5. Version Control: Keep diagrams in version control
  6. Document Changes: Document diagram changes in commits

Diagram Tools

Draw.io / diagrams.net

  • Free: Web-based diagramming tool
  • Supports: Azure icon stencils
  • Export: SVG, PNG, PDF
  • Integration: GitHub integration

Lucidchart

  • Professional: Diagramming tool
  • Features: Azure icon library, collaboration
  • Export: Multiple formats

Visio

  • Microsoft: Official diagramming tool
  • Features: Azure stencils, templates
  • Integration: Office integration

PlantUML

  • Text-based: Diagramming tool
  • Features: Version control friendly, automated generation
  • Integration: Documentation integration

Icon Mapping

See assets/azure-icons/metadata/icon-mapping.json for a complete mapping of icon names to files.

Example:

{
  "compute": {
    "azure-kubernetes-service": {
      "svg": "Icon-service-kubernetes-Azure.svg",
      "png": "Icon-service-kubernetes-Azure.png",
      "description": "Azure Kubernetes Service (AKS)"
    }
  }
}

Custom Icons

Blockchain Icons

Custom icons for blockchain components:

  • Hyperledger Besu
  • Validator Nodes
  • RPC Nodes
  • Oracle Nodes

Creating Custom Icons

  1. Create SVG or PNG files
  2. Place in assets/azure-icons/svg/ or assets/azure-icons/png/
  3. Update assets/azure-icons/metadata/icon-mapping.json
  4. Document in assets/azure-icons/metadata/icon-catalog.md

Updating Icons

Check for Updates

Azure icons are updated regularly. Check for updates:

  1. Visit Azure Architecture Center
  2. Download the latest version
  3. Run ./scripts/assets/download-azure-icons.sh

Version Control

Icons are tracked in Git. When updating:

  1. Download new icons
  2. Commit changes
  3. Update assets/azure-icons/metadata/download-info.json
  4. Document changes in commit message

Troubleshooting

Icons Not Downloading

If icons fail to download:

  1. Check internet connection
  2. Verify download URLs in script
  3. Manually download from Azure Architecture Center
  4. Extract to assets/azure-icons/

Icons Not Displaying

If icons don't display in diagrams:

  1. Verify icon files exist
  2. Check file paths
  3. Verify file formats (SVG/PNG)
  4. Check diagram tool compatibility

Missing Icons

If specific icons are missing:

  1. Check assets/azure-icons/metadata/icon-mapping.json
  2. Verify icon files exist
  3. Download latest icon set
  4. Create custom icons if needed

References

Quick Reference

Download Icons

./scripts/assets/download-azure-icons.sh

Setup Assets

./scripts/assets/setup-assets.sh

Create Stencil

./scripts/assets/create-diagram-stencil.sh

Icon Location

  • SVG: assets/azure-icons/svg/
  • PNG: assets/azure-icons/png/
  • Metadata: assets/azure-icons/metadata/

Diagram Location

  • Architecture: assets/diagrams/architecture/
  • Network: assets/diagrams/network/
  • Deployment: assets/diagrams/deployment/
  • Templates: assets/diagrams/templates/
Reference in New Issue View Git Blame Copy Permalink