# onexstack/onex architecture

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

- Interactive diagram: https://gitdiagram.com/onexstack/onex
- Repository: https://github.com/onexstack/onex

## Overview

##### Project Type and Purpose
- This is a Go-based, enterprise-grade cloud-native platform (“OneX”) that implements a full microservices ecosystem.
- It includes a custom Kubernetes API server with CRDs, a suite of controllers (controller-manager), multiple business services (cacheserver, gateway, fakeserver, nightwatch, toyblc, usercenter, pump, etc.), CLI tools (onex, onexctl), code-generation pipelines, and deployment manifests for Kubernetes.

##### File Structure Analysis
- Top-level “cmd/” directory holds each microservice or tool’s main.go (e.g., cmd/onex-apiserver, cmd/onex-gateway, cmd/onex-usercenter, cmd/onexctl, etc.).
- “internal/” and “pkg/” contain shared libraries: middleware, configuration, clients, contract definitions, code-gen tools, utilities.
- “api/” and “pkg/api/…” hold OpenAPI/Swagger specs and Protobuf/gRPC definitions.
- “manifests/” provides Kubernetes YAML, Helm charts, and Kustomize overlays for deploying all components and dependencies (etcd, Kafka, Jaeger, MariaDB, MongoDB, Redis, Traefik, etc.).
- “docs/” and “scripts/” drive documentation generation, build, test, and release workflows.

