# avitaltamir/cyphernetes architecture

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

- Interactive diagram: https://gitdiagram.com/avitaltamir/cyphernetes
- Repository: https://github.com/avitaltamir/cyphernetes

## Overview

##### Project type and purpose
- This is a multi‐package, full‐stack tool (“Cyphernetes”) providing:
- A Go-based CLI (cmd/cyphernetes)
- A core query engine library (pkg/core) and API-server provider (pkg/provider/apiserver)
- A React/TypeScript web UI (web/)
- A Kubernetes operator (operator/) for DynamicOperator CRDs

##### File structure
- Top-level packages:
- cmd/cyphernetes – CLI entrypoint with subcommands (web, shell, query, graph, macro, autocomplete)
- pkg/core – parser, lexer, query engine, graph operations, relationship resolution
- pkg/provider/apiserver – implements provider interface against Kubernetes API server
- web/ – React app built with Vite, serves UI for interactive queries
- operator/ – controller-runtime Go operator, CRD definitions, deploy manifests, Helm chart
- Configuration and CI: GitHub workflows, Makefile orchestrates build/test for CLI, operator, and web client

##### README insights
- Core functionality: Cypher-inspired DSL over Kubernetes object graph
- Multiple execution modes: CLI, shell, single query, web UI, in-cluster operator
- Operator uses DynamicOperator CRD to embed queries into Kubernetes workflows

##### Main components and interactions
A. CLI Binary (Go)
- Subcommands invoke core pkg/core and provider
- “cyphernetes web” spins up embedded HTTP server serving static web assets
B. Core Engine (pkg/core)
- Lexer → Parser → Query planner/engine → executes graph ops
C. Provider Layer (pkg/provider/apiserver)
- Fetches resource objects and watches via Kubernetes API (client-go)
D. Web UI (React/TS)
- Queries CLI HTTP API (REST or WebSocket)
- Displays query input, graph visualizations, results
E. Kubernetes Operator
- Controller-runtime manager
- Watches DynamicOperator CRDs
- Runs core engine in-cluster to apply graph operations
- Uses CRD YAML (operator/config/crd) and Helm chart for deployment

##### Architectural patterns and design principles
- Modular monorepo: clear separation of CLI, core library, provider, UI, operator
- Adapter pattern: provider interface abstracts backend (only apiserver implementation today)
- MVC-like on client side: React components (View), queryApi.ts (Controller), core engine (Model)
- Controller-Runtime operator follows Kubernetes Operator pattern (Reconcile loop)

##### Elements
- CLI → Core Engine → Provider → K8s API
- Web UI ↔ CLI HTTP endpoint
- Operator reconciler loops: CRD → Controller → Core Engine → API Server

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    subgraph "End-User / Client Layer"
        direction TB
        CLIUser("Bash / Scripts") 
        Browser("Browser") 
    end

    %% CLI & Web Server Layer
    subgraph "CLI & Web Server Layer"
        direction TB
        CLI["CLI (Go)\n- shell, query, graph, macro, autocomplete\n- embedded web server"]:::go
        WebServer["HTTP Server\n(serves Web UI assets)"]:::go
        WebUI["Web UI (React/TS)"]:::js
    end

    %% Core & Provider Layer
    subgraph "Core & Provider Layer"
        direction TB
        CoreEngine["Core Engine\n(lexer→parser→planner→executor)"]:::go
        Provider["Apiserver Provider\n(K8s API client)"]:::go
    end

    %% Kubernetes Cluster Layer
    subgraph "Kubernetes Cluster" 
        direction TB
        APIServer["K8s API Server"]:::k8s
        CRD["DynamicOperator CRD"]:::k8s
        Operator["Operator Controller"]:::k8s
    end

    %% Connections: User to CLI/Web
    CLIUser -->|"runs commands"| CLI
    Browser -->|"accesses"| WebUI
    CLI -->|"spins up"| WebServer
    WebServer -->|"serves"| WebUI

    %% Web UI to CLI HTTP API
    WebUI -->|"GraphQL/REST"| WebServer
    WebServer -->|"forwards request"| CoreEngine

    %% CLI normal execution
    CLI -->|"invokes"| CoreEngine
    CoreEngine -->|"uses"| Provider
    Provider -->|"calls"| APIServer

    %% Operator flow
    CRD -->|"watch"| Operator
    Operator -->|"executes"| CoreEngine
    CoreEngine -->|"calls"| APIServer
    Operator -->|"applies changes"| APIServer

    %% Click events
    click CLIUser "https://github.com/avitaltamir/cyphernetes/tree/main/cmd/cyphernetes"
    click CLI "https://github.com/avitaltamir/cyphernetes/blob/main/cmd/cyphernetes/main.go"
    click CoreEngine "https://github.com/avitaltamir/cyphernetes/tree/main/pkg/core"
    click Provider "https://github.com/avitaltamir/cyphernetes/tree/main/pkg/provider/apiserver"
    click WebUI "https://github.com/avitaltamir/cyphernetes/tree/main/web/"
    click Operator "https://github.com/avitaltamir/cyphernetes/tree/main/operator/"

    %% Styles
    classDef go fill:#8fbc8f,stroke:#333,stroke-width:1px
    classDef js fill:#89CFF0,stroke:#333,stroke-width:1px
    classDef k8s fill:#ffa500,stroke:#333,stroke-width:1px
```
