# aalyria/api architecture

> Architecture diagram of the GitHub repository aalyria/api, 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/aalyria/api
- Repository: https://github.com/aalyria/api

## Overview

##### Project Type and Purpose
- The repository is primarily focused on providing Spacetime’s network APIs, which are organized into three main interfaces: the Northbound Interface (NBI), Southbound Interface (SBI), and Federation (East-West) API.
- It also includes an SBI agent implemented in Go (contained in the “agent” directory) that interacts with network devices, and there are sections for API definitions (gRPC/Protobufs in the “api” directory) and sample implementations or clients (Java and Python in their respective folders).
- The overall design enables orchestration and real-time control of network elements and interconnection among networks.

##### Analyzing the File Structure
- Top-Level Architecture: The project is modularized into multiple directories:
- “api” – Contains the gRPC and Protocol Buffers definitions for various API components (NBI, scheduling, federation, provisioning, telemetry, etc.).
- “agent” – Holds the code for the SBI agent in Go and includes several subdirectories that reflect modular internal components (like “internal”, “telemetry”, “enactment”, etc.) which are partitioned for tasks such as logging, task management, external process handling, and networking.
- “auth”, “java”, “py” – These directories indicate additional authentication components and language-specific sample implementations.
- “contrib” and “entity_samples” – These directories offer open-source contributions or tutorial examples, providing real-world scenario setups that may help users in building their own network scenarios.
- Supporting files such as Bazel configuration, tests, build scripts, and governance documents are also present, giving hints about how the project is built and deployed.

##### Key Components and Their Relationships
- APIs (Northbound, Southbound, Federation):
- The “api” directory is the central definition place for all API communications (including common messages, models, scheduling, telemetry, etc.). These definitions unify the interaction between the system’s internal components and external entities.
- SBI Agent:
- Found in the “agent” directory, this Go-based service likely implements communication with network devices. It contains further subdivisions for telemetry, enactment, external processes, and channel communications. Internally, it also integrates modules for configuration (e.g., configpb) and networking (e.g., netlink) supporting both operational logic and testing.
- Authentication and Client Implementations:
- The “auth” directory (and analogous directories for Java and Python) implement the authentication mechanisms (JWT management, call credentials) needed to secure access to the APIs.
- Developer Tools & Helpers:
- Tools like “nbictl” and other scripts (as in the “tools” directory) help with provisioning, testing, and simulation of API usage.

##### Architectural Patterns and Design Principles
- Modularity: The directory structure clearly shows a modular design, where API definitions, agent functionalities, and authentication are separated.
- Microservice/Service-Oriented Approach: While the project is distributed across multiple languages and components, each major functional area (e.g., API definitions vs. the SBI agent) can be seen as a service or module that interacts over well-defined interfaces (gRPC, Protocol Buffers).
- Separation of Concerns: The internal subdivisions (e.g., “telemetry”, “enactment”, “auth”) ensure that different aspects of the system—data collection, network control, and permission management—are clearly delineated.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "API Services"
        API["API Layer (gRPC/Protobuf Definitions)"]:::api
    end

    subgraph "SBI Agent"
        AG["SBI Agent Core (Go-based)"]:::agent
        subgraph "Internal Modules"
            TELE["Telemetry Module"]:::internal
            ENACT["Enactment Module"]:::internal
            NET["Networking Module"]:::internal
        end
        AG --> TELE
        AG --> ENACT
        AG --> NET
    end

    subgraph "Authentication Module"
        AUTH_GP["Auth (Go/Python)"]:::auth
        AUTH_JAVA["Auth (Java Sample)"]:::auth
        AUTH_PY["Auth (Python Sample)"]:::auth
    end

    subgraph "Developer Tools & Clients"
        DEV_JAVA["NBI Client (Java)"]:::client
        DEV_PY["NBI Client (Python)"]:::client
        DEV_TOOL["SBI Agent Management Tool"]:::client
    end

    subgraph "Supporting Infrastructure"
        BAZELRC[".bazelrc"]:::infra
        BUILD_FILE["BUILD"]:::infra
        MODULE_FILE["MODULE.bazel"]:::infra
        WORKSPACE_NODE["WORKSPACE"]:::infra
        BAZEL_DIR["bazel/"]:::infra
        CI_CD["CI/CD Workflows (.github/workflows)"]:::infra
    end

    %% Relationships between main components
    DEV_JAVA -->|"sends_request"| API
    DEV_PY -->|"sends_request"| API
    DEV_TOOL -->|"manages_agent"| AG

    AUTH_GP -->|"secures"| API
    AUTH_JAVA -->|"secures"| API
    AUTH_PY -->|"secures"| API

    API -->|"orchestrates"| AG

    %% Supporting Infrastructure connections (dashed lines)
    BAZELRC -.->|"build"| API
    BAZELRC -.->|"build"| AG
    BUILD_FILE -.->|"build"| API
    BUILD_FILE -.->|"build"| AG
    MODULE_FILE -.->|"build"| API
    MODULE_FILE -.->|"build"| AG
    WORKSPACE_NODE -.->|"build"| API
    WORKSPACE_NODE -.->|"build"| AG
    BAZEL_DIR -.->|"build"| API
    BAZEL_DIR -.->|"build"| AG
    CI_CD -.->|"deploy"| API
    CI_CD -.->|"deploy"| AG

    %% Click Events for component mapping
    click API "https://github.com/aalyria/api/tree/main/api/"
    click AG "https://github.com/aalyria/api/tree/main/agent/"
    click AUTH_GP "https://github.com/aalyria/api/tree/main/auth/"
    click AUTH_JAVA "https://github.com/aalyria/api/tree/main/java/com/aalyria/spacetime/authentication"
    click AUTH_PY "https://github.com/aalyria/api/tree/main/py/authentication"
    click DEV_JAVA "https://github.com/aalyria/api/tree/main/java/com/aalyria/spacetime/codesamples/nbi/client"
    click DEV_PY "https://github.com/aalyria/api/tree/main/py/codesamples"
    click DEV_TOOL "https://github.com/aalyria/api/tree/main/tools/nbictl"
    click BAZELRC "https://github.com/aalyria/api/blob/main/.bazelrc"
    click BUILD_FILE "https://github.com/aalyria/api/tree/main/BUILD"
    click MODULE_FILE "https://github.com/aalyria/api/blob/main/MODULE.bazel"
    click WORKSPACE_NODE "https://github.com/aalyria/api/tree/main/WORKSPACE"
    click BAZEL_DIR "https://github.com/aalyria/api/tree/main/bazel/"
    click CI_CD "https://github.com/aalyria/api/tree/main/.github/workflows"

    %% Styles
    classDef api fill:#f9c,stroke:#333,stroke-width:2px;
    classDef agent fill:#ccf,stroke:#333,stroke-width:2px;
    classDef internal fill:#cfc,stroke:#333,stroke-width:2px;
    classDef auth fill:#fc9,stroke:#333,stroke-width:2px;
    classDef client fill:#9cf,stroke:#333,stroke-width:2px;
    classDef infra fill:#ff9,stroke:#333,stroke-width:2px;
```