##### README Insights
- It uses Kubernetes CRD machinery for custom resources, follows controller–reconciler patterns, and exposes gRPC and REST endpoints for each service.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & Dev Tools Layer
    subgraph "User & Dev Tools"
        ONEX["onex CLI"]:::tools
        OXCTL["onexctl CLI"]:::tools
        GEN_DOCS["gen-docs"]:::tools
        GEN_SWAGGER["swagger-type-docs"]:::tools
        GEN_YAML["gen-yaml"]:::tools
    end

    %% Control Plane Layer
    subgraph "Control Plane"
        KUBEAPI["Kubernetes API Server"]:::control
        APISERVER["Custom API Server"]:::control
        subgraph "API Server Internals"
            APISERVER_INT["apiserver internals"]:::control
        end
        CONTROLLER["Controller-Manager"]:::control
        subgraph "Controller Internals"
            CONTROLLER_INT["controller internals"]:::control
        end
    end

    %% Data Plane Services Layer
    subgraph "Data Plane Services"
        GATEWAY["API Gateway"]:::service
        CACHESRV["CacheService"]:::service
        NIGHTWATCH["NightWatch"]:::service
        TOYBLC["Toy Blockchain"]:::service
        USRCENTER["User Center"]:::service
        PUMP["Pump (ETL)"]:::service
        FAKESRV["FakeServer"]:::service
        SHAREDAPI["Shared API Definitions"]:::tools
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        ETCD["etcd"]:::infra
        MARIADB["MariaDB/MySQL"]:::infra
        MONGO["MongoDB"]:::infra
        REDIS["Redis"]:::infra
        KAFKA["Kafka"]:::infra
        MINIO["MinIO/S3"]:::infra
        JAEGER["Jaeger (Tracing)"]:::infra
    end

    %% Connections - CLI to Control Plane & Gateway
    ONEX -->|"HTTP/gRPC call"| GATEWAY
    OXCTL -->|"kubeconfig"| APISERVER

    %% Control Plane interactions
    KUBEAPI <-->|"internal datastore"| ETCD
    APISERVER -->|"store CRD"| ETCD
    CONTROLLER -->|"Watch CRD"| APISERVER

    %% Data Plane interactions
    GATEWAY -->|"route"| CACHESRV
    GATEWAY -->|"route"| NIGHTWATCH
    GATEWAY -->|"route"| TOYBLC
    GATEWAY -->|"route"| USRCENTER
    GATEWAY -->|"route"| PUMP
    GATEWAY -->|"route"| FAKESRV

    CACHESRV -->|"read/write"| REDIS
    USRCENTER -->|"read/write"| MONGO
    NIGHTWATCH -->|"read/write"| MARIADB
    PUMP -->|"read/write"| MARIADB
    TOYBLC -->|"read/write"| MINIO
    FAKESRV -->|"read/write"| MONGO

    %% Messaging & Tracing
    CACHESRV -->|"publish"| KAFKA
    NIGHTWATCH -->|"publish"| KAFKA
    TOYBLC -->|"publish"| KAFKA
    USRCENTER -->|"publish"| KAFKA
    PUMP -->|"publish"| KAFKA
    FAKESRV -->|"publish"| KAFKA

    ONEX -->|"trace data"| JAEGER
    OXCTL -->|"trace data"| JAEGER
    APISERVER -->|"trace data"| JAEGER
    CONTROLLER -->|"trace data"| JAEGER
    CACHESRV -->|"trace data"| JAEGER
    NIGHTWATCH -->|"trace data"| JAEGER
    TOYBLC -->|"trace data"| JAEGER
    USRCENTER -->|"trace data"| JAEGER
    PUMP -->|"trace data"| JAEGER
    FAKESRV -->|"trace data"| JAEGER

    %% Code-Gen Tools to API Definitions
    GEN_DOCS -->|"generate docs"| SHAREDAPI
    GEN_SWAGGER -->|"generate swagger"| SHAREDAPI
    GEN_YAML -->|"generate yaml"| SHAREDAPI

    %% Click Events
    click ONEX "https://github.com/onexstack/onex/blob/master/cmd/onex/onex.go"
    click OXCTL "https://github.com/onexstack/onex/blob/master/cmd/onexctl/onexctl.go"
    click APISERVER "https://github.com/onexstack/onex/blob/master/cmd/onex-apiserver/apiserver.go"
    click APISERVER_INT "https://github.com/onexstack/onex/tree/master/internal/controlplane/apiserver"
    click CONTROLLER "https://github.com/onexstack/onex/blob/master/cmd/onex-controller-manager/controller-manager.go"
    click CONTROLLER_INT "https://github.com/onexstack/onex/tree/master/internal/controlplane/controller"
    click CACHESRV "https://github.com/onexstack/onex/blob/master/cmd/onex-cacheserver/main.go"
    click NIGHTWATCH "https://github.com/onexstack/onex/blob/master/cmd/onex-nightwatch/main.go"
    click TOYBLC "https://github.com/onexstack/onex/blob/master/cmd/onex-toyblc/main.go"
    click USRCENTER "https://github.com/onexstack/onex/blob/master/cmd/onex-usercenter/main.go"
    click PUMP "https://github.com/onexstack/onex/blob/master/cmd/onex-pump/main.go"
    click FAKESRV "https://github.com/onexstack/onex/tree/master/pkg/api/fakeserver"
    click GEN_DOCS "https://github.com/onexstack/onex/blob/master/cmd/gen-docs/gen_onexctl_docs.go"
    click GEN_SWAGGER "https://github.com/onexstack/onex/blob/master/cmd/gen-swaggertype-docs/swagger_type_docs.go"
    click GEN_YAML "https://github.com/onexstack/onex/blob/master/cmd/gen-yaml/gen_onexctl_yaml.go"
    click SHAREDAPI "https://github.com/onexstack/onex/tree/master/pkg/api"
    click ETCD "https://github.com/onexstack/onex/tree/master/manifests/installation/storage/etcd"
    click MARIADB "https://github.com/onexstack/onex/tree/master/manifests/installation/storage/mariadb"
    click MONGO "https://github.com/onexstack/onex/tree/master/manifests/installation/storage/mongo"
    click REDIS "https://github.com/onexstack/onex/tree/master/manifests/installation/storage/redis"
    click KAFKA "https://github.com/onexstack/onex/tree/master/manifests/installation/middleware/kafka"
    click JAEGER "https://github.com/onexstack/onex/tree/master/manifests/installation/middleware/jaeger"

    %% Styles
    classDef control fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef service fill:#DFF8D0,stroke:#028A0F,color:#028A0F
    classDef infra fill:#FFE0B2,stroke:#D46A00,color:#D46A00
    classDef tools fill:#E0E0E0,stroke:#888888,color:#333333
```
