1fb7266469
- 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.
271 lines
6.7 KiB
Markdown
271 lines
6.7 KiB
Markdown
# 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/`
|
|
|