# gaurav-patil-13/wargames architecture

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

- Interactive diagram: https://gitdiagram.com/gaurav-patil-13/wargames
- Repository: https://github.com/gaurav-patil-13/wargames

## Overview

WARGAMES is a browser-based CTF learning platform. Users authenticate, browse their progress-unlocked Linux, Bash, Docker, and Networking levels, start an isolated challenge container, use its live shell, and submit a flag to earn XP and unlock the next level. The React pages drive Express APIs and a separate Socket.IO terminal channel; backend services manage challenge containers and progress backed by PostgreSQL. The README documents the major flows and integrations; some route and socket internals were not sampled, so their wiring is shown only where documented.

Main entry points: [`backend/src/server.js`](https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/server.js) (HTTP and socket server), [`backend/src/services/dockerService.js`](https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/services/dockerService.js) (Container and shell service), [`frontend/src/App.jsx`](https://github.com/gaurav-patil-13/wargames/blob/main/frontend/src/App.jsx) (Routes and session gate), [`backend/src/routes/levels.js`](https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/routes/levels.js) (Level and flag routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser app"]
  node_app["Routes and session gate<br/>[App.jsx]"]
  node_authui["Session provider<br/>[auth.jsx]"]
  node_login["Login and registration<br/>[Login.jsx]"]
  node_dashboard["Level dashboard<br/>[Dashboard.jsx]"]
  node_challenge["Challenge controls<br/>[Challenge.jsx]"]
  node_terminalui["Browser terminal<br/>[TerminalPane.jsx]"]
  node_api_client["HTTP API client<br/>[api.js]"]
end

subgraph group_api["Backend API"]
  node_server["HTTP and socket server<br/>[server.js]"]
  node_authroutes["Authentication routes<br/>[auth.js]"]
  node_authmw["JWT authentication<br/>[auth.js]"]
  node_levelroutes["Level and flag routes<br/>[levels.js]"]
  node_containerroutes["Container routes<br/>[containers.js]"]
  node_socket["Terminal socket handler<br/>[terminal.js]"]
end

subgraph group_runtime["Challenge runtime"]
  node_levels["Level catalog<br/>[levels.js]"]
  node_challenges["Challenge environments"]
  node_docker_service["Container and shell service<br/>[dockerService.js]"]
end

subgraph group_state["Platform state"]
  node_progress["Unlock and XP service<br/>[progressService.js]"]
  node_db["Database access<br/>[db.js]"]
end

node_learner(("Learner"))
node_postgres[("PostgreSQL")]
node_docker["Docker Engine"]

node_learner -->|"uses"| node_app
node_app -->|"checks session"| node_authui
node_app -->|"routes"| node_dashboard
node_app -->|"routes"| node_challenge
node_learner -->|"signs in"| node_login
node_login -->|"requests session"| node_authui
node_dashboard -->|"fetches levels"| node_api_client
node_challenge -->|"calls endpoints"| node_api_client
node_challenge -->|"opens shell"| node_terminalui
node_terminalui -->|"terminal events"| node_socket
node_api_client -->|"HTTP requests"| node_server
node_server -->|"dispatches"| node_authroutes
node_server -->|"dispatches"| node_levelroutes
node_server -->|"dispatches"| node_containerroutes
node_server -->|"registers handler"| node_socket
node_authroutes -->|"protects profile"| node_authmw
node_levelroutes -->|"protects routes"| node_authmw
node_containerroutes -->|"protects routes"| node_authmw
node_socket -->|"verifies token"| node_authmw
node_levelroutes -->|"reads catalog"| node_levels
node_levelroutes -->|"checks and records"| node_progress
node_containerroutes -->|"loads level"| node_levels
node_containerroutes -->|"starts or destroys"| node_docker_service
node_socket -->|"opens shell"| node_docker_service
node_docker_service -->|"builds image from"| node_challenges
node_docker_service -->|"builds and controls"| node_docker
node_progress -->|"reads and writes"| node_db
node_authroutes -->|"reads and writes users"| node_db
node_docker_service -->|"records containers"| node_db
node_db -->|"queries"| node_postgres

click node_app "https://github.com/gaurav-patil-13/wargames/blob/main/frontend/src/App.jsx"
click node_authui "https://github.com/gaurav-patil-13/wargames/blob/main/frontend/src/utils/auth.jsx"
click node_login "https://github.com/gaurav-patil-13/wargames/blob/main/frontend/src/pages/Login.jsx"
click node_dashboard "https://github.com/gaurav-patil-13/wargames/blob/main/frontend/src/pages/Dashboard.jsx"
click node_challenge "https://github.com/gaurav-patil-13/wargames/blob/main/frontend/src/pages/Challenge.jsx"
click node_terminalui "https://github.com/gaurav-patil-13/wargames/blob/main/frontend/src/components/TerminalPane.jsx"
click node_api_client "https://github.com/gaurav-patil-13/wargames/blob/main/frontend/src/utils/api.js"
click node_server "https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/server.js"
click node_authroutes "https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/routes/auth.js"
click node_authmw "https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/middleware/auth.js"
click node_levelroutes "https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/routes/levels.js"
click node_containerroutes "https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/routes/containers.js"
click node_socket "https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/sockets/terminal.js"
click node_levels "https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/data/levels.js"
click node_challenges "https://github.com/gaurav-patil-13/wargames/tree/main/challenges"
click node_docker_service "https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/services/dockerService.js"
click node_progress "https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/services/progressService.js"
click node_db "https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/db.js"

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_app,node_authui,node_login,node_dashboard,node_challenge,node_terminalui,node_api_client toneBlue
class node_server,node_authroutes,node_authmw,node_levelroutes,node_containerroutes,node_socket,node_postgres toneAmber
class node_levels,node_challenges,node_docker_service toneMint
class node_progress,node_db toneRose
class node_learner,node_docker toneIndigo
```

## Components

### Browser app

- [Routes and session gate](https://github.com/gaurav-patil-13/wargames/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Session provider](https://github.com/gaurav-patil-13/wargames/blob/main/frontend/src/utils/auth.jsx): `frontend/src/utils/auth.jsx`
- [Login and registration](https://github.com/gaurav-patil-13/wargames/blob/main/frontend/src/pages/Login.jsx): `frontend/src/pages/Login.jsx`
- [Level dashboard](https://github.com/gaurav-patil-13/wargames/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Challenge controls](https://github.com/gaurav-patil-13/wargames/blob/main/frontend/src/pages/Challenge.jsx): `frontend/src/pages/Challenge.jsx`
- [Browser terminal](https://github.com/gaurav-patil-13/wargames/blob/main/frontend/src/components/TerminalPane.jsx): `frontend/src/components/TerminalPane.jsx`
- [HTTP API client](https://github.com/gaurav-patil-13/wargames/blob/main/frontend/src/utils/api.js): `frontend/src/utils/api.js`

### Backend API

- [HTTP and socket server](https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/server.js): `backend/src/server.js`
- [Authentication routes](https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/routes/auth.js): `backend/src/routes/auth.js`
- [JWT authentication](https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/middleware/auth.js): `backend/src/middleware/auth.js`
- [Level and flag routes](https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/routes/levels.js): `backend/src/routes/levels.js`
- [Container routes](https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/routes/containers.js): `backend/src/routes/containers.js`
- [Terminal socket handler](https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/sockets/terminal.js): `backend/src/sockets/terminal.js`

### Challenge runtime

- [Level catalog](https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/data/levels.js): `backend/src/data/levels.js`
- [Challenge environments](https://github.com/gaurav-patil-13/wargames/tree/main/challenges): `challenges`
- [Container and shell service](https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/services/dockerService.js): `backend/src/services/dockerService.js`

### Platform state

- [Unlock and XP service](https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/services/progressService.js): `backend/src/services/progressService.js`
- [Database access](https://github.com/gaurav-patil-13/wargames/blob/main/backend/src/db.js): `backend/src/db.js`

### Other components

- **Learner**
- **PostgreSQL**
- **Docker Engine**

## Connections

- Learner → Routes and session gate: uses
- Routes and session gate → Session provider: checks session
- Routes and session gate → Level dashboard: routes
- Routes and session gate → Challenge controls: routes
- Learner → Login and registration: signs in
- Login and registration → Session provider: requests session
- Level dashboard → HTTP API client: fetches levels
- Challenge controls → HTTP API client: calls endpoints
- Challenge controls → Browser terminal: opens shell
- Browser terminal → Terminal socket handler: terminal events
- HTTP API client → HTTP and socket server: HTTP requests
- HTTP and socket server → Authentication routes: dispatches
- HTTP and socket server → Level and flag routes: dispatches
- HTTP and socket server → Container routes: dispatches
- HTTP and socket server → Terminal socket handler: registers handler
- Authentication routes → JWT authentication: protects profile
- Level and flag routes → JWT authentication: protects routes
- Container routes → JWT authentication: protects routes
- Terminal socket handler → JWT authentication: verifies token
- Level and flag routes → Level catalog: reads catalog
- Level and flag routes → Unlock and XP service: checks and records
- Container routes → Level catalog: loads level
- Container routes → Container and shell service: starts or destroys
- Terminal socket handler → Container and shell service: opens shell
- Container and shell service → Challenge environments: builds image from
- Container and shell service → Docker Engine: builds and controls
- Unlock and XP service → Database access: reads and writes
- Authentication routes → Database access: reads and writes users
- Container and shell service → Database access: records containers
- Database access → PostgreSQL: queries