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

# Architecture Diagram

**Last Updated**: 2025-01-27  
**Status**: Active

This document provides a visual representation of the system architecture using Mermaid diagrams.

## Network Topology

```mermaid
graph TB
    subgraph "Public Internet"
        Users[Users/Applications]
    end
    
    subgraph "Azure Cloud"
        subgraph "Application Gateway"
            AGW[API Gateway<br/>Rate Limiting<br/>HTTPS Termination]
        end
        
        subgraph "RPC Tier"
            RPC1[RPC Node 1]
            RPC2[RPC Node 2]
            RPC3[RPC Node 3]
        end
        
        subgraph "Sentry Tier"
            SENT1[Sentry 1]
            SENT2[Sentry 2]
            SENT3[Sentry 3]
        end
        
        subgraph "Validator Tier"
            VAL1[Validator 1<br/>Private Subnet]
            VAL2[Validator 2<br/>Private Subnet]
            VAL3[Validator 3<br/>Private Subnet]
            VAL4[Validator 4<br/>Private Subnet]
        end
        
        subgraph "Oracle System"
            PUB[Oracle Publisher]
            AGG[Oracle Aggregator<br/>Smart Contract]
        end
        
        subgraph "Monitoring"
            PROM[Prometheus]
            GRAF[Grafana]
            LOKI[Loki]
        end
        
        subgraph "Explorer"
            BS[Blockscout]
        end
    end
    
    Users --> AGW
    AGW --> RPC1
    AGW --> RPC2
    AGW --> RPC3
    
    RPC1 --> SENT1
    RPC2 --> SENT2
    RPC3 --> SENT3
    
    SENT1 --> VAL1
    SENT1 --> VAL2
    SENT2 --> VAL3
    SENT3 --> VAL4
    
    VAL1 <--> VAL2
    VAL2 <--> VAL3
    VAL3 <--> VAL4
    VAL4 <--> VAL1
    
    PUB --> AGG
    PUB --> RPC1
    
    RPC1 --> PROM
    RPC2 --> PROM
    RPC3 --> PROM
    VAL1 --> PROM
    VAL2 --> PROM
    VAL3 --> PROM
    VAL4 --> PROM
    
    PROM --> GRAF
    PROM --> LOKI
    
    RPC1 --> BS
```

## Deployment Flow

```mermaid
sequenceDiagram
    participant Admin
    participant Terraform
    participant Azure
    participant AKS
    participant Nodes
    
    Admin->>Terraform: terraform apply
    Terraform->>Azure: Create Infrastructure
    Azure-->>Terraform: Infrastructure Ready
    
    Admin->>AKS: Deploy Kubernetes Resources
    AKS->>Nodes: Create Pods
    Nodes-->>AKS: Pods Running
    
    Admin->>Nodes: Deploy Contracts
    Nodes-->>Admin: Contracts Deployed
    
    Admin->>Nodes: Verify Deployment
    Nodes-->>Admin: Deployment Verified
```

## Consensus Flow (QBFT)

```mermaid
sequenceDiagram
    participant V1 as Validator 1
    participant V2 as Validator 2
    participant V3 as Validator 3
    participant V4 as Validator 4
    
    V1->>V2: Propose Block
    V1->>V3: Propose Block
    V1->>V4: Propose Block
    
    V2->>V1: Vote
    V3->>V1: Vote
    V4->>V1: Vote
    
    Note over V1,V4: 3/4 votes received<br/>Block committed
    
    V1->>V2: Commit Block
    V1->>V3: Commit Block
    V1->>V4: Commit Block
```

## Oracle Data Flow

```mermaid
graph LR
    subgraph "External Sources"
        API1[Price API 1]
        API2[Price API 2]
        API3[Price API 3]
    end
    
    subgraph "Oracle Publisher"
        PUB[Publisher Service]
        AGG[Median Aggregation]
    end
    
    subgraph "Blockchain"
        CONTRACT[Oracle Aggregator<br/>Smart Contract]
    end
    
    API1 --> PUB
    API2 --> PUB
    API3 --> PUB
    
    PUB --> AGG
    AGG --> CONTRACT
    
    CONTRACT -->|Round Update| Users[Smart Contracts]
```

## Deployment Flow Diagram

```mermaid
graph TB
    subgraph "Deployment Process"
        START[Start Deployment]
        GEN[Generate Genesis & Keys]
        INFRA[Deploy Infrastructure]
        K8S[Deploy Kubernetes]
        MON[Deploy Monitoring]
        CONTRACTS[Deploy Contracts]
        SERVICES[Deploy Services]
        VERIFY[Verify Deployment]
        END[Deployment Complete]
    end
    
    START --> GEN
    GEN --> INFRA
    INFRA --> K8S
    K8S --> MON
    MON --> CONTRACTS
    CONTRACTS --> SERVICES
    SERVICES --> VERIFY
    VERIFY --> END
```

## Service Interaction Diagram

```mermaid
graph LR
    subgraph "Blockchain"
        CONTRACT[Smart Contracts]
    end
    
    subgraph "Services"
        ORACLE[Oracle Publisher]
        CCIP[CCIP Monitor]
        TOKEN[Tokenization Service]
    end
    
    subgraph "External"
        API[Price APIs]
        FIREFLY[Firefly]
        CACTI[Cacti]
    end
    
    API --> ORACLE
    ORACLE --> CONTRACT
    CONTRACT --> CCIP
    CCIP --> ALERT[Alerts]
    TOKEN --> FIREFLY
    FIREFLY --> CACTI
    CACTI --> CONTRACT
```

## Network Topology Diagram

```mermaid
graph TB
    subgraph "Internet"
        USERS[Users/Applications]
    end
    
    subgraph "Azure Cloud"
        subgraph "Public Layer"
            AGW[Application Gateway]
            RPC1[RPC Node 1]
            RPC2[RPC Node 2]
            RPC3[RPC Node 3]
        end
        
        subgraph "P2P Layer"
            SENT1[Sentry 1]
            SENT2[Sentry 2]
            SENT3[Sentry 3]
        end
        
        subgraph "Consensus Layer"
            VAL1[Validator 1<br/>Private]
            VAL2[Validator 2<br/>Private]
            VAL3[Validator 3<br/>Private]
            VAL4[Validator 4<br/>Private]
        end
    end
    
    USERS --> AGW
    AGW --> RPC1
    AGW --> RPC2
    AGW --> RPC3
    
    RPC1 --> SENT1
    RPC2 --> SENT2
    RPC3 --> SENT3
    
    SENT1 --> VAL1
    SENT1 --> VAL2
    SENT2 --> VAL3
    SENT3 --> VAL4
    
    VAL1 <--> VAL2
    VAL2 <--> VAL3
    VAL3 <--> VAL4
    VAL4 <--> VAL1
```

## Related Documentation

- [Architecture Documentation](ARCHITECTURE.md)
- [Services Architecture](SERVICES_ARCHITECTURE.md)
- [Network Documentation](NETWORK.md)
- [Deployment Guide](../deployment/DEPLOYMENT.md)

---

**Last Updated**: 2025-01-27