# openjiuwen-ai/careersim-bdci26 architecture

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

- Interactive diagram: https://gitdiagram.com/openjiuwen-ai/careersim-bdci26
- Repository: https://github.com/openjiuwen-ai/careersim-bdci26

## Overview

CareerSim Runner is the participant-side harness for submitting skills to JiuwenSwarm, driving a 48-month Career Emulator game, and producing score and replay reports. The main path is CLI → submission install and environment checks → headless WebSocket drive → score report; replay separately parses the resulting event log. README documents the game’s monthly events, quarterly actions, six-month reviews, and final grade, but those mechanics execute in the external emulator. Several module connections are inferred only where the README or sampled excerpts establish them; unsampled implementation details are omitted.

Main entry points: [`career_sim_runner/cli.py`](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/cli.py) (Runner CLI), [`career_sim_runner/headless_play.py`](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/headless_play.py) (Play orchestrator), [`career_sim_runner/score.py`](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/score.py) (Score calculation), [`career_sim_runner/ws_client.py`](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/ws_client.py) (WebSocket driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Participant interface"]
  node_cli["Runner CLI<br/>[cli.py]"]
  node_submission["Submission bundle<br/>[manifest.json]"]
  node_skills["Agent skills"]
end

subgraph group_run["Run preparation"]
  node_setup["Instance setup<br/>[setup.py]"]
  node_config["MCP config<br/>[mcp_config.py]"]
  node_install["Skill installer<br/>[install.py]"]
  node_contract["Skill contract<br/>[skill_contract.py]"]
  node_validate["Preflight checks<br/>[validate.py]"]
  node_paths["Runtime paths<br/>[paths.py]"]
end

subgraph group_game["Game execution"]
  node_headless["Play orchestrator<br/>[headless_play.py]"]
  node_ws["WebSocket driver<br/>[ws_client.py]"]
  node_prompts["Game prompts<br/>[play_headless.md]"]
  node_jiuwen["JiuwenSwarm"]
  node_emulator["Career Emulator MCP"]
  node_model["Configured model"]
end

subgraph group_results["Results and replay"]
  node_score["Score calculation<br/>[score.py]"]
  node_db[("Emulator database<br/>[db.py]")]
  node_report["Score report<br/>[report.py]"]
  node_transcript["Transcript handling<br/>[transcript.py]"]
  node_replay_parse["Event parser<br/>[parse.py]"]
  node_replay_render["Replay renderer<br/>[render.py]"]
  node_usage["Score and usage<br/>[usage.py]"]
  node_events["Event log"]
end

node_participant(("Participant"))

node_participant -->|"runs commands"| node_cli
node_cli -->|"selects"| node_submission
node_submission -->|"contains"| node_skills
node_cli -->|"configures"| node_setup
node_setup -->|"writes settings"| node_config
node_cli -->|"installs"| node_install
node_install -->|"validates layout"| node_contract
node_install -->|"copies skills"| node_skills
node_cli -->|"checks environment"| node_validate
node_validate -->|"checks MCP setup"| node_config
node_cli -->|"starts play"| node_headless
node_headless -->|"installs submission"| node_install
node_headless -->|"preflights"| node_validate
node_headless -->|"resolves endpoint"| node_setup
node_headless -->|"drives session"| node_ws
node_headless -->|"builds score"| node_score
node_ws -->|"uses prompts"| node_prompts
node_ws -->|"sends WebSocket requests"| node_jiuwen
node_jiuwen -->|"requests completions"| node_model
node_jiuwen -->|"calls MCP tools"| node_emulator
node_emulator -->|"persists game state"| node_db
node_jiuwen -->|"emits events"| node_events
node_ws -->|"records conversation"| node_transcript
node_score -->|"reads game data"| node_db
node_score -->|"builds report"| node_report
node_score -->|"uses transcript"| node_transcript
node_score -->|"uses event log"| node_events
node_cli -->|"requests replay"| node_replay_parse
node_replay_parse -->|"parses"| node_events
node_cli -->|"loads score data"| node_usage
node_usage -->|"reads score report"| node_report
node_cli -->|"renders replay"| node_replay_render
node_replay_render -->|"renders parsed turns"| node_replay_parse

click node_cli "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/cli.py"
click node_submission "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/solution/manifest.json"
click node_skills "https://github.com/openjiuwen-ai/careersim-bdci26/tree/main/solution/skills"
click node_setup "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/setup.py"
click node_config "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/mcp_config.py"
click node_install "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/install.py"
click node_contract "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/skill_contract.py"
click node_validate "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/validate.py"
click node_paths "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/paths.py"
click node_headless "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/headless_play.py"
click node_ws "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/ws_client.py"
click node_prompts "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/prompts/play_headless.md"
click node_score "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/score.py"
click node_db "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/db.py"
click node_report "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/report.py"
click node_transcript "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/transcript.py"
click node_replay_parse "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/replay/parse.py"
click node_replay_render "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/replay/render.py"
click node_usage "https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/replay/usage.py"

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_cli,node_submission,node_skills toneBlue
class node_setup,node_config,node_install,node_contract,node_validate,node_paths toneAmber
class node_headless,node_ws,node_prompts,node_jiuwen,node_emulator,node_model toneMint
class node_score,node_db,node_report,node_transcript,node_replay_parse,node_replay_render,node_usage,node_events toneRose
class node_participant toneIndigo
```

## Components

### Participant interface

- [Runner CLI](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/cli.py): `career_sim_runner/cli.py`
- [Submission bundle](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/solution/manifest.json): `solution/manifest.json`
- [Agent skills](https://github.com/openjiuwen-ai/careersim-bdci26/tree/main/solution/skills): `solution/skills`

### Run preparation

- [Instance setup](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/setup.py): `career_sim_runner/setup.py`
- [MCP config](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/mcp_config.py): `career_sim_runner/mcp_config.py`
- [Skill installer](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/install.py): `career_sim_runner/install.py`
- [Skill contract](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/skill_contract.py): `career_sim_runner/skill_contract.py`
- [Preflight checks](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/validate.py): `career_sim_runner/validate.py`
- [Runtime paths](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/paths.py): `career_sim_runner/paths.py`

### Game execution

- [Play orchestrator](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/headless_play.py): `career_sim_runner/headless_play.py`
- [WebSocket driver](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/ws_client.py): `career_sim_runner/ws_client.py`
- [Game prompts](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/prompts/play_headless.md): `career_sim_runner/prompts/play_headless.md`
- **JiuwenSwarm**
- **Career Emulator MCP**
- **Configured model**

### Results and replay

- [Score calculation](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/score.py): `career_sim_runner/score.py`
- [Emulator database](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/db.py): `career_sim_runner/db.py`
- [Score report](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/report.py): `career_sim_runner/report.py`
- [Transcript handling](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/transcript.py): `career_sim_runner/transcript.py`
- [Event parser](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/replay/parse.py): `career_sim_runner/replay/parse.py`
- [Replay renderer](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/replay/render.py): `career_sim_runner/replay/render.py`
- [Score and usage](https://github.com/openjiuwen-ai/careersim-bdci26/blob/main/career_sim_runner/replay/usage.py): `career_sim_runner/replay/usage.py`
- **Event log**

### Other components

- **Participant**

## Connections

- Participant → Runner CLI: runs commands
- Runner CLI → Submission bundle: selects
- Submission bundle → Agent skills: contains
- Runner CLI → Instance setup: configures
- Instance setup → MCP config: writes settings
- Runner CLI → Skill installer: installs
- Skill installer → Skill contract: validates layout
- Skill installer → Agent skills: copies skills
- Runner CLI → Preflight checks: checks environment
- Preflight checks → MCP config: checks MCP setup
- Runner CLI → Play orchestrator: starts play
- Play orchestrator → Skill installer: installs submission
- Play orchestrator → Preflight checks: preflights
- Play orchestrator → Instance setup: resolves endpoint
- Play orchestrator → WebSocket driver: drives session
- Play orchestrator → Score calculation: builds score
- WebSocket driver → Game prompts: uses prompts
- WebSocket driver → JiuwenSwarm: sends WebSocket requests
- JiuwenSwarm → Configured model: requests completions
- JiuwenSwarm → Career Emulator MCP: calls MCP tools
- Career Emulator MCP → Emulator database: persists game state
- JiuwenSwarm → Event log: emits events
- WebSocket driver → Transcript handling: records conversation
- Score calculation → Emulator database: reads game data
- Score calculation → Score report: builds report
- Score calculation → Transcript handling: uses transcript
- Score calculation → Event log: uses event log
- Runner CLI → Event parser: requests replay
- Event parser → Event log: parses
- Runner CLI → Score and usage: loads score data
- Score and usage → Score report: reads score report
- Runner CLI → Replay renderer: renders replay
- Replay renderer → Event parser: renders parsed turns