> ## Documentation Index
> Fetch the complete documentation index at: https://doc.blueapi.ir/llms.txt
> Use this file to discover all available pages before exploring further.

# EMEP Architecture Diagrams: Levels 1-3 and Runtime Views

> Mermaid source for Level 1 Executive, Level 2 Logical, Level 3 Internal, Runtime, Storage, GPU, Trust, Supply Chain, and Deployment topology diagrams.

EMEP architecture is documented at three levels of abstraction plus six specialized topology views. This page provides the Mermaid source for each diagram with a brief caption explaining its purpose.

## Level 1: Executive Architecture

```mermaid theme={null}
flowchart TB
    subgraph External["External Systems"]
        HF["Hugging Face Hub"]
        User["Research Engineer / MLOps"]
    end

    subgraph EMEP["EMEP Platform"]
        direction TB
        IF["Interface Layer<br/>CLI / API / Config"]
        OR["Orchestration<br/>ExperimentTracker / DeploymentManager"]
        CE["Core Engine<br/>Merge / Evolution / Evaluation"]
        SS["Serving & Storage<br/>Quantization / Inference"]
    end

    subgraph Output["Output"]
        Model["Released Model Artifact"]
        Metrics["Evaluation Report"]
    end

    User --> IF
    HF --> CE
    IF --> OR
    OR --> CE
    CE --> SS
    SS --> Model
    CE --> Metrics
```

Caption: The executive view shows EMEP as a black box between external model sources and released artifacts. Three internal layers handle interface, orchestration, and core processing.

## Level 2: Logical Architecture

```mermaid theme={null}
flowchart TB
    subgraph Interface["Interface Layer"]
        CLI["CLI Specification"]
        API["API Specification"]
        CFG["Configuration"]
    end

    subgraph Orchestration["Orchestration"]
        EXP["ExperimentTracker"]
        DM["DeploymentManager"]
    end

    subgraph Core["Core Engine"]
        direction TB
        MCA["ModelCompatibilityAnalyzer"]
        ML["ModelLoader"]
        TE["TensorEngine"]
        ME["MergeEngine"]
        CG["CandidateGenerator"]
        EE["EvolutionEngine"]
        EV["EvaluationEngine"]
        BE["BenchmarkEngine"]
        FE["FitnessEngine"]
        MR["ModelRegistry"]
        DR["DatasetRegistry"]
        AS["ArtifactStore"]
    end

    subgraph Serving["Serving & Storage"]
        QE["QuantizationEngine"]
        IB["InferenceBackend"]
    end

    CLI --> EXP
    API --> EXP
    CFG --> EXP
    EXP --> MR
    EXP --> AS
    EXP --> EE
    EXP --> EV
    MR --> ML
    MR --> AS
    MR --> MCA
    MCA --> ML
    MCA --> TE
    ML --> AS
    ML --> TE
    ME --> ML
    ME --> TE
    ME --> MCA
    ME --> CG
    CG --> AS
    CG --> MR
    EE --> ME
    EE --> FE
    EE --> CG
    EE --> EXP
    EV --> BE
    EV --> IB
    EV --> FE
    EV --> EXP
    BE --> DR
    BE --> AS
    FE --> EV
    DM --> QE
    DM --> IB
    DM --> AS
    DM --> MR
    DM --> EXP
    QE --> ML
    QE --> AS
    IB --> ML
    IB --> QE
```

Caption: The logical architecture maps all 16 core components into four groups. Arrows indicate runtime invocation direction. ExperimentTracker is the central hub.

## Level 3: TensorEngine Internals

