# 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

```bash
./scripts/assets/setup-assets.sh
```

This creates the directory structure for assets.

### 2. Download Azure Icons

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

This downloads the official Azure Architecture Icons from Microsoft.

### 3. Create Draw.io Stencil

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

```markdown
![Azure Kubernetes Service](assets/azure-icons/svg/Icon-service-kubernetes-Azure.svg)
```

### In Presentations

Use PNG icons for presentations:

```markdown
![Azure Kubernetes Service](assets/azure-icons/png/Icon-service-kubernetes-Azure.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:

```json
{
  "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](https://docs.microsoft.com/azure/architecture/icons/)
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](https://docs.microsoft.com/azure/architecture/icons/)
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

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

## Quick Reference

### Download Icons
```bash
./scripts/assets/download-azure-icons.sh
```

### Setup Assets
```bash
./scripts/assets/setup-assets.sh
```

### Create Stencil
```bash
./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/`