# piyush-gpt/codeflux architecture

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

- Interactive diagram: https://gitdiagram.com/piyush-gpt/codeflux
- Repository: https://github.com/piyush-gpt/codeflux

## Overview

##### Project type & purpose
− CodeFlux is a full-stack, cloud-native, real-time collaborative code editor (like Replit).
− It uses a React/Tailwind frontend, Node/Express backend with WebSockets, plus a “podDeployment” microservice to spin up Docker containers in Kubernetes for live code execution.

##### File structure
- Top-level “frontend” folder – production React app (served via Nginx)
- Top-level “server” folder – Express API, WebSocket logic, auth, models (User, Repl, Collaboration), S3 integration
- Top-level “podDeployment” folder – microservice to control Kubernetes pods for code execution
- “ProductionSetup” – Kubernetes YAMLs for cert-manager, ingress, Redis, frontend/server deployments
- CI/CD workflows in .github/workflows (build/test, deploy-to-gke)

##### Key architecture insights from README
- Real-time sync via WebSockets → implies a message bus or pub/sub (Redis)
- Code executed in isolated Docker containers orchestrated by Kubernetes
- Object storage is CloudFlare R2 (S3-compatible)
- Deployed to GCP/GKE behind an Ingress controller with Let’s Encrypt

A. Clients (Browsers)
– Users load the React app, authenticate, edit code, see live updates via WebSockets, and trigger code runs.
B. Frontend Service
– Nginx container serving built React/Tailwind UI
– WebSocket client connects here and proxies to backend
C. API Backend
– Express.js app pods
– REST endpoints for auth, file management, collaboration metadata
– WebSocket server for real-time diff sync
– Integrations:
- MongoDB (or chosen document DB) for users, repls, collaboration state
- Redis for pub/sub, session caching
- CloudFlare R2 (S3-compatible) for persisting files/snapshots
D. PodDeployment Microservice
– REST endpoint to request new execution pods
– Controller calls Kubernetes API to spawn ephemeral Docker containers per run
– Streams logs/results back to API/Frontend
E. Kubernetes Cluster (GKE)
– Ingress Controller + Cert-Manager (Let’s Encrypt)
– Services & Deployments: frontend, backend, podDeployment, redis
F. CI/CD Pipeline
– GitHub Actions for build → container images → push to registry → kubectl apply → GKE

##### Relationships & data flows
1. Browser → Ingress (TLS) → Frontend → REST/WebSocket → API Backend
2. API ↔ Redis (pub/sub for WebSocket broadcasts)
3. API ↔ MongoDB (persistence of users, repl sessions, code)
4. API ↔ R2 (file snapshots, asset storage)
5. API → PodDeployment → Kubernetes API → Execution Pod → Docker container → return stdout/errors → API → WebSocket → Browser
6. GitHub Actions → Container Registry → GKE cluster updates

##### Architectural patterns & design principles
– Microservices: separate podDeployment service
– Containerization: all services run in Docker pods
– Infrastructure-as-code: Kubernetes YAML in ProductionSetup
– Pub/Sub for real-time sync (Redis)
– Clear separation of concerns: UI vs API vs execution engine

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client"
        Browser["Browser"]:::client
    end

    %% Edge Layer
    subgraph "Edge / Ingress"
        Ingress["Ingress Controller + Cert-Manager"]:::infra
    end

    %% Services Layer
    subgraph "Services"
        subgraph "Frontend Service"
            FE_Nginx["React.js + Tailwind (Nginx)"]:::service
        end
        subgraph "API Backend"
            API["Node.js/Express + socket.io"]:::service
        end
        PodDep["PodDeployment Microservice"]:::service
        Redis["Redis pub/sub"]:::service
    end

    %% Managed Datastores
    subgraph "Managed Datastores"
        Mongo["MongoDB Atlas"]:::external
        R2["CloudFlare R2 (S3)"]:::external
    end

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster (GKE)"
        KubeAPI["Kubernetes API"]:::infra
        ExecPod["Execution Pod (Docker)"]:::service
    end

    %% CI/CD
    subgraph "CI/CD Pipeline"
        GHActions["GitHub Actions"]:::cicd
        ContainerReg["Container Registry"]:::external
    end

    %% Connections
    Browser -->|"HTTPS"| Ingress
    Ingress -->|"HTTP/WebSocket"| FE_Nginx
    FE_Nginx -->|"REST API"| API
    Browser -->|"WebSocket"| API
    API -->|"pub/sub"| Redis
    API -->|"read/write"| Mongo
    API -->|"store/retrieve"| R2
    API -->|"trigger run"| PodDep
    PodDep -->|"calls"| KubeAPI
    KubeAPI -->|"spawn container"| ExecPod
    ExecPod -->|"stdout/errors"| API
    GHActions -->|"build & test"| ContainerReg
    ContainerReg -->|"deploy images"| KubeAPI

    %% Click Events
    click FE_Nginx "https://github.com/piyush-gpt/codeflux/tree/main/frontend/"
    click API "https://github.com/piyush-gpt/codeflux/tree/main/server/"
    click PodDep "https://github.com/piyush-gpt/codeflux/tree/main/podDeployment/"
    click KubeAPI "https://github.com/piyush-gpt/codeflux/tree/main/ProductionSetup/"
    click GHActions "https://github.com/piyush-gpt/codeflux/tree/main/.github/workflows/"

    %% Styles
    classDef client fill:#E0F7FA,stroke:#006064
    classDef infra fill:#E8EAF6,stroke:#3F51B5
    classDef service fill:#FFF3E0,stroke:#FB8C00
    classDef external fill:#E8F5E9,stroke:#388E3C
    classDef cicd fill:#F3E5F5,stroke:#7B1FA2
```
