# ohaval/qr-code-generator-go-k8s architecture

> Architecture diagram of the GitHub repository ohaval/qr-code-generator-go-k8s, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ohaval/qr-code-generator-go-k8s
- Repository: https://github.com/ohaval/qr-code-generator-go-k8s

## Overview

##### Project type and purpose
- This is a cloud-native, full-stack backend service written in Go. Its sole responsibility is to expose a REST API to generate QR codes on demand.
- It’s containerized with Docker, supports local development on a kind Kubernetes cluster, and is production-ready for AWS EKS with auto-scaling and load balancing.
- The service is tested end-to-end (including load testing) and deployed via CI/CD workflows in GitHub Actions.

##### File structure
- Top level:
- main.go & main_test.go: the core Go application and unit tests
- e2e_test.go: integration/e2e tests
- Dockerfile & Makefile: build, run, test, docker commands, and deployment scripts
- go.mod / go.sum: Go modules
- scripts/: automation scripts for local and EKS setup/teardown
- k8s/: manifests split into kind/ (local) and eks/ (production)
- load-tests/: k6 performance tests
- .github/workflows: CI pipelines (lint, tests)
- Patterns & architectural clues:
- Single service binary (no separate frontend)
- Kubernetes manifests reflect micro-deployment: Deployment, Service, Ingress, HPA
- Docker multi-stage build, non-root user, health checks

##### README for additional insights
- Confirms:
- REST endpoints: health check, QR generate, root info
- Docker usage: dev vs prod images
- Local Kubernetes via Makefile + kind
- Production on AWS EKS: ECR registry, ALB ingress, HPA
- Testing strategy: unit, e2e, load tests via k6
- CI/CD automation via GitHub Actions

##### Detail
- Both local kind cluster (port-forward) and EKS cluster (ALB).
- Test tools (e2e_test.go, load-tests) as separate actors.
- Do not over-simplify—each script (setup-eks.sh, run-load-test.sh) can be noted as part of CI/CD or developer automation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients & Testers
    subgraph "Clients & Testers"
        direction TB
        Client["Client (HTTP)"]:::client
        E2E["e2e_test.go"]:::tester
        LoadTestScript["run-load-test.sh"]:::tester
        LoadTest["load-test.js"]:::tester
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        GH_Lint["linting.yaml"]:::pipeline
        GH_Tests["tests.yaml"]:::pipeline
        BuildImage["Docker Build"]:::pipeline
        PushRegistry["Push to Registry"]:::pipeline
        ApplyK8s["kubectl apply"]:::pipeline
    end

    %% Registry
    DockerRegistry["Docker Registry"]:::infra

    %% Infrastructure
    subgraph "Kubernetes Clusters"
        direction TB
        subgraph "Local (kind)"
            direction TB
            KindDeployment["deployment.yaml"]:::infra
            KindService["service.yaml"]:::infra
        end
        subgraph "Production (EKS)"
            direction TB
            EKSDeployment["deployment.yaml"]:::infra
            EKSService["service.yaml"]:::infra
            EKSIngress["ingress.yaml"]:::infra
            EKSHPA["hpa.yaml"]:::infra
        end
    end

    %% Developer Machine & Scripts
    subgraph "Developer Machine & Scripts"
        direction TB
        SetupLocal["setup-k8s-local.sh"]:::script
        SetupEKS["setup-eks.sh"]:::script
        TeardownEKS["teardown-eks.sh"]:::script
        DeployApp["deploy-app.sh"]:::script
    end

    %% Application Code
    subgraph "Application Code"
        direction TB
        Main["main.go"]:::code
        UnitTests["main_test.go"]:::code
        Modules["go.mod / go.sum"]:::code
        DockerfileNode["Dockerfile"]:::code
        DockerIgnore[".dockerignore"]:::code
        MakefileNode["Makefile"]:::code
    end

    %% Documentation
    subgraph "Documentation"
        direction TB
        DocPlan["PROJECT_PLAN.md"]:::doc
        DocStruct["STRUCTURE.md"]:::doc
    end

    %% Connections
    Client -->|"HTTP POST/GET"| EKSIngress
    LoadTest -->|"K6 Test"| EKSIngress
    E2E -->|"Integration Test"| EKSIngress

    GH_Lint --> GH_Tests
    GH_Tests --> BuildImage
    BuildImage --> PushRegistry
    PushRegistry --> DockerRegistry
    PushRegistry --> ApplyK8s
    ApplyK8s --> KindDeployment
    ApplyK8s --> KindService
    ApplyK8s --> EKSDeployment
    ApplyK8s --> EKSService
    ApplyK8s --> EKSIngress
    ApplyK8s --> EKSHPA

    SetupLocal --> KindDeployment
    SetupLocal --> KindService
    SetupEKS --> EKSDeployment
    SetupEKS --> EKSService
    SetupEKS --> EKSIngress
    SetupEKS --> EKSHPA
    TeardownEKS --> EKSDeployment
    TeardownEKS --> EKSService
    TeardownEKS --> EKSIngress
    TeardownEKS --> EKSHPA
    DeployApp --> ApplyK8s

    %% Code build flow
    Main --> BuildImage
    Modules --> BuildImage
    DockerfileNode --> BuildImage
    DockerIgnore --> BuildImage
    MakefileNode --> SetupLocal
    MakefileNode --> SetupEKS
    MakefileNode --> DeployApp

    %% Click Events
    click Main "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/main.go"
    click UnitTests "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/main_test.go"
    click E2E "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/e2e_test.go"
    click DockerfileNode "https://github.com/ohaval/qr-code-generator-go-k8s/tree/main/Dockerfile"
    click MakefileNode "https://github.com/ohaval/qr-code-generator-go-k8s/tree/main/Makefile"
    click Modules "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/go.mod"
    click GH_Lint "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/.github/workflows/linting.yaml"
    click GH_Tests "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/.github/workflows/tests.yaml"
    click KindDeployment "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/k8s/kind/deployment.yaml"
    click KindService "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/k8s/kind/service.yaml"
    click EKSDeployment "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/k8s/eks/deployment.yaml"
    click EKSService "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/k8s/eks/service.yaml"
    click EKSIngress "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/k8s/eks/ingress.yaml"
    click EKSHPA "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/k8s/eks/hpa.yaml"
    click SetupLocal "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/scripts/setup-k8s-local.sh"
    click SetupEKS "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/scripts/setup-eks.sh"
    click TeardownEKS "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/scripts/teardown-eks.sh"
    click DeployApp "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/scripts/deploy-app.sh"
    click LoadTest "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/load-tests/load-test.js"
    click LoadTestScript "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/load-tests/run-load-test.sh"
    click DocPlan "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/docs/PROJECT_PLAN.md"
    click DocStruct "https://github.com/ohaval/qr-code-generator-go-k8s/blob/main/docs/STRUCTURE.md"

    %% Styles
    classDef client fill:#f9c74f,stroke:#f9844a,color:#000
    classDef tester fill:#f9c74f,stroke:#f9844a,color:#000
    classDef pipeline fill:#90be6d,stroke:#43aa8b,color:#000
    classDef infra fill:#43aa8b,stroke:#669933,color:#fff
    classDef script fill:#aaaaaa,stroke:#666666,color:#000
    classDef code fill:#4d908e,stroke:#277f73,color:#fff
    classDef doc fill:#f94144,stroke:#b31217,color:#fff
```
