# opencomputeproject/sai architecture

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

- Interactive diagram: https://gitdiagram.com/opencomputeproject/sai
- Repository: https://github.com/opencomputeproject/sai

## Overview

##### Main Components
- Core API & Interface Layer:
- Represented by the “inc” folder (with header files like sai.h, saiacl.h, etc.) which defines the SAI API.
- The “meta” folder contains support for metadata, RPC generators, and code that supports the API implementation.
- RPC and Thrift Interfaces:
- The “meta/rpc” directory and the dedicated “test/saithrift” and “test/saithriftv2” directories indicate that the SAI API is exposed via an RPC interface, with Thrift-based components generating server stubs and client proxies.
- P4 Backend and Extensions:
- The “flexsai/p4” directory contains a complete P4 compilable backend implementation that adapts SAI calls for programmable hardware.
- Testing and Validation:
- The “ptf” directory and “test” directories provide functional and unit test frameworks (using PTF and C++ based tests) to validate that the API and its implementations work correctly.
- Documentation and Proposals:
- The “doc” folder holds extensive documentation on various SAI proposals and design documents which describe architecture, extensions (ACL, ARS, etc.), and vendor-specific enhancements.
- Packaging and Integration:
- There are directories such as “debian”, “.github” and CI configuration files (azure-pipelines.yml) showing build, test, and packaging pipelines.

##### Relationships and Data Flows
- Link the P4 Backend component (flexsai/p4) to the SAI API to show that some implementations or emulations for programmable switches are mapped from SAI abstractions.
- Test Framework component (ptf and test directories) that invokes SAI functions and verifies behavior, clearly showing the flow from test client → RPC interface → SAI Core.
- CI/Packaging pipelines (via “.github”, “debian”, and “azure-pipelines”) which are used for building and deploying the software.

##### Architectural Patterns & Design Principles
- Abstraction and Layering: The clear separation between API definitions, RPC interface generation (meta/rpc and saithrift), and diverse test implementations emphasizes a layered architecture.
- Extensibility: The presence of many “doc” subdirectories (covering proposals on ACL, FEC, ECMP, etc.) and “experimental” directories signifies that the design is intended to support multiple features and vendor-specific extensions without altering the core API.
- Modularity: Components like the flexsai backend, RPC layer, and testing suites serve as modular parts that interact via well-defined interfaces.

##### Elements
- SAI Core API (headers and meta definitions)
- RPC/Thrift Interface Layer
- P4 / FlexSai Backend
- Testing Framework (PTF and Unit Tests)
- CI/CD & Packaging (build systems, deployment scripts)
- Documentation & Proposals (for context)
- How API calls propagate from test clients or external management systems through the RPC interface down to the core API.
- Build/test pipelines feeding into library updates.
- Clear Labels:

## Diagram (Mermaid)

```mermaid
flowchart TD
    EC("External Clients"):::external

    subgraph "RPC/Thrift Interface"
        R1("RPC (meta/rpc)"):::interface
        R2("RPC Thrift v1 (test/saithrift)"):::interface
        R3("RPC Thrift v2 (test/saithriftv2)"):::interface
    end

    subgraph "SAI Core API"
        A1("SAI Headers (inc)"):::core
        A2("SAI Metadata (meta)"):::core
    end

    subgraph "P4 Backend"
        P1("P4 Backend (flexsai/p4)"):::backend
    end

    subgraph "Testing Framework"
        T1("Testing (ptf & test)"):::test
    end

    subgraph "CI/CD & Packaging"
        C1("CI/CD (GitHub, Debian, Pipelines)"):::ci
    end

    subgraph "Documentation"
        D1("Documentation (doc)"):::doc
    end

    V1("Vendor Implementation"):::vendor

    EC --> R1
    EC --> R2
    EC --> R3

    T1 --> R1

    R1 --> A1
    R2 --> A1
    R3 --> A1
    R1 --> A2
    R2 --> A2
    R3 --> A2

    A1 --> P1
    A2 --> P1

    A1 --> V1
    A2 --> V1

    C1 --> A1
    C1 --> A2

    D1 --> A1
    D1 --> A2

    click A1 "https://github.com/opencomputeproject/sai/tree/master/inc/"
    click A2 "https://github.com/opencomputeproject/sai/tree/master/meta/"
    click R1 "https://github.com/opencomputeproject/sai/tree/master/meta/rpc/"
    click R2 "https://github.com/opencomputeproject/sai/tree/master/test/saithrift/"
    click R3 "https://github.com/opencomputeproject/sai/tree/master/test/saithriftv2/"
    click P1 "https://github.com/opencomputeproject/sai/tree/master/flexsai/p4/"
    click T1 "https://github.com/opencomputeproject/sai/tree/master/ptf/"
    click C1 "https://github.com/opencomputeproject/sai/tree/master/.github/"
    click D1 "https://github.com/opencomputeproject/sai/tree/master/doc/"

    classDef core fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef interface fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef backend fill:#ffcc99,stroke:#000,stroke-width:2px;
    classDef test fill:#ffb6c1,stroke:#000,stroke-width:2px;
    classDef ci fill:#d3d3d3,stroke:#000,stroke-width:2px;
    classDef doc fill:#ffff99,stroke:#000,stroke-width:2px;
    classDef vendor fill:#dda0dd,stroke:#000,stroke-width:2px;
    classDef external fill:#f0e68c,stroke:#000,stroke-width:2px;
```