```mermaid theme={null}
flowchart TB
    subgraph TE["TensorEngine"]
        direction TB
        VAL["Shape Validation"]
        ADD["Element-wise Addition"]
        SCL["Scaling / Rescaling"]
        MSK["Masking / Sparsification"]
        INT["Interpolation<br/>SLERP / Linear"]
        DIFF["Difference Computation<br/>Task Vector"]
        NORM["Normalization"]
    end

    subgraph Inputs["Inputs"]
        W1["Weights A"]
        W2["Weights B"]
        CFG["Merge Config<br/>strategy, ratio, density"]
    end

    subgraph Output["Output"]
        OW["Merged Weights"]
    end

    W1 --> VAL
    W2 --> VAL
    CFG --> VAL
    VAL --> DIFF
    W1 --> DIFF
    W2 --> DIFF
    DIFF --> MSK
    CFG --> MSK
    MSK --> ADD
    W1 --> ADD
    ADD --> SCL
    CFG --> SCL
    SCL --> INT
    W1 --> INT
    W2 --> INT
    CFG --> INT
    INT --> NORM
    NORM --> OW
```

Caption: TensorEngine decomposes into seven primitive operations. The exact path through the engine depends on the MergeStrategy selected in the merge config.

## Level 3: EvolutionEngine Internals

```mermaid theme={null}
flowchart TB
    subgraph EE["EvolutionEngine"]
        direction TB
        INIT["Population Initialization"]
        GEN["Genome Encoding"]
        MUT["Mutation Operators"]
        XO["Crossover Operators"]
        SEL["Selection<br/>Tournament / Elitism"]
        FIT["Fitness Evaluation"]
        PARETO["Pareto Front Update"]
        DIV["Diversity Enforcement"]
        STOP["Convergence Check"]
    end

    subgraph External["External Calls"]
        ME["MergeEngine"]
        FE["FitnessEngine"]
    end

    INIT --> GEN
    GEN --> MUT
    GEN --> XO
    MUT --> SEL
    XO --> SEL
    SEL --> ME
    ME --> FIT
    FIT --> FE
    FE --> PARETO
    PARETO --> DIV
    DIV --> STOP
    STOP -->|Not converged| MUT
    STOP -->|Converged| END["Return Pareto Front"]
```

Caption: EvolutionEngine orchestrates the iterative search loop. It calls MergeEngine to realize genomes and FitnessEngine to score candidates. Diversity enforcement and Pareto front updates prevent premature convergence.

## Runtime Topology

```mermaid theme={null}
flowchart TB
    subgraph Control["Control Plane"]
        API["API Server"]
        SCHED["Job Scheduler"]
    end

    subgraph Compute["Compute Plane"]
        GPU1["GPU Worker 1<br/>Merge / Evolution"]
        GPU2["GPU Worker 2<br/>Evaluation"]
        GPU3["GPU Worker 3<br/>Evaluation"]
        CPU1["CPU Worker 1<br/>Compatibility / Registry"]
    end

    subgraph Storage["Storage Plane"]
        OBJ["Object Store<br/>safetensors, manifests"]
        META["Metadata Store<br/>experiment logs, lineage"]
    end

    API --> SCHED
    SCHED --> GPU1
    SCHED --> GPU2
    SCHED --> GPU3
    SCHED --> CPU1
    GPU1 --> OBJ
    GPU2 --> OBJ
    GPU3 --> OBJ
    CPU1 --> META
    GPU1 --> META
    GPU2 --> META
    GPU3 --> META
```

Caption: The runtime topology separates control, compute, and storage. GPU workers handle tensor-intensive operations. CPU workers manage registry and metadata. The scheduler assigns jobs based on resource availability.

## Storage Tiers

```mermaid theme={null}
flowchart LR
    A["Hot Tier<br/>NVMe SSD<br/>Active experiments"]
    B["Warm Tier<br/>SATA SSD<br/>Recent artifacts"]
    C["Cold Tier<br/>Object Storage<br/>Archived experiments"]
    D["Backup Tier<br/>Off-site / Tape<br/>Disaster recovery"]

    A --> B
    B --> C
    C --> D

    style A fill:#ffebee
    style B fill:#fff3e0
    style C fill:#e3f2fd
    style D fill:#e8f5e9
```

Caption: Four storage tiers manage cost and access latency. Hot tier holds weights for active merges. Warm tier retains recent candidates. Cold tier archives completed experiments. Backup tier is for disaster recovery.

## GPU Topology

