khansharafraz/k8sgames

1. Overall shape

- This is a client-side browser application with no application server in the repo.

- The site is served as static files (index.html, draw.html, style.css, js/**) and deployed with vercel.json.

- The architecture is split into two top-level experiences: game/play mode and K8s Draw (/draw), both running in the browser.

2. Entry points and page-level boundaries

- index.html is the main interactive simulator entry.

- draw.html is the diagramming-focused entry with no game progression logic.

- The README’s “play now” and “draw” split is reflected in the file structure: the same codebase supports both a simulation game and a whiteboard/diagram editor.

3. Core simulation engine

- js/engine/GameEngine.js is the central coordinator for the game experience.

- ClusterState.js holds the current Kubernetes cluster model: resources, relationships, status, and likely selection/interaction state.

- SimulationTick.js and IncidentEngine.js drive time-based progression: incidents, state changes, and cluster behavior over time.

- ScoringEngine.js computes performance/quality metrics for sandbox and challenge-style evaluation.

4. Game modes as orchestration layers

- js/modes/CampaignMode.js, ChallengeMode.js, ChaosMode.js, and SandboxMode.js define different rulesets and progression styles.

- These modes likely plug into the same core engine but alter:

- level/incident sequencing,

- success/failure conditions,

- scoring pressure,

- starting resources and constraints.

- js/data/CampaignLevels.js, IncidentDefs.js, and Achievements.js provide mode-specific content and progression data.

5. Cluster resource model

- The js/resources/** folder is the domain model for Kubernetes objects.

- ResourceBase.js likely defines shared behavior, while specialized files split resources by category:

- ClusterResources.js, ConfigResources.js, NetworkResources.js, RBACResources.js,

- StorageResources.js, WorkloadResources.js.

- This separation matters architecturally because it mirrors Kubernetes domains: workload ownership, networking, storage, and access control.

6. Rendering pipeline

- js/rendering/ClusterRenderer.js is the main visual renderer for the 3D cluster.

- Supporting modules render different visual layers:

- ConnectionLines.js for ownership/network edges,

- ParticleTraffic.js for animated flow/traffic,

- ResourceMeshes.js for the per-resource 3D shapes.

- The app uses Three.js for the 3D scene; visual state is derived from cluster state rather than stored separately.

7. UI layer and interaction surfaces

- js/ui/** contains the browser UI overlays around the 3D scene:

- HUD.js for top-level status,

- InspectorPanel.js for selected resource details/YAML/describe output,

- ContextMenu.js for resource actions,

- CommandBar.js for kubectl-style commands,

- MetricsDashboard.js, Minimap.js, SettingsPanel.js, and IncidentPanel.js.

- These panels sit above the renderer and act as controllers for user actions that mutate cluster state.

8. Primary data flow

- User input enters through the UI layers: click, drag, context menu, keyboard commands.

- UI actions update ClusterState through the engine.

- The engine advances simulation, evaluates incidents/scoring, then the renderer redraws the 3D cluster and overlays.

- This is a classic state-driven render loop: state changes originate from user actions or simulation ticks, and rendering is a projection of that state.

9. Kubernetes-specific semantics

- The app is not just a generic 3D scene; it models real K8s concepts:

- ownership chains such as Deployment → ReplicaSet → Pod,

- service selection and connectivity,

- storage and RBAC objects,

- incidents like CrashLoopBackOff, ImagePullBackOff, DNS failures, PVC issues, and node problems.

- This is why the architecture separates resource definitions, incident logic, and rendering: each layer needs to understand Kubernetes semantics.

10. Diagramming mode (/draw)

- The draw experience is a specialized editor for K8s architecture diagrams.

- It reuses the resource catalog and 3D rendering primitives, but removes incident/scoring/game loops.

- The README indicates support for:

- drag-drop resource placement,

- connection lines,

- property editing,

- auto-layout,

- YAML/PNG export,

- shareable URLs.

- Architecturally, this is a second product mode built on the same visualization foundation.

11. Content and progression data

- js/data/** contains static game content:

- achievements,

- campaign levels,

- incident definitions.

- These files are the content boundary between the engine and authored gameplay. The engine interprets the data; the data files define what scenarios exist.

12. Deployment and runtime constraints

- The repo is intentionally dependency-light and build-free: vanilla ES modules, Three.js, and CDN-hosted Tailwind per README.

- That makes the deployment model simple: static hosting only, with no backend APIs visible in this repo.

- robots.txt, og-image.html, and vercel.json support public site hosting, social previews, and routing/hosting configuration.

13. What to show in an architecture diagram

- A good diagram would place the browser runtime at the center, with:

- input/UI controls feeding the engine,

- engine updating cluster state,

- renderer consuming state to draw the 3D scene,

- mode modules selecting rules and progression,

- data files supplying levels/incidents/achievements,

- draw mode branching off as a simpler editor path.

- The main boundary is between state/logic and presentation, with Kubernetes resource definitions acting as the domain model that connects them.