d-bis/smom-dbis-138
4
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity
Files
main
smom-dbis-138/docs/architecture/ARCHITECTURE_DIAGRAMS.md
defiQUG 1fb7266469 Add Oracle Aggregator and CCIP Integration 
- Introduced Aggregator.sol for Chainlink-compatible oracle functionality, including round-based updates and access control.
- Added OracleWithCCIP.sol to extend Aggregator with CCIP cross-chain messaging capabilities.
- Created .gitmodules to include OpenZeppelin contracts as a submodule.
- Developed a comprehensive deployment guide in NEXT_STEPS_COMPLETE_GUIDE.md for Phase 2 and smart contract deployment.
- Implemented Vite configuration for the orchestration portal, supporting both Vue and React frameworks.
- Added server-side logic for the Multi-Cloud Orchestration Portal, including API endpoints for environment management and monitoring.
- Created scripts for resource import and usage validation across non-US regions.
- Added tests for CCIP error handling and integration to ensure robust functionality.
- Included various new files and directories for the orchestration portal and deployment scripts.
2025-12-12 14:57:48 -08:00

6.7 KiB
Raw Permalink Blame History

Architecture Diagrams Guide

This guide explains how to create and maintain architecture diagrams for the DeFi Oracle Meta Mainnet project.

Overview

Architecture diagrams are essential for understanding the system design, deployment topology, and component relationships. This project uses Azure Architecture Icons and diagram templates to create consistent, professional diagrams.

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

Creating Diagrams

Step 1: Setup Assets

# Setup assets directory
make -f Makefile.assets assets

# Download Azure icons
make -f Makefile.assets download-icons

Step 2: Choose a Tool

Draw.io / diagrams.net (Recommended)

  1. Open Draw.io
  2. Import Azure icons from assets/azure-icons/svg/
  3. Create your diagram
  4. Export to SVG, PNG, or PDF

Lucidchart

  1. Open Lucidchart
  2. Use Azure icon library
  3. Create your diagram
  4. Export to desired format

Visio

  1. Open Microsoft Visio
  2. Use Azure stencils
  3. Create your diagram
  4. Export to desired format

Step 3: Use Templates

Templates are available in assets/diagrams/templates/:

  • High-level architecture
  • Network architecture
  • Deployment architecture
  • Security architecture
  • Data flow diagrams

Step 4: Add Icons

Use icons from assets/azure-icons/svg/:

  • Azure Kubernetes Service (AKS)
  • Virtual Network
  • Application Gateway
  • Key Vault
  • Storage Account
  • And more...

See assets/azure-icons/metadata/icon-mapping.json for complete icon mapping.

Diagram Types

High-Level Architecture

Shows the overall system architecture:

  • Components and their relationships
  • Data flow
  • Key services
  • Integration points

Network Architecture

Shows network topology:

  • Virtual networks
  • Subnets
  • Network security groups
  • Network connectivity
  • Private endpoints

Deployment Architecture

Shows deployment topology:

  • Resource groups
  • Deployment regions
  • Availability zones
  • Node pools
  • Services

Security Architecture

Shows security controls:

  • Key Vault integration
  • Network security
  • Access controls
  • Security monitoring
  • Compliance

Data Flow Diagram

Shows data flow:

  • Transaction flow
  • Oracle data flow
  • API calls
  • Data storage
  • Data processing

Best Practices

Icon Usage

  1. Use Official Icons: Always use official Azure icons from Microsoft
  2. Maintain Consistency: Use the same icon set across all diagrams
  3. Use SVG Format: Prefer SVG for scalability
  4. Label Components: Label all components clearly
  5. Show Relationships: Show connections and data flows

Diagram Design

  1. Keep It Simple: Focus on key components and relationships
  2. Use Legends: Add legends for complex diagrams
  3. Use Colors: Use colors to distinguish components
  4. Group Related Components: Group related components together
  5. Show Data Flow: Show data flow with arrows

Documentation

  1. Include Descriptions: Add descriptions to diagrams
  2. Version Control: Keep diagrams in version control
  3. Document Changes: Document diagram changes in commits
  4. Update Regularly: Update diagrams when architecture changes
  5. Link to Documentation: Link diagrams to relevant documentation

Icon Mapping

Common Icons

Service SVG Icon PNG Icon
Azure Kubernetes Service Icon-service-kubernetes-Azure.svg Icon-service-kubernetes-Azure.png
Virtual Network Icon-service-virtual-network-Azure.svg Icon-service-virtual-network-Azure.png
Application Gateway Icon-service-application-gateway-Azure.svg Icon-service-application-gateway-Azure.png
Key Vault Icon-service-key-vaults-Azure.svg Icon-service-key-vaults-Azure.png
Storage Account Icon-service-storage-accounts-Azure.svg Icon-service-storage-accounts-Azure.png

See assets/azure-icons/metadata/icon-mapping.json for complete mapping.

Diagram Templates

High-Level Architecture Template

# High-Level Architecture

## Components
- Azure Kubernetes Service (AKS)
- Virtual Network
- Application Gateway
- Key Vault
- Storage Account
- Monitor

## Data Flow
1. Client → Application Gateway
2. Application Gateway → AKS
3. AKS → Key Vault
4. AKS → Storage Account

Network Architecture Template

# Network Architecture

## Virtual Network
- Address Space: 10.0.0.0/16

## Subnets
- AKS Subnet: 10.0.1.0/24
- Validators Subnet: 10.0.2.0/24
- Sentries Subnet: 10.0.3.0/24
- RPC Subnet: 10.0.4.0/24
- App Gateway Subnet: 10.0.5.0/24

## Network Security Groups
- Validators NSG: Allow internal only
- Sentries NSG: Allow P2P (30303)
- RPC NSG: Allow HTTPS (443)

Updating Diagrams

When to Update

Update diagrams when:

  • Architecture changes
  • New components are added
  • Components are removed
  • Relationships change
  • Deployment topology changes

How to Update

  1. Open the diagram file
  2. Make necessary changes
  3. Update icon references if needed
  4. Update documentation
  5. Commit changes with descriptive message

Version Control

Diagrams are tracked in Git:

  • Keep diagrams in assets/diagrams/
  • Use descriptive file names
  • Document changes in commit messages
  • Include diagrams in pull requests

References

Quick Reference

Setup Assets

make -f Makefile.assets assets
make -f Makefile.assets download-icons

Create Diagram

  1. Open Draw.io
  2. Import icons from assets/azure-icons/svg/
  3. Use templates from assets/diagrams/templates/
  4. Create diagram
  5. Export to SVG, PNG, or PDF

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