# appnet-org/appnet architecture

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

## Overview

- Kubernetes Cluster Components:
- Controller/Manager: Represented by the “cmd” and “internal/controller” directories. Indicate that this component watches and reconciles custom resources defined in the “api” directory.
- Custom Resource Definitions (CRDs): Highlight the “config/crd” directory that holds YAML definitions (e.g., appnetconfigs) to be installed in the cluster.
- RBAC & Additional Configurations: Use “config/rbac”, “config/manager”, and “config/prometheus” directories to illustrate security policies and monitoring setups.
- CLI Tool:
- Auxiliary and Supporting Components:
- Compiler: Although its exact purpose may be specialized, include the “compiler” directory to show any domain-specific functionalities or intermediary processing of definitions.
- Utilities & Helpers: Represent the “utils”, “hack”, and “go-lib” directories that support deployment scripts, performance testing, and additional tooling.
- External Dependencies:
- Docker: Indicate that a Dockerfile, .dockerignore, and Makefile are used to containerize and deploy the manager and related components.
- Kubernetes API Server: Show an interaction between the deployed controller, the CRDs it manages, and the API server.
- Registry / Build Pipeline: Include representation of CI workflows (in .github/workflows) and the Makefile automation for building and deploying images.

##### Out Relationships and Data Flow
- User Interaction:
- Controller Operation:
- Custom Resources:
- Flow where CRD configurations (from config/crd) are installed into the cluster and later processed by the controller.
- Build & Deployment:
- Testing/Utilities:
- Components for End-to-End tests (under “test/e2e”) and utility scripts used for setup (from “utils”).

##### Important Architectural Patterns
- Kubernetes Operator Pattern: Emphasize that AppNet follows the operator design pattern—watching for CR changes, reconciling state, and using Kubernetes-native APIs.
- Separation of Concerns: Indicate a clear separation between API definitions, business logic (controller), and user interfaces (CLI tool). Highlight that configuration management is handled via Kustomize overlays.
- Extensibility and Modularity: Note the modular structure (e.g., separate directories for API, controller, and CLI), making it easier to extend or contribute new components.

##### Relevant Technologies and Frameworks
- Golang: The primary language, which can be noted since much of the code (under “internal”, “appnetctl”, and “cmd”) is written in Go.
- Kubernetes and Kubebuilder: Clearly indicate that the operator is built on top of the Kubernetes API along with Kubebuilder’s scaffolding.
- Docker & Kustomize: Highlight the use of Docker for containerization and Kustomize for configuration overlays during deployment.
- CI/CD and Testing: Incorporate the GitHub workflows for submission checks (e.g., pre-commit hooks and automated tests under “test/e2e”).

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interaction
    A["AppNetCTL CLI"]:::client
    B["Kubernetes API Server"]:::external

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        subgraph "Controller/Manager"
            C1["cmd (Main)"]:::internal
            C2["Controller Logic"]:::internal
            C1 -->|"initiates"| C2
        end
        D["CRDs"]:::internal
        E["RBAC Policies"]:::internal
        F["Manager Config"]:::internal
        G["Prometheus Monitoring"]:::internal
    end

    %% CI/CD & Build Pipeline
    subgraph "CI/CD & Build Pipeline"
        H1["Makefile & Build Automation"]:::external
        H2["GitHub Workflows"]:::external
        H1 -->|"triggers"| H2
    end

    %% Utilities & Helpers
    subgraph "Utilities & Helpers"
        U1["Utils"]:::support
        U2["Hack"]:::support
        U3["Go-Lib"]:::support
    end

    %% Auxiliary Component: Compiler
    I["Compiler"]:::support

    %% Docker Containerization
    subgraph "Docker Containerization"
        K1["Root Dockerfile"]:::external
        K2["Load Manager Dockerfile"]:::external
        K3["Shard Manager Dockerfile"]:::external
    end

    %% Connections
    A -->|"CR_submission"| B
    B -->|"watch"| C1
    C1 -->|"status_update"| B
    H1 -->|"deploys"| C1
    I -->|"compile_definitions"| C1
    U1 -->|"assist"| H1
    U2 -->|"assist"| H1
    U3 -->|"assist"| H1
    C1 -->|"reconciles"| D

    %% Click Events
    click A "https://github.com/appnet-org/appnet/tree/main//appnetctl/"
    click C1 "https://github.com/appnet-org/appnet/blob/main//cmd/main.go"
    click C2 "https://github.com/appnet-org/appnet/tree/main//internal/controller/"
    click D "https://github.com/appnet-org/appnet/tree/main//config/crd/"
    click E "https://github.com/appnet-org/appnet/tree/main//config/rbac/"
    click F "https://github.com/appnet-org/appnet/tree/main//config/manager/"
    click G "https://github.com/appnet-org/appnet/tree/main//config/prometheus/"
    click H1 "https://github.com/appnet-org/appnet/tree/main//Makefile"
    click H2 "https://github.com/appnet-org/appnet/tree/main//.github/workflows/"
    click I "https://github.com/appnet-org/appnet/tree/main//compiler/"
    click U1 "https://github.com/appnet-org/appnet/tree/main//utils/"
    click U2 "https://github.com/appnet-org/appnet/tree/main//hack/"
    click U3 "https://github.com/appnet-org/appnet/tree/main//go-lib/"
    click K1 "https://github.com/appnet-org/appnet/tree/main/Dockerfile"
    click K2 "https://github.com/appnet-org/appnet/tree/main//utils/loadmanager/"
    click K3 "https://github.com/appnet-org/appnet/tree/main//utils/shardmanager/"

    %% Styles
    classDef client fill:#FDEDEC,stroke:#333,stroke-width:2px;
    classDef external fill:#E8F8F5,stroke:#333,stroke-width:2px;
    classDef internal fill:#E8DAEF,stroke:#333,stroke-width:2px;
    classDef support fill:#FCF3CF,stroke:#333,stroke-width:2px;
```
