# kubestellar/ui architecture

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

- Interactive diagram: https://gitdiagram.com/kubestellar/ui
- Repository: https://github.com/kubestellar/ui

## Overview

##### Project type and purpose
- KubestellarUI is a full-stack web application.
- Frontend: React + TypeScript single-page application (SPA).
- Backend: Go service built on Gin, exposing REST endpoints and WebSocket streams.
- Purpose: Provide a UI for managing multi-cluster Kubernetes workloads (namespaces, binding policies, deployments, etc.) and stream real-time status updates via WebSockets.

##### File structure
- Top-level directories:
- /backend – Go monolith (API handlers, installer, k8s client, JWT auth, middleware, services, models)
- /src – React code (components, pages, hooks, API client, context providers, stores)
- /public – static examples & assets
- Infrastructure files: Dockerfile, docker-compose.yml, nginx.conf, GitHub Actions workflows, Makefile
- Notice patterns:
- Frontend communicates via HTTP REST + WebSocket.
- Backend encapsulates k8s interactions, JWT auth, Redis for caching, PostgreSQL for persistent data.
- CI/CD and container orchestration (Docker Compose, GitHub CI).

##### Key insights from README
- Frontend runs on port 5173, backend on port 4000.
- Redis optional for caching WebSocket updates.
- Kubernetes clusters must be pre-configured; backend uses kubernetes/client-go.
- Docker Compose brings up backend, frontend, redis.

a. Components to include:
- React Frontend (SPA)
- Go Backend (Gin HTTP server + WebSocket handler)
- PostgreSQL (persistent store)
- Redis (cache / pub-sub for WebSocket throttling)
- Kubernetes Clusters (one or more; managed via K8s client & custom controllers)
- External services: Artifact Hub registry, GitHub (for repository browsing), Helm Chart repositories
- CI/CD pipelines (GitHub Actions, Docker registry)
- Load Balancer / Reverse Proxy (NGINX in front of frontend/backend if present)

b. Relationships & data flows:
1. User → Browser → React SPA
2. SPA → (HTTP/REST) → Gin backend routes (e.g., /api/cluster, /api/bindings, /ws/installer)
3. Backend → PostgreSQL (user, namespace, cluster metadata)
4. Backend → Redis (cache real-time k8s watch events)
5. Backend → Kubernetes API (deploy, list resources, watch CSRs)
6. Backend → External artifact hub / GitHub / Helm repos (to fetch charts, images)
7. Backend WebSocket → SPA (push real-time status updates via socket)
8. Docker Compose / CI → Build and deploy container images to registry

c. Architectural patterns & principles:
- Layered architecture in backend: API handler → service layer → k8s client / installer / models
- React: component hierarchy, context for theming & WebSocket, React-Query for data fetching & caching
- Use of pub-sub (Redis) to decouple k8s watch events from WebSocket streams
- Single responsibility: distinct modules for auth, installer, k8s, namespace, JWT, logging