```mermaid theme={null}
flowchart TB
    subgraph Node1["GPU Node 1"]
        GPU1A["A100 80GB"]
        GPU1B["A100 80GB"]
        NIC1["NVLink + InfiniBand"]
    end

    subgraph Node2["GPU Node 2"]
        GPU2A["A100 80GB"]
        GPU2B["A100 80GB"]
        NIC2["NVLink + InfiniBand"]
    end

    GPU1A <-->|NVLink| GPU1B
    GPU2A <-->|NVLink| GPU2B
    NIC1 <-->|InfiniBand| NIC2
```

Caption: GPU nodes are paired A100s with NVLink intra-node and InfiniBand inter-node. Large model merges may require cross-node tensor sharding.

## Trust Boundary

```mermaid theme={null}
flowchart TB
    subgraph Untrusted["Untrusted Zone"]
        EXT["External Hub<br/>Public Internet"]
        USER["Unauthenticated User"]
    end

    subgraph DMZ["DMZ"]
        PROXY["Reverse Proxy<br/>TLS termination"]
        AUTH["Authentication<br/>API key validation"]
    end

    subgraph Trusted["Trusted Zone"]
        CORE["Core Engine<br/>Merge / Evolution / Eval"]
        STORE["ArtifactStore<br/>Signed artifacts"]
        REG["ModelRegistry"]
    end

    subgraph Secure["Secure Zone"]
        KEYS["HSM / Key Vault<br/>ed25519 signing keys"]
        AUDIT["Audit Log<br/>Append-only"]
    end

    EXT --> PROXY
    USER --> PROXY
    PROXY --> AUTH
    AUTH --> CORE
    CORE --> STORE
    CORE --> REG
    CORE --> KEYS
    CORE --> AUDIT
    STORE --> KEYS

    style Untrusted fill:#ffebee
    style DMZ fill:#fff3e0
    style Trusted fill:#e3f2fd
    style Secure fill:#e8f5e9
```

Caption: The trust boundary separates external untrusted traffic from the core engine. Authentication sits in the DMZ. Signing keys and audit logs are in the secure zone, accessible only to the core engine.

## Model Supply Chain

```mermaid theme={null}
sequenceDiagram
    actor User
    participant Hub as External Hub
    participant Import as ModelLoader
    participant Validate as ModelCompatibilityAnalyzer
    participant Sign as ArtifactStore
    participant Registry as ModelRegistry
    participant Track as ExperimentTracker

    User->>Hub: Request model import
    Hub->>Import: Download weights, config, tokenizer
    Import->>Validate: Submit for validation
    Validate->>Validate: Check architecture, shapes, tokenizer
    Validate->>Sign: Request signature
    Sign->>Sign: Compute ed25519 signature
    Sign->>Registry: Register with metadata
    Registry->>Track: Log IMPORTED → VALIDATED → REGISTERED
    Track->>User: Return model ID and signature
```

Caption: The model supply chain sequence shows every step from external download to registered, signed artifact. Each transition is logged and signed.

## Deployment Topology

```mermaid theme={null}
flowchart TB
    subgraph Build["Build Environment"]
        QE["QuantizationEngine"]
        PKG["Packaging"]
        SIG["Signing"]
    end

    subgraph Staging["Staging"]
        STG["Staging InferenceBackend"]
        VAL["Performance Validation"]
    end

    subgraph Prod["Production"]
        LB["Load Balancer"]
        INF1["Inference Node 1"]
        INF2["Inference Node 2"]
        MON["Monitoring"]
    end

    QE --> PKG
    PKG --> SIG
    SIG --> STG
    STG --> VAL
    VAL -->|Pass| LB
    VAL -->|Fail| QE
    LB --> INF1
    LB --> INF2
    INF1 --> MON
    INF2 --> MON
```

Caption: Deployment flows from build through staging validation to production serving. Failed validation returns to quantization for adjustment. Production nodes are monitored for health and latency.

## Next Steps

See [Algorithm Flowchart Index](/diagrams/algorithm-flowchart-index) for the standardized algorithm template, or [System Architecture](/architecture/system-architecture) for the prose specification of these views.