# nemoyuan2008/md-ml architecture

> Architecture diagram of the GitHub repository nemoyuan2008/md-ml, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nemoyuan2008/md-ml
- Repository: https://github.com/nemoyuan2008/md-ml

## Overview

##### Project type and purpose
- MD-ML is a C++20 research library implementing “MD-ML: Super Fast Privacy-Preserving Machine Learning for Malicious Security with a Dishonest Majority.”
- It provides a two-phase secure computation framework (offline preprocessing + online circuit evaluation) for neural-network inference and other linear/algebraic computations.

##### File structure
- Top-level: CMakeLists.txt, README.md, LICENSE, dummy.cpp
- src/
- utils/       → general helpers (Timer, tensor, linear_algebra, rand, IO)
- share/       → data representations (Spdz2kShare, Mod2PowN, IsSpdz2kShare)
- networking/  → Party class, handles peer-to-peer I/O and synchronization
- protocols/   → Gate abstractions (AddGate, MultiplyGate, Conv2DGate, Circuit, Input/Output Gate, etc.)
- fake-offline/→ simulation of offline preprocessing (FakeCircuit, FakeParty, FakeGate variants)
- experiments/ → concrete benchmarks and demos (dot-product, AlexNet on ImageNet), each with its own CMakeLists and party-0/party-1 executables

##### Insights from the README
- Build scripts orchestrate static library/executable creation for both the core library and the experiments.

##### Components
1. Application Layer (experiments/ executables)
2. Protocol Engine (src/protocols: Gate, Circuit, PartyWithFakeOffline)
3. Offline Preprocessing Module (src/fake-offline: FakeParty, FakeCircuit, FakeGate implementations)
4. Communication Layer (src/networking: Party class, sockets or TCP channels)
5. Share Abstraction (src/share: Spdz2kShare, Mod2PowN)
6. Utility Library (src/utils: Timer, tensor, linear algebra)
- Application → Protocol Engine: constructs circuit(s) and invokes `Circuit::run()`
- Protocol Engine → Offline Module: requests preprocessed triples/truncations via FakeParty API
- Protocol Engine ↔ Communication Layer: exchanges share-messages between parties in both phases
- Protocol Engine ↔ Share Abstraction: creates/manipulates Spdz2kShare objects for every gate operation
- All layers → Utility Library: for timing, random number generation, tensor ops
c. Architectural patterns & principles:
- Layered architecture (Utils → Share → Protocol → Application)
- Strategy/Plugin pattern for Gate implementations and for swapping real vs. fake offline preprocessing
- Peer-to-peer network topology for N parties (dishonest-majority setting)
- Circuit abstraction separating control flow from cryptographic primitives
d. Key technologies/frameworks:
- C++20 modules and templates for gate/share abstractions
- CMake for cross-platform build orchestration
- Boost.Asio (via Boost.System) or raw sockets for networking
- Eigen for local linear-algebra (conv2D, tensor manipulations)

##### Don’t overthink—capture every logical component and its dependencies.
- How CMake orchestrates building static libs and executables.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Dependencies
    Boost("Boost.Asio, Boost.System"):::external
    Eigen("Eigen"):::external

    %% Supporting Modules
    subgraph "Supporting Modules"
        direction TB
        Utils["Utility Library\n(src/utils/)"]:::support
        Networking["Communication Layer\n(src/networking/)"]:::support
    end

    %% Core Cryptographic Engines
    subgraph "Core Cryptographic Engines"
        direction TB
        Share["Share Abstraction\n(src/share/)"]:::core
        Offline["Offline Preprocessing Module\n(src/fake-offline/)"]:::core
        Protocol["Protocol Engine\n(src/protocols/)"]:::core
    end

    %% Application Layer
    Experiments["Application Layer\n(experiments/)"]:::app

    %% Connections
    Boost --> Utils
    Boost --> Share
    Boost --> Networking
    Boost --> Protocol
    Eigen --> Utils
    Eigen --> Share
    Eigen --> Protocol

    Utils --> Share
    Utils --> Networking
    Utils --> Protocol
    Utils --> Offline

    Networking <--> Protocol
    Protocol --> Offline
    Protocol <--> Share
    Experiments --> Protocol

    %% Multiple Parties Example
    subgraph "Peer-to-Peer Network"
        direction TB
        Party1("Party 1"):::peer
        Party2("Party 2"):::peer
        Party3("Party 3"):::peer
    end
    Party1 --- Networking
    Party2 --- Networking
    Party3 --- Networking

    %% Click Events
    click Utils "https://github.com/nemoyuan2008/md-ml/tree/master/src/utils/"
    click Networking "https://github.com/nemoyuan2008/md-ml/tree/master/src/networking/"
    click Share "https://github.com/nemoyuan2008/md-ml/tree/master/src/share/"
    click Offline "https://github.com/nemoyuan2008/md-ml/tree/master/src/fake-offline/"
    click Protocol "https://github.com/nemoyuan2008/md-ml/tree/master/src/protocols/"
    click Experiments "https://github.com/nemoyuan2008/md-ml/tree/master/experiments/"
    click Boost "https://github.com/nemoyuan2008/md-ml/blob/master/CMakeLists.txt"
    click Eigen "https://github.com/nemoyuan2008/md-ml/blob/master/CMakeLists.txt"

    %% Styles
    classDef core fill:#e0f7fa,stroke:#006064,color:#004d40
    classDef support fill:#e8f5e9,stroke:#1b5e20,color:#2e7d32
    classDef app fill:#fff3e0,stroke:#ef6c00,color:#e65100
    classDef external fill:#eceff1,stroke:#607d8b,color:#37474f,stroke-dasharray: 5 5
    classDef peer fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c,stroke-dasharray: 2 2
```