d. Technologies & frameworks to annotate:
- Frontend: React, Vite, TypeScript, TailwindCSS, React-Query, WebSocket
- Backend: Go, Gin framework, client-go, Redis client, PostgreSQL driver, JWT
- DevOps: Docker, Docker Compose, GitHub Actions, Makefile, Air (hot reload)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & Browser
    subgraph "User Interaction"
        User["User"]:::external
        Browser["Browser"]:::external
    end
    User --> Browser

    %% UI Layer
    subgraph "Frontend Layer"
        React["React SPA"]:::frontend
        Vite["Vite & Tailwind Config"]:::frontend
        Assets["Static Assets & Examples"]:::frontend
    end
    Browser --> React
    click React "https://github.com/kubestellar/ui/tree/dev/src/"
    click Vite "https://github.com/kubestellar/ui/blob/dev/vite.config.ts"
    click Vite "https://github.com/kubestellar/ui/blob/dev/tailwind.config.js"
    click Vite "https://github.com/kubestellar/ui/blob/dev/postcss.config.js"
    click Assets "https://github.com/kubestellar/ui/tree/dev/public/"

    %% Reverse Proxy
    Nginx["NGINX Reverse Proxy"]:::infra
    Browser --> Nginx
    Nginx --> React
    Nginx --> Backend

    %% Backend Layer
    subgraph "Backend Layer"
        Backend["Go Backend (Gin HTTP Server)"]:::backend

        subgraph "API & Routing"
            API["API Handlers & Routes"]:::backend
            WS["Installer WebSocket Handler"]:::backend
            Auth["JWT Auth & Middleware"]:::backend
        end

        subgraph "Services & Modules"
            InstallerSvc["Installer Service"]:::backend
            K8sClient["Kubernetes Client Module"]:::backend
            Namespace["Namespace Management"]:::backend
            Binding["Binding Policy Service (WDS)"]:::backend
            ITS["Installer Tracking Service (ITS)"]:::backend
            WECS["Exec & WebSocket Command Service (WECS)"]:::backend
            Models["Models Layer"]:::backend
            Logging["Logging & Utils"]:::backend
        end
    end

    React -->|HTTP REST & WebSocket| Backend
    Backend --> API
    Backend --> WS
    Backend --> Auth
    Backend --> InstallerSvc
    Backend --> K8sClient
    Backend --> Namespace
    Backend --> Binding
    Backend --> ITS
    Backend --> WECS
    Backend --> Models
    Backend --> Logging

    click Backend "https://github.com/kubestellar/ui/blob/dev/backend/main.go"
    click API "https://github.com/kubestellar/ui/blob/dev/backend/routes/cluster.go"
    click API "https://github.com/kubestellar/ui/blob/dev/backend/routes/deployment.go"
    click API "https://github.com/kubestellar/ui/blob/dev/backend/routes/bp.go"
    click API "https://github.com/kubestellar/ui/blob/dev/backend/routes/artifacthub.go"
    click API "https://github.com/kubestellar/ui/blob/dev/backend/routes/gitops.go"
    click API "https://github.com/kubestellar/ui/blob/dev/backend/routes/setup.go"
    click API "https://github.com/kubestellar/ui/blob/dev/backend/routes/wecs.go"
    click API "https://github.com/kubestellar/ui/blob/dev/backend/routes/installer.go"
    click API "https://github.com/kubestellar/ui/blob/dev/backend/routes/resources.go"
    click WS "https://github.com/kubestellar/ui/blob/dev/backend/installer-websocket.go"
    click Auth "https://github.com/kubestellar/ui/blob/dev/backend/middleware/auth.go"
    click Auth "https://github.com/kubestellar/ui/blob/dev/backend/jwt/config.go"
    click K8sClient "https://github.com/kubestellar/ui/tree/dev/backend/k8s/"
    click InstallerSvc "https://github.com/kubestellar/ui/tree/dev/backend/installer/"
    click Namespace "https://github.com/kubestellar/ui/tree/dev/backend/namespace/"
    click Binding "https://github.com/kubestellar/ui/tree/dev/backend/wds/"
    click ITS "https://github.com/kubestellar/ui/tree/dev/backend/its/manual/"
    click WECS "https://github.com/kubestellar/ui/tree/dev/backend/wecs/"
    click Models "https://github.com/kubestellar/ui/tree/dev/backend/models/"
    click Logging "https://github.com/kubestellar/ui/blob/dev/backend/log/log.go"
    click Logging "https://github.com/kubestellar/ui/blob/dev/backend/utils/parser.go"

    %% Infrastructure
    subgraph "Infrastructure"
        Postgres["PostgreSQL"]:::infra
        Redis["Redis Cache / Pub-Sub"]:::infra
    end
    Backend -->|"DB Queries"| Postgres
    Backend -->|"Cache / Pub-Sub"| Redis

    click Postgres "https://github.com/kubestellar/ui/blob/dev/backend/postgresql/config.go"
    click Redis "https://github.com/kubestellar/ui/blob/dev/backend/redis/redis.go"

    %% External Systems
    subgraph "External Systems"
        K8sCluster["Kubernetes Clusters"]:::external
        ArtifactHub["Artifact Hub Registry"]:::external
        GitHub["GitHub Repos"]:::external
        HelmRepo["Helm Chart Repos"]:::external
    end
    K8sClient -->|"WATCH / APPLY"| K8sCluster
    Backend -->|"Fetch Charts & Images"| ArtifactHub
    Backend -->|"Fetch Repos"| GitHub
    Backend -->|"Fetch Helm Charts"| HelmRepo

    %% CI/CD & Deployment
    subgraph "DevOps"
        GHAction["GitHub Actions Workflows"]:::devops
        DockerReg["Docker Registry (quay.io)"]:::devops
        DockerCompose["Docker Compose"]:::devops
        Make["Makefiles & Husky Hooks"]:::devops
    end
    GHAction --> DockerReg
    DockerReg --> DockerCompose
    DockerCompose --> React
    DockerCompose --> Backend
    DockerCompose --> Redis
    DockerCompose --> Postgres
    Make --> GHAction

    click GHAction "https://github.com/kubestellar/ui/blob/dev/.github/workflows/ci.yml"
    click GHAction "https://github.com/kubestellar/ui/blob/dev/.github/workflows/docker-push.yml"
    click GHAction "https://github.com/kubestellar/ui/blob/dev/.github/workflows/auto_label_pr.yml"
    click DockerCompose "https://github.com/kubestellar/ui/blob/dev/docker-compose.yml"
    click Make "https://github.com/kubestellar/ui/tree/dev/Makefile"
    click Make "https://github.com/kubestellar/ui/tree/dev/backend/Makefile"
    click Make "https://github.com/kubestellar/ui/tree/dev/.husky/pre-commit"
    click DockerReg "https://github.com/kubestellar/ui/tree/dev/Dockerfile"
    click Backend "https://github.com/kubestellar/ui/tree/dev/backend/Dockerfile"
    click Nginx "https://github.com/kubestellar/ui/blob/dev/nginx.conf"

    %% Class Definitions
    classDef frontend fill:#D0E8FF,stroke:#0288D1,stroke-width:1px;
    classDef backend fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px;
    classDef infra fill:#FFF3E0,stroke:#EF6C00,stroke-width:1px;
    classDef external fill:#FFEBEE,stroke:#C62828,stroke-width:1px;
    classDef devops fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1px;
```
