# immanuwell/k16s-exam-simulator architecture

> Architecture diagram of the GitHub repository immanuwell/k16s-exam-simulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/immanuwell/k16s-exam-simulator
- Repository: https://github.com/immanuwell/k16s-exam-simulator

## Overview

K16S provisions a Kubernetes exam environment, serves timed CKA/CKS sessions in a browser, and grades candidate changes against live cluster state. The main runtime path is candidate → exam UI → API/session handling → per-question setup or validation scripts → Kubernetes state, with progress persisted in SQLite. The README also documents host, Lima-laptop, and lightweight-kind installation modes and browser terminal/desktop access. Provisioning and terminal links follow documented capabilities and tree paths; their implementation details were not sampled.

Main entry points: [`install.sh`](https://github.com/immanuwell/k16s-exam-simulator/blob/main/install.sh) (Install command), [`server/handlers.go`](https://github.com/immanuwell/k16s-exam-simulator/blob/main/server/handlers.go) (Session and grading), [`server/main.go`](https://github.com/immanuwell/k16s-exam-simulator/blob/main/server/main.go) (HTTP server), [`exams`](https://github.com/immanuwell/k16s-exam-simulator/tree/main/exams) (Exam profiles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_install["Environment setup"]
  node_installer["Install command<br/>[install.sh]"]
  node_hostprov["Host provisioner"]
  node_laptop["Laptop mode"]
  node_lite["Lightweight mode"]
  node_cluster["Kubeadm cluster"]
end

subgraph group_exam["Exam content"]
  node_exams["Exam profiles"]
  node_cka["CKA questions"]
  node_cks["CKS questions"]
  node_setup["Question setup"]
  node_grading["Question grading"]
end

subgraph group_web["Exam application"]
  node_questionmeta["Question loader<br/>[questions.go]"]
  node_frontend["Exam UI<br/>[+page.svelte]"]
  node_api["API client<br/>[api.js]"]
  node_server["HTTP server<br/>[main.go]"]
  node_handlers["Session and grading<br/>[handlers.go]"]
  node_store[("Session progress<br/>[store.go]")]
end

subgraph group_runtime["Candidate workspace"]
  node_terminal["Browser terminal<br/>[ttyd.sh]"]
  node_desktop["Browser desktop<br/>[desktop.sh]"]
  node_nginx["Web proxy<br/>[nginx.sh]"]
end

node_candidate(("Candidate"))

node_candidate -->|"starts install"| node_installer
node_installer -->|"provisions host"| node_hostprov
node_installer -.->|"starts laptop"| node_laptop
node_installer -.->|"starts lightweight"| node_lite
node_hostprov -->|"creates cluster"| node_cluster
node_laptop -->|"runs provisioner"| node_cluster
node_lite -->|"runs kind mode"| node_cluster
node_candidate -->|"uses exam UI"| node_frontend
node_frontend -->|"calls"| node_api
node_api -->|"sends requests"| node_server
node_server -->|"loads questions"| node_questionmeta
node_questionmeta -->|"reads profiles"| node_exams
node_exams -->|"includes"| node_cka
node_exams -->|"includes"| node_cks
node_server -->|"dispatches routes"| node_handlers
node_handlers -->|"reads and writes"| node_store
node_handlers -->|"runs setup script"| node_setup
node_handlers -->|"runs validator"| node_grading
node_setup -->|"changes environment"| node_cluster
node_grading -->|"checks state"| node_cluster
node_candidate -->|"opens workspace"| node_terminal
node_candidate -.->|"opens workspace"| node_desktop
node_nginx -->|"proxies requests"| node_server

click node_installer "https://github.com/immanuwell/k16s-exam-simulator/blob/main/install.sh"
click node_hostprov "https://github.com/immanuwell/k16s-exam-simulator/tree/main/provision"
click node_laptop "https://github.com/immanuwell/k16s-exam-simulator/tree/main/local"
click node_lite "https://github.com/immanuwell/k16s-exam-simulator/tree/main/lightweight"
click node_exams "https://github.com/immanuwell/k16s-exam-simulator/tree/main/exams"
click node_cka "https://github.com/immanuwell/k16s-exam-simulator/tree/main/exams/cka"
click node_cks "https://github.com/immanuwell/k16s-exam-simulator/tree/main/exams/cks"
click node_questionmeta "https://github.com/immanuwell/k16s-exam-simulator/blob/main/server/questions.go"
click node_frontend "https://github.com/immanuwell/k16s-exam-simulator/blob/main/server/frontend/src/routes/%2Bpage.svelte"
click node_api "https://github.com/immanuwell/k16s-exam-simulator/blob/main/server/frontend/src/lib/api.js"
click node_server "https://github.com/immanuwell/k16s-exam-simulator/blob/main/server/main.go"
click node_handlers "https://github.com/immanuwell/k16s-exam-simulator/blob/main/server/handlers.go"
click node_store "https://github.com/immanuwell/k16s-exam-simulator/blob/main/server/store.go"
click node_setup "https://github.com/immanuwell/k16s-exam-simulator/tree/main/exams"
click node_grading "https://github.com/immanuwell/k16s-exam-simulator/tree/main/exams"
click node_terminal "https://github.com/immanuwell/k16s-exam-simulator/blob/main/provision/ttyd.sh"
click node_desktop "https://github.com/immanuwell/k16s-exam-simulator/blob/main/provision/desktop.sh"
click node_nginx "https://github.com/immanuwell/k16s-exam-simulator/blob/main/provision/nginx.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_installer,node_hostprov,node_laptop,node_lite,node_cluster toneBlue
class node_exams,node_cka,node_cks,node_setup,node_grading toneAmber
class node_questionmeta,node_frontend,node_api,node_server,node_handlers,node_store toneMint
class node_terminal,node_desktop,node_nginx toneRose
class node_candidate toneIndigo
```

## Components

### Environment setup

- [Install command](https://github.com/immanuwell/k16s-exam-simulator/blob/main/install.sh): `install.sh`
- [Host provisioner](https://github.com/immanuwell/k16s-exam-simulator/tree/main/provision): `provision`
- [Laptop mode](https://github.com/immanuwell/k16s-exam-simulator/tree/main/local): `local`
- [Lightweight mode](https://github.com/immanuwell/k16s-exam-simulator/tree/main/lightweight): `lightweight`
- **Kubeadm cluster**

### Exam content

- [Exam profiles](https://github.com/immanuwell/k16s-exam-simulator/tree/main/exams): `exams`
- [CKA questions](https://github.com/immanuwell/k16s-exam-simulator/tree/main/exams/cka): `exams/cka`
- [CKS questions](https://github.com/immanuwell/k16s-exam-simulator/tree/main/exams/cks): `exams/cks`
- [Question setup](https://github.com/immanuwell/k16s-exam-simulator/tree/main/exams): `exams`
- [Question grading](https://github.com/immanuwell/k16s-exam-simulator/tree/main/exams): `exams`

### Exam application

- [Question loader](https://github.com/immanuwell/k16s-exam-simulator/blob/main/server/questions.go): `server/questions.go`
- [Exam UI](https://github.com/immanuwell/k16s-exam-simulator/blob/main/server/frontend/src/routes/%2Bpage.svelte): `server/frontend/src/routes/+page.svelte`
- [API client](https://github.com/immanuwell/k16s-exam-simulator/blob/main/server/frontend/src/lib/api.js): `server/frontend/src/lib/api.js`
- [HTTP server](https://github.com/immanuwell/k16s-exam-simulator/blob/main/server/main.go): `server/main.go`
- [Session and grading](https://github.com/immanuwell/k16s-exam-simulator/blob/main/server/handlers.go): `server/handlers.go`
- [Session progress](https://github.com/immanuwell/k16s-exam-simulator/blob/main/server/store.go): `server/store.go`

### Candidate workspace

- [Browser terminal](https://github.com/immanuwell/k16s-exam-simulator/blob/main/provision/ttyd.sh): `provision/ttyd.sh`
- [Browser desktop](https://github.com/immanuwell/k16s-exam-simulator/blob/main/provision/desktop.sh): `provision/desktop.sh`
- [Web proxy](https://github.com/immanuwell/k16s-exam-simulator/blob/main/provision/nginx.sh): `provision/nginx.sh`

### Other components

- **Candidate**

## Connections

- Candidate → Install command: starts install
- Install command → Host provisioner: provisions host
- Install command → Laptop mode: starts laptop
- Install command → Lightweight mode: starts lightweight
- Host provisioner → Kubeadm cluster: creates cluster
- Laptop mode → Kubeadm cluster: runs provisioner
- Lightweight mode → Kubeadm cluster: runs kind mode
- Candidate → Exam UI: uses exam UI
- Exam UI → API client: calls
- API client → HTTP server: sends requests
- HTTP server → Question loader: loads questions
- Question loader → Exam profiles: reads profiles
- Exam profiles → CKA questions: includes
- Exam profiles → CKS questions: includes
- HTTP server → Session and grading: dispatches routes
- Session and grading → Session progress: reads and writes
- Session and grading → Question setup: runs setup script
- Session and grading → Question grading: runs validator
- Question setup → Kubeadm cluster: changes environment
- Question grading → Kubeadm cluster: checks state
- Candidate → Browser terminal: opens workspace
- Candidate → Browser desktop: opens workspace
- Web proxy → HTTP server: proxies requests