# ishaannene/blunder-buss architecture

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

- Interactive diagram: https://gitdiagram.com/ishaannene/blunder-buss
- Repository: https://github.com/ishaannene/blunder-buss

## Overview

##### Project type and purpose
- From the file tree we see a “web” folder containing HTML, CSS, and JS, a Go‐based “api” (go/api), a Go “worker” (go/worker), a containerized Stockfish engine (docker/stockfish), a Redis deployment in k8s, plus Terraform and k8s manifests.
- This is a full-stack, microservices-style chess move analysis platform:
- A static web UI served via Nginx (docker/web)
- A Go-based HTTP API (docker/api → go/api)
- A Redis-backed job queue
- A worker service that pulls jobs from Redis, invokes Stockfish (docker/stockfish), and writes results back
- Optional Go CLI client (go/client) for integration or testing
- All services are containerized, orchestrated via Kubernetes, and provisioned via Terraform.

##### File structure
- Top level:
- web/ → static frontend assets
- go/api, go/worker, go/client → three Go binaries (API server, asynchronous worker, CLI client)
- docker/… → Dockerfiles for each component plus an Nginx config
- k8s/… → Deployments, Services, HPA, KEDA ScaledObject for queue autoscaling, Redis PVC
- terraform/… → Infrastructure as code (e.g., EKS, VPC, IAM, kubeconfig template)
- scripts/… → build & push container images, local‐deploy scripts, API tests
- Patterns:
- Microservice decomposition (API vs. worker vs. engine)
- Queue‐based asynchronous processing
- Container per component
- Infrastructure‐as‐code with Terraform + K8s

