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