# pwncollege/challenges architecture

> Architecture diagram of the GitHub repository pwncollege/challenges, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pwncollege/challenges
- Repository: https://github.com/pwncollege/challenges

## Overview

This is a pwn.college challenge monorepo: challenge directories hold the artifacts that are rendered, built into containers, and run or tested through the pwnshop CLI. The graph also shows the separate workspace-agent runtime and representative curriculum areas, including the substantial PyPU challenge modules. Workflow links follow the README or shown source calls; many challenge files and runtime internals were not sampled, so their behavior and connections are not inferred.

Main entry points: [`runtime/workspace/agent/internal/workspace/server.go`](https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/internal/workspace/server.go) (HTTP Agent), [`tools/pwnshop/src/pwnshop/__main__.py`](https://github.com/pwncollege/challenges/blob/main/tools/pwnshop/src/pwnshop/__main__.py) (pwnshop CLI), [`challenges`](https://github.com/pwncollege/challenges/tree/main/challenges) (Challenge Artifacts), [`tools/pwnshop/src/pwnshop/lib/__init__.py`](https://github.com/pwncollege/challenges/blob/main/tools/pwnshop/src/pwnshop/lib/__init__.py) (Challenge Helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Challenge CLI"]
  node_pwnshop["pwnshop CLI<br/>[__main__.py]"]
  node_list["List Challenges<br/>[list.py]"]
  node_render["Render Challenges<br/>[render.py]"]
  node_build["Build Image<br/>[build.py]"]
  node_run["Run Challenge<br/>[run.py]"]
  node_challenge_lib["Challenge Helpers<br/>[__init__.py]"]
  node_console["Console Output<br/>[console.py]"]
end

subgraph group_curriculum["Challenge Curriculum"]
  node_challenge_artifacts["Challenge Artifacts"]
  node_advent["Advent Challenges<br/>[generate_list.py]"]
  node_computing["Computing Lessons"]
  node_security["Security Challenges<br/>[home.php]"]
  node_bug_challenges["Bug Challenges"]
  node_pypu_device["PyPU PCI Device<br/>[pypu-pci.c]"]
  node_pypu_capture["PyPU Capture Type<br/>[pypu-capture.h]"]
  node_pypu_privileged["PyPU Hash Header<br/>[pypu-privileged.h]"]
end

subgraph group_workspace["Workspace Runtime"]
  node_entrypoint["Workspace Entrypoint<br/>[main.go]"]
  node_agent_command["Agent Command<br/>[main.go]"]
  node_supervisor["Workspace Supervisor<br/>[main.go]"]
  node_http_agent["HTTP Agent<br/>[server.go]"]
  node_workspace_service["Service Manager<br/>[service.go]"]
  node_workspace_files["File Operations<br/>[file.go]"]
  node_workspace_exec["Command Execution<br/>[exec.go]"]
  node_workspace_pty["PTY Sessions<br/>[pty.go]"]
  node_workspace_readiness["Readiness Checks<br/>[readiness.go]"]
  node_workspace_env["Workspace Environment<br/>[env.go]"]
end

subgraph group_registry["Service Registry"]
  node_registry_service["Registry Service<br/>[index.js]"]
end

node_developer(("Challenge Developer"))

node_developer -->|"uses"| node_pwnshop
node_pwnshop -.->|"dispatches"| node_list
node_pwnshop -.->|"dispatches"| node_render
node_pwnshop -.->|"dispatches"| node_build
node_pwnshop -.->|"dispatches"| node_run
node_list -.->|"lists via"| node_challenge_lib
node_render -->|"renders via"| node_challenge_lib
node_render -->|"prints with"| node_console
node_build -.->|"builds via"| node_challenge_lib
node_run -->|"builds and runs via"| node_challenge_lib
node_challenge_lib -->|"renders and builds"| node_challenge_artifacts
node_challenge_artifacts -->|"includes"| node_advent
node_challenge_artifacts -->|"includes"| node_computing
node_challenge_artifacts -->|"includes"| node_security
node_challenge_artifacts -->|"includes"| node_bug_challenges
node_pypu_device -->|"uses type"| node_pypu_capture
node_pypu_device -->|"references"| node_pypu_privileged
node_agent_command -.->|"starts"| node_http_agent
node_entrypoint -.->|"executes"| node_supervisor
node_http_agent -->|"queries services"| node_workspace_service
node_http_agent -.->|"routes requests"| node_workspace_files
node_http_agent -.->|"routes requests"| node_workspace_exec
node_http_agent -.->|"routes requests"| node_workspace_pty
node_http_agent -->|"guards routes"| node_workspace_readiness

click node_pwnshop "https://github.com/pwncollege/challenges/blob/main/tools/pwnshop/src/pwnshop/__main__.py"
click node_list "https://github.com/pwncollege/challenges/blob/main/tools/pwnshop/src/pwnshop/commands/list.py"
click node_render "https://github.com/pwncollege/challenges/blob/main/tools/pwnshop/src/pwnshop/commands/render.py"
click node_build "https://github.com/pwncollege/challenges/blob/main/tools/pwnshop/src/pwnshop/commands/build.py"
click node_run "https://github.com/pwncollege/challenges/blob/main/tools/pwnshop/src/pwnshop/commands/run.py"
click node_challenge_lib "https://github.com/pwncollege/challenges/blob/main/tools/pwnshop/src/pwnshop/lib/__init__.py"
click node_console "https://github.com/pwncollege/challenges/blob/main/tools/pwnshop/src/pwnshop/console.py"
click node_challenge_artifacts "https://github.com/pwncollege/challenges/tree/main/challenges"
click node_advent "https://github.com/pwncollege/challenges/blob/main/challenges/advent-of-pwn/2025/day-01/challenge/generate_list.py"
click node_computing "https://github.com/pwncollege/challenges/tree/main/challenges/computing-101"
click node_security "https://github.com/pwncollege/challenges/blob/main/challenges/advanced-web-security/php-security/arbitrary-file-inclusion/challenge/www/home.php"
click node_bug_challenges "https://github.com/pwncollege/challenges/tree/main/challenges/what-is-a-bug"
click node_pypu_device "https://github.com/pwncollege/challenges/blob/main/challenges/advent-of-pwn/2025/day-09/challenge/pypu-pci.c"
click node_pypu_capture "https://github.com/pwncollege/challenges/blob/main/challenges/advent-of-pwn/2025/day-09/challenge/pypu-capture.h"
click node_pypu_privileged "https://github.com/pwncollege/challenges/blob/main/challenges/advent-of-pwn/2025/day-09/challenge/pypu-privileged.h"
click node_entrypoint "https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/cmd/workspace-entrypoint/main.go"
click node_agent_command "https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/cmd/workspace-agent/main.go"
click node_supervisor "https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/cmd/workspace-supervisor/main.go"
click node_http_agent "https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/internal/workspace/server.go"
click node_workspace_service "https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/internal/workspace/service.go"
click node_workspace_files "https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/internal/workspace/file.go"
click node_workspace_exec "https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/internal/workspace/exec.go"
click node_workspace_pty "https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/internal/workspace/pty.go"
click node_workspace_readiness "https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/internal/workspace/readiness.go"
click node_workspace_env "https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/internal/workspace/env.go"
click node_registry_service "https://github.com/pwncollege/challenges/blob/main/services/registry/src/index.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_pwnshop,node_list,node_render,node_build,node_run,node_challenge_lib,node_console toneBlue
class node_challenge_artifacts,node_advent,node_computing,node_security,node_bug_challenges,node_pypu_device,node_pypu_capture,node_pypu_privileged toneAmber
class node_entrypoint,node_agent_command,node_supervisor,node_http_agent,node_workspace_service,node_workspace_files,node_workspace_exec,node_workspace_pty,node_workspace_readiness,node_workspace_env toneMint
class node_registry_service toneRose
class node_developer toneIndigo
```

## Components

### Challenge CLI

- [pwnshop CLI](https://github.com/pwncollege/challenges/blob/main/tools/pwnshop/src/pwnshop/__main__.py): `tools/pwnshop/src/pwnshop/__main__.py`
- [List Challenges](https://github.com/pwncollege/challenges/blob/main/tools/pwnshop/src/pwnshop/commands/list.py): `tools/pwnshop/src/pwnshop/commands/list.py`
- [Render Challenges](https://github.com/pwncollege/challenges/blob/main/tools/pwnshop/src/pwnshop/commands/render.py): `tools/pwnshop/src/pwnshop/commands/render.py`
- [Build Image](https://github.com/pwncollege/challenges/blob/main/tools/pwnshop/src/pwnshop/commands/build.py): `tools/pwnshop/src/pwnshop/commands/build.py`
- [Run Challenge](https://github.com/pwncollege/challenges/blob/main/tools/pwnshop/src/pwnshop/commands/run.py): `tools/pwnshop/src/pwnshop/commands/run.py`
- [Challenge Helpers](https://github.com/pwncollege/challenges/blob/main/tools/pwnshop/src/pwnshop/lib/__init__.py): `tools/pwnshop/src/pwnshop/lib/__init__.py`
- [Console Output](https://github.com/pwncollege/challenges/blob/main/tools/pwnshop/src/pwnshop/console.py): `tools/pwnshop/src/pwnshop/console.py`

### Challenge Curriculum

- [Challenge Artifacts](https://github.com/pwncollege/challenges/tree/main/challenges): `challenges`
- [Advent Challenges](https://github.com/pwncollege/challenges/blob/main/challenges/advent-of-pwn/2025/day-01/challenge/generate_list.py): `challenges/advent-of-pwn/2025/day-01/challenge/generate_list.py`
- [Computing Lessons](https://github.com/pwncollege/challenges/tree/main/challenges/computing-101): `challenges/computing-101`
- [Security Challenges](https://github.com/pwncollege/challenges/blob/main/challenges/advanced-web-security/php-security/arbitrary-file-inclusion/challenge/www/home.php): `challenges/advanced-web-security/php-security/arbitrary-file-inclusion/challenge/www/home.php`
- [Bug Challenges](https://github.com/pwncollege/challenges/tree/main/challenges/what-is-a-bug): `challenges/what-is-a-bug`
- [PyPU PCI Device](https://github.com/pwncollege/challenges/blob/main/challenges/advent-of-pwn/2025/day-09/challenge/pypu-pci.c): `challenges/advent-of-pwn/2025/day-09/challenge/pypu-pci.c`
- [PyPU Capture Type](https://github.com/pwncollege/challenges/blob/main/challenges/advent-of-pwn/2025/day-09/challenge/pypu-capture.h): `challenges/advent-of-pwn/2025/day-09/challenge/pypu-capture.h`
- [PyPU Hash Header](https://github.com/pwncollege/challenges/blob/main/challenges/advent-of-pwn/2025/day-09/challenge/pypu-privileged.h): `challenges/advent-of-pwn/2025/day-09/challenge/pypu-privileged.h`

### Workspace Runtime

- [Workspace Entrypoint](https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/cmd/workspace-entrypoint/main.go): `runtime/workspace/agent/cmd/workspace-entrypoint/main.go`
- [Agent Command](https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/cmd/workspace-agent/main.go): `runtime/workspace/agent/cmd/workspace-agent/main.go`
- [Workspace Supervisor](https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/cmd/workspace-supervisor/main.go): `runtime/workspace/agent/cmd/workspace-supervisor/main.go`
- [HTTP Agent](https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/internal/workspace/server.go): `runtime/workspace/agent/internal/workspace/server.go`
- [Service Manager](https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/internal/workspace/service.go): `runtime/workspace/agent/internal/workspace/service.go`
- [File Operations](https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/internal/workspace/file.go): `runtime/workspace/agent/internal/workspace/file.go`
- [Command Execution](https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/internal/workspace/exec.go): `runtime/workspace/agent/internal/workspace/exec.go`
- [PTY Sessions](https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/internal/workspace/pty.go): `runtime/workspace/agent/internal/workspace/pty.go`
- [Readiness Checks](https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/internal/workspace/readiness.go): `runtime/workspace/agent/internal/workspace/readiness.go`
- [Workspace Environment](https://github.com/pwncollege/challenges/blob/main/runtime/workspace/agent/internal/workspace/env.go): `runtime/workspace/agent/internal/workspace/env.go`

### Service Registry

- [Registry Service](https://github.com/pwncollege/challenges/blob/main/services/registry/src/index.js): `services/registry/src/index.js`

### Other components

- **Challenge Developer**

## Connections

- Challenge Developer → pwnshop CLI: uses (evidence: `README.md`)
- pwnshop CLI → List Challenges: dispatches
- pwnshop CLI → Render Challenges: dispatches
- pwnshop CLI → Build Image: dispatches
- pwnshop CLI → Run Challenge: dispatches
- List Challenges → Challenge Helpers: lists via
- Render Challenges → Challenge Helpers: renders via (evidence: `tools/pwnshop/src/pwnshop/commands/render.py`)
- Render Challenges → Console Output: prints with (evidence: `tools/pwnshop/src/pwnshop/commands/render.py`)
- Build Image → Challenge Helpers: builds via
- Run Challenge → Challenge Helpers: builds and runs via (evidence: `tools/pwnshop/src/pwnshop/commands/run.py`)
- Challenge Helpers → Challenge Artifacts: renders and builds (evidence: `README.md`)
- Challenge Artifacts → Advent Challenges: includes (evidence: `README.md`)
- Challenge Artifacts → Computing Lessons: includes (evidence: `README.md`)
- Challenge Artifacts → Security Challenges: includes (evidence: `README.md`)
- Challenge Artifacts → Bug Challenges: includes (evidence: `README.md`)
- PyPU PCI Device → PyPU Capture Type: uses type (evidence: `challenges/advent-of-pwn/2025/day-09/challenge/pypu-pci.c`)
- PyPU PCI Device → PyPU Hash Header: references (evidence: `challenges/advent-of-pwn/2025/day-09/challenge/pypu-pci.c`)
- Agent Command → HTTP Agent: starts
- Workspace Entrypoint → Workspace Supervisor: executes
- HTTP Agent → Service Manager: queries services (evidence: `runtime/workspace/agent/internal/workspace/server.go`)
- HTTP Agent → File Operations: routes requests
- HTTP Agent → Command Execution: routes requests
- HTTP Agent → PTY Sessions: routes requests
- HTTP Agent → Readiness Checks: guards routes (evidence: `runtime/workspace/agent/internal/workspace/server.go`)