##### Key insights from (empty) README
- Although the README is blank, the folder names and manifests convey the high-level architecture and dependencies (Go, Redis, Stockfish, Nginx, Kubernetes, Terraform, KEDA).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers and Components
    subgraph "Frontend Layer"
        Browser["Browser"]:::external
        WebUI["Nginx + Static Web UI"]:::frontend
    end

    subgraph "Sync Backend"
        API["Go API Service"]:::api
    end

    subgraph "Async Backend"
        Redis["Redis Queue"]:::infra
        Worker["Go Worker Service"]:::worker
        Stockfish["Stockfish Engine"]:::engine
    end

    subgraph "Clients"
        CLI["Go CLI Client"]:::client
    end

    subgraph "Infrastructure"
        K8s["Kubernetes Cluster"]:::infra
        Terraform["Terraform IaC"]:::infra
    end

    %% Interactions
    Browser -->|"HTTP Request"| WebUI
    WebUI -->|"HTTP Request"| API
    API -->|"Enqueue Job (Redis)"| Redis
    Worker -->|"Dequeue Job (Redis)"| Redis
    Worker -->|"Invoke UCI"| Stockfish
    Stockfish -->|"Return Analysis"| Worker
    Worker -->|"Send Result (HTTP)"| API
    CLI -->|"HTTP Request / Enqueue"| API
    CLI -->|"Enqueue Job"| Redis

    API -->|"Deploy"| K8s
    Worker -->|"Deploy"| K8s
    Redis -->|"Deploy"| K8s
    Stockfish -->|"Deploy"| K8s
    WebUI -->|"Deploy"| K8s
    Terraform -->|"Provision"| K8s

    %% Artifacts
    subgraph "Project Artifacts"
        WebDir["web/"]:::artifact
        WebDocker["docker/web/Dockerfile"]:::artifact
        NginxConf["docker/web/nginx.conf"]:::artifact
        WebDeploy["k8s/web-deployment.yaml"]:::artifact
        WebService["k8s/web-service.yaml"]:::artifact

        APIMain["go/api/main.go"]:::artifact
        APIDocker["docker/api/Dockerfile"]:::artifact
        APIKeda["k8s/keda-scaledobject-queue.yaml"]:::artifact

        RedisDeploy["k8s/redis-deployment.yaml"]:::artifact
        RedisPVC["k8s/redis-pvc.yaml"]:::artifact

        WorkerMain["go/worker/main.go"]:::artifact
        WorkerDocker["docker/worker/Dockerfile"]:::artifact
        WorkerKeda["k8s/keda-scaledobject-queue.yaml"]:::artifact

        StockfishDocker["docker/stockfish/Dockerfile"]:::artifact
        StockfishK8s["k8s/stockfish-deployment.yaml"]:::artifact
        StockfishServ["k8s/stockfish-service.yaml"]:::artifact
        HPAStock["k8s/hpa-stockfish.yaml"]:::artifact

        CLIClient["go/client/main.go"]:::artifact

        Kustom["k8s/kustomization.yaml"]:::artifact
        Namespace["k8s/namespace.yaml"]:::artifact

        TFMain["terraform/main.tf"]:::artifact
        TFVar["terraform/variables.tf"]:::artifact
        TFOut["terraform/outputs.tf"]:::artifact
        TFKube["terraform/kubeconfig.tpl"]:::artifact
        TFEx["terraform/terraform.tfvars.example"]:::artifact

        Scripts1["scripts/build-and-push-ecr.sh"]:::artifact
        Scripts2["scripts/deploy-local.sh"]:::artifact
        Scripts3["scripts/test-api.sh"]:::artifact
        DockerCompose["docker-compose.local.yml"]:::artifact
    end

    %% Click Events
    click WebDir "https://github.com/ishaannene/blunder-buss/tree/main/web/"
    click WebDocker "https://github.com/ishaannene/blunder-buss/tree/main/docker/web/Dockerfile"
    click NginxConf "https://github.com/ishaannene/blunder-buss/blob/main/docker/web/nginx.conf"
    click WebDeploy "https://github.com/ishaannene/blunder-buss/blob/main/k8s/web-deployment.yaml"
    click WebService "https://github.com/ishaannene/blunder-buss/blob/main/k8s/web-service.yaml"

    click APIMain "https://github.com/ishaannene/blunder-buss/blob/main/go/api/main.go"
    click APIDocker "https://github.com/ishaannene/blunder-buss/tree/main/docker/api/Dockerfile"
    click APIKeda "https://github.com/ishaannene/blunder-buss/blob/main/k8s/keda-scaledobject-queue.yaml"

    click RedisDeploy "https://github.com/ishaannene/blunder-buss/blob/main/k8s/redis-deployment.yaml"
    click RedisPVC "https://github.com/ishaannene/blunder-buss/blob/main/k8s/redis-pvc.yaml"

    click WorkerMain "https://github.com/ishaannene/blunder-buss/blob/main/go/worker/main.go"
    click WorkerDocker "https://github.com/ishaannene/blunder-buss/tree/main/docker/worker/Dockerfile"
    click WorkerKeda "https://github.com/ishaannene/blunder-buss/blob/main/k8s/keda-scaledobject-queue.yaml"

    click StockfishDocker "https://github.com/ishaannene/blunder-buss/tree/main/docker/stockfish/Dockerfile"
    click StockfishK8s "https://github.com/ishaannene/blunder-buss/blob/main/k8s/stockfish-deployment.yaml"
    click StockfishServ "https://github.com/ishaannene/blunder-buss/blob/main/k8s/stockfish-service.yaml"
    click HPAStock "https://github.com/ishaannene/blunder-buss/blob/main/k8s/hpa-stockfish.yaml"

    click CLIClient "https://github.com/ishaannene/blunder-buss/blob/main/go/client/main.go"

    click Kustom "https://github.com/ishaannene/blunder-buss/blob/main/k8s/kustomization.yaml"
    click Namespace "https://github.com/ishaannene/blunder-buss/blob/main/k8s/namespace.yaml"

    click TFMain "https://github.com/ishaannene/blunder-buss/blob/main/terraform/main.tf"
    click TFVar "https://github.com/ishaannene/blunder-buss/blob/main/terraform/variables.tf"
    click TFOut "https://github.com/ishaannene/blunder-buss/blob/main/terraform/outputs.tf"
    click TFKube "https://github.com/ishaannene/blunder-buss/blob/main/terraform/kubeconfig.tpl"
    click TFEx "https://github.com/ishaannene/blunder-buss/blob/main/terraform/terraform.tfvars.example"

    click Scripts1 "https://github.com/ishaannene/blunder-buss/blob/main/scripts/build-and-push-ecr.sh"
    click Scripts2 "https://github.com/ishaannene/blunder-buss/blob/main/scripts/deploy-local.sh"
    click Scripts3 "https://github.com/ishaannene/blunder-buss/blob/main/scripts/test-api.sh"
    click DockerCompose "https://github.com/ishaannene/blunder-buss/blob/main/docker-compose.local.yml"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef api fill:#90EE90,stroke:#333,stroke-width:1px
    classDef worker fill:#FFFACD,stroke:#333,stroke-width:1px
    classDef engine fill:#FFB6C1,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#E0FFFF,stroke:#333,stroke-width:1px
    classDef client fill:#F08080,stroke:#333,stroke-width:1px
    classDef artifact fill:#F5DEB3,stroke:#333,stroke-width:1px
```
