# sashi-u/multi-juicer architecture

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

- Interactive diagram: https://gitdiagram.com/sashi-u/multi-juicer
- Repository: https://github.com/sashi-u/multi-juicer

## Overview

##### Project Type and Purpose
- MultiJuicer is a Kubernetes-based orchestration platform (“full-stack,” microservices style)
- Purpose: Dynamically spin up per-team OWASP Juice Shop instances on a central cluster, route traffic, persist progress, and garbage-collect idle instances.

##### File Structure
Top-level microservice folders:
– cleaner (Node.js cronjob)
– juice-balancer (Node.js load-balancer + UI)
– progress-watchdog (Go service)
Packaging & deployment:
– helm/multi-juicer: Helm chart with Kubernetes manifests (Deployments, Services, ConfigMaps, CronJobs)
– guides/: Cloud-provider setup tutorials
– e2e/: Cypress end-to-end tests

##### README for Architecture Insights
- Describes requirements for a custom load-balancer, backup/restore, and cleanup

A. Main Components
1. External Clients (Participants)
2. Kubernetes Cluster
a. Ingress/LoadBalancer (NGINX or cloud LB)
b. juice-balancer Service
– Node.js application (proxy logic + Kubernetes API client + Redis client)
– React UI served at /admin and join pages
c. Redis (in-cluster) – session/cookie store, mapping of users → team deployments
d. progress-watchdog Deployment (Go) – watches Juice Shop pods, backs up/restores progress
e. cleaner CronJob (Node) – scheduled cleanup of old/idle Juice Shop deployments
f. Per-team Juice Shop Deployments (one Deployment + Service per team)
g. ConfigMaps & Secrets (helm values.yaml drives configs)

B. Relationships & Data Flow
1. Client → DNS → Ingress → juice-balancer
2. juice-balancer reads incoming request cookie → looks up mapping in Redis
3. If no mapping, juice-balancer uses Kubernetes API → create new Juice Shop Deployment & Service
4. juice-balancer proxies HTTP traffic into the correct Juice Shop Service
5. progress-watchdog polls Kubernetes API and/or container file system → periodically snapshot challenge progress (e.g., to persistent volume or object store)
6. On Juice Shop restart, progress-watchdog restores state from backups
7. cleaner CronJob runs on schedule → queries Kubernetes API for stale deployments → deletes them

C. Architectural Patterns & Principles
- Microservices within a single Kubernetes cluster
- “Control plane” (juice-balancer + progress-watchdog + cleaner) separate from “data plane” (Juice Shop instances)
- Event-driven resource management via Kubernetes API calls
- Helm for packaging and templating infrastructure as code

D. Key Technologies
- Kubernetes (Deployments, Services, Ingress, CronJob)
- Helm (templating, values.yaml)
- Node.js (juice-balancer & cleaner)
- React (juice-balancer UI)
- Go (progress-watchdog)
- Redis (stateful session store)
- Cypress (e2e testing)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client("Browser User"):::external
    Client -->|"HTTP"| Ingress["Ingress / LoadBalancer"]:::network

    subgraph "Kubernetes Cluster"
        direction TB
        Ingress -->|"route"| JB["juice-balancer"]:::control
        JB -->|"Redis lookup"| Redis[(Redis)]:::database
        JB -->|"K8s API create/list"| API["Kubernetes API"]:::k8s
        JB -->|"proxy HTTP"| TSVC["juice-shop Service (team)"]:::data
        TSVC -->|"serves traffic"| JPD["Juice Shop Pod"]:::data
        progress["progress-watchdog"]:::control
        progress -->|"poll & backup"| API
        API -->|"manage backup"| Backup[(Backup Store)]:::database
        cleaner["Cleaner CronJob"]:::control
        cleaner -->|"delete stale"| API
    end

    subgraph "Deployment Automation"
        Helm["Helm Chart"]:::automation
    end

    subgraph "Testing & Documentation"
        e2e["E2E Tests (Cypress)"]:::testing
        Guides["Setup Guides"]:::docs
    end

    Helm -->|"templating & deploy"| API
    e2e -->|"validate flow"| JB
    Guides -->|"docs for"| Helm

    %% Click Events
    click cleaner "https://github.com/sashi-u/multi-juicer/tree/master/cleaner/"
    click JB "https://github.com/sashi-u/multi-juicer/tree/master/juice-balancer/"
    click progress "https://github.com/sashi-u/multi-juicer/tree/master/progress-watchdog/"
    click Helm "https://github.com/sashi-u/multi-juicer/tree/master/helm/multi-juicer/"
    click e2e "https://github.com/sashi-u/multi-juicer/tree/master/e2e/"
    click Guides "https://github.com/sashi-u/multi-juicer/tree/master/guides/"

    %% Styles
    classDef external fill:#ececff,stroke:#666,stroke-width:1px
    classDef network fill:#d0e7ff,stroke:#1f6feb,stroke-width:1px
    classDef control fill:#d4f5d4,stroke:#28a745,stroke-width:1px
    classDef data fill:#ffd8a8,stroke:#f97316,stroke-width:1px
    classDef database fill:#e2e8f0,stroke:#64748b,stroke-width:1px,shape:cylinder
    classDef k8s fill:#f0f9ff,stroke:#0c4a6e,stroke-width:1px
    classDef automation fill:#fff7ed,stroke:#d97706,stroke-width:1px
    classDef testing fill:#f0fdfa,stroke:#059669,stroke-width:1px
    classDef docs fill:#f8fafc,stroke:#334155,stroke-width:1px
```
