smom-dbis-138/docs/architecture/ARCHITECTURE_DIAGRAMS.md

# 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

```bash
# 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](https://app.diagrams.net/)
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

```markdown
# 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

```markdown
# 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

- [Assets Guide](ASSETS_GUIDE.md)
- [Azure Architecture Center](https://docs.microsoft.com/azure/architecture/)
- [Azure Architecture Icons](https://docs.microsoft.com/azure/architecture/icons/)
- [Azure Architecture Patterns](https://docs.microsoft.com/azure/architecture/patterns/)
- [Draw.io Documentation](https://www.diagrams.net/doc/)

## Quick Reference

### Setup Assets
```bash
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/`