# mineqihang/codecraft2025-public architecture

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

- Interactive diagram: https://gitdiagram.com/mineqihang/codecraft2025-public
- Repository: https://github.com/mineqihang/codecraft2025-public

## Overview

1. **Repository purpose**
   - This is a competition solver repository for **Huawei CodeCraft 2025**, organized into three independent solutions: **preliminary**, **semifinal**, and **final**.
   - Each stage is a separate C++17 program with its own source tree, build scripts, test scripts, and challenge PDFs.

2. **Top-level structure**
   - `preliminary/`, `semifinal/`, and `final/` are the main architecture boundaries.
   - `docs/` under each stage stores the problem statement and sample data.
   - `test/` and the `data-analyze.ipynb` notebooks indicate offline evaluation and tuning were part of the workflow.
   - `images/` supports the README’s strategy explanations, not runtime behavior.

3. **Execution model**
   - Each stage is an **interactive solver**: it reads judge input from stdin, maintains internal storage/request state, and prints disk operations back to stdout.
   - The entry point is `main.cpp` in each stage, which wires the model, controller, and disk abstractions together.
   - `run.sh` / `run.py` are wrapper scripts for local execution against sample or test data, while `build.sh`/`pack.sh` handle compilation and submission packaging.

4. **Core runtime layers**
   - The codebase is split into a small set of domain objects:
     - `request.hpp`: request parsing and request-state tracking.
     - `object.hpp`: object metadata and placement state.
     - `disk.hpp`: disk-level storage layout and read/write/jump behavior.
     - `controller.hpp`: orchestration layer that decides actions each time slice.
     - `utils.hpp`: shared constants, macros, and helper functions.
   - In the final stage, these abstractions are duplicated per round where necessary.

5. **Preliminary architecture**
   - `preliminary/src/` contains a single-controller, single-disk-model solution.
   - The main dependency flow is: input stream → `Request`/`Object` construction → `Controller` scheduling → `Disk` operation generation.
   - The preliminary solver focuses on one round of decisions with one `controller.hpp` and one `disk.hpp`.

6. **Semifinal architecture**
   - `semifinal/src/` keeps the same overall shape as preliminary, but the solver must handle the more complex contest rules of that stage.
   - The architecture is still centered on one controller and one disk model, implying the stage is handled as a single integrated strategy rather than multiple subsystems.
   - The shared file layout suggests the code remains mostly rule adaptation rather than a full redesign.

7. **Final architecture: two-round solver**
   - `final/src/` is structurally different because the final has **Round 1** and **Round 2**.
   - It includes:
     - `controller_round1.hpp`, `disk_round1.hpp`
     - `controller_round2.hpp`, `disk_round2.hpp`
     - plus shared `controller.hpp`, `disk.hpp`, `object.hpp`, `request.hpp`, `utils.hpp`
   - This indicates a two-phase architecture: each round has its own controller/disk specialization, while the shared types provide common state and utilities.

8. **Final-stage data flow**
   - Round 1 handles uncertain information and online inference-like behavior.
   - Round 2 reuses the same data model but can exploit more complete information and more precise planning.
   - The solver therefore appears to pass accumulated state from the common model into round-specific controllers, rather than treating the rounds as unrelated programs.

9. **Algorithmic boundary vs. infrastructure boundary**
   - The repository is **mostly algorithmic**, not service-oriented.
   - There is no sign of databases, network services, or external APIs in runtime architecture; the important boundary is between:
     - judge-provided event stream
     - in-memory scheduling/state
     - emitted disk commands
   - The PDFs in `docs/` are a key input to implementation but not part of execution.

10. **Build and packaging pipeline**
   - Each stage uses `CMakeLists.txt` for compilation, so the codebase is designed around standard C++ build tooling.
   - `build.sh` likely compiles the solver locally.
   - `pack.sh` likely prepares the final submission artifact.
   - `run.sh` and `run.py` provide convenience wrappers for local replay and regression testing.

11. **Testing and analysis boundary**
   - `test.sh` and the `test/` directory are used to validate solver behavior on sample or custom cases.
   - The notebooks under `test/` are for offline data analysis and parameter tuning, which is important because the solver strategy depends heavily on empirical tuning.
   - This means the repo includes both the production solver and the offline experimentation workflow.

12. **What to draw in an architecture diagram**
   - Draw three separate stage boxes: preliminary, semifinal, final.
   - Inside each, show a `main.cpp` entry point feeding a `controller` and `disk` model, with `request` and `object` as shared state entities.
   - For the final stage, split the controller/disk into Round 1 and Round 2 branches, both using shared domain types.
   - Around the solver, show build/test/pack scripts and documentation as supporting tooling, not runtime components.

Main entry points: [`preliminary/src/main.cpp`](https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/src/main.cpp) (main.cpp), [`preliminary/src/controller.hpp`](https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/src/controller.hpp) (Controller), [`semifinal/src/controller.hpp`](https://github.com/mineqihang/codecraft2025-public/blob/main/semifinal/src/controller.hpp) (Controller), [`final/src/controller_round1.hpp`](https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/controller_round1.hpp) (Round 1 controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_preliminary["Preliminary"]
  node_pre_main["main.cpp<br/>entry point<br/>[main.cpp]"]
  node_pre_controller["Controller<br/>scheduler<br/>[controller.hpp]"]
  node_pre_disk[("Disk model<br/>storage model<br/>[disk.hpp]")]
  node_pre_request["Request<br/>event state<br/>[request.hpp]"]
  node_pre_object["Object<br/>placement state<br/>[object.hpp]"]
  node_pre_utils["Utils<br/>shared helpers<br/>[utils.hpp]"]
end

subgraph group_g_semifinal["Semifinal"]
  node_semi_main["main.cpp<br/>entry point<br/>[main.cpp]"]
  node_semi_controller["Controller<br/>scheduler<br/>[controller.hpp]"]
  node_semi_disk[("Disk model<br/>storage model<br/>[disk.hpp]")]
  node_semi_request["Request<br/>event state<br/>[request.hpp]"]
  node_semi_object["Object<br/>placement state<br/>[object.hpp]"]
  node_semi_utils["Utils<br/>shared helpers<br/>[utils.hpp]"]
end

subgraph group_g_final["Final"]
  node_final_main["main.cpp<br/>entry point<br/>[main.cpp]"]
  node_final_controller1["Round 1 controller<br/>round strategy"]
  node_final_disk1[("Round 1 disk<br/>round storage model<br/>[disk_round1.hpp]")]
  node_final_controller2["Round 2 controller<br/>round strategy"]
  node_final_disk2[("Round 2 disk<br/>round storage model<br/>[disk_round2.hpp]")]
  node_final_controller["Shared controller<br/>common orchestration<br/>[controller.hpp]"]
  node_final_disk[("Shared disk<br/>common storage model<br/>[disk.hpp]")]
  node_final_request["Request<br/>event state<br/>[request.hpp]"]
  node_final_object["Object<br/>placement state<br/>[object.hpp]"]
  node_final_utils["Utils<br/>shared helpers<br/>[utils.hpp]"]
end

subgraph group_g_tooling["Tooling"]
  node_build_sh["build.sh<br/>build script<br/>[build.sh]"]
  node_pack_sh["pack.sh<br/>packaging script<br/>[pack.sh]"]
  node_run_scripts["run scripts<br/>execution wrapper<br/>[run.sh]"]
  node_test_scripts["test harness<br/>validation wrapper<br/>[test.sh]"]
  node_docs["Task docs<br/>problem statements"]
  node_analysis["Data analysis<br/>offline notebook<br/>[data-analyze.ipynb]"]
end

node_pre_main -->|"parse"| node_pre_request
node_pre_main -->|"build"| node_pre_object
node_pre_main -->|"run"| node_pre_controller
node_pre_controller -->|"emit ops"| node_pre_disk
node_pre_controller -->|"consume"| node_pre_request
node_pre_controller -->|"update"| node_pre_object
node_pre_controller -.->|"use"| node_pre_utils
node_pre_disk -.->|"use"| node_pre_utils
node_semi_main -->|"parse"| node_semi_request
node_semi_main -->|"build"| node_semi_object
node_semi_main -->|"run"| node_semi_controller
node_semi_controller -->|"emit ops"| node_semi_disk
node_semi_controller -->|"consume"| node_semi_request
node_semi_controller -->|"update"| node_semi_object
node_semi_controller -.->|"use"| node_semi_utils
node_semi_disk -.->|"use"| node_semi_utils
node_final_main -->|"parse"| node_final_request
node_final_main -->|"build"| node_final_object
node_final_main -->|"dispatch"| node_final_controller
node_final_controller -->|"round 1"| node_final_controller1
node_final_controller -->|"round 2"| node_final_controller2
node_final_controller1 -->|"emit ops"| node_final_disk1
node_final_controller2 -->|"emit ops"| node_final_disk2
node_final_controller1 -->|"consume"| node_final_request
node_final_controller2 -->|"consume"| node_final_request
node_final_controller1 -->|"update"| node_final_object
node_final_controller2 -->|"update"| node_final_object
node_final_controller1 -.->|"use"| node_final_utils
node_final_controller2 -.->|"use"| node_final_utils
node_final_disk1 -.->|"use"| node_final_utils
node_final_disk2 -.->|"use"| node_final_utils
node_build_sh -.->|"builds"| node_pre_main
node_pack_sh -.->|"packages"| node_pre_main
node_run_scripts -.->|"runs"| node_pre_main
node_test_scripts -.->|"validates"| node_pre_main
node_docs -.->|"specifies"| node_pre_main
node_analysis -.->|"tunes"| node_pre_controller

click node_pre_main "https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/src/main.cpp"
click node_pre_controller "https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/src/controller.hpp"
click node_pre_disk "https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/src/disk.hpp"
click node_pre_request "https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/src/request.hpp"
click node_pre_object "https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/src/object.hpp"
click node_pre_utils "https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/src/utils.hpp"
click node_semi_main "https://github.com/mineqihang/codecraft2025-public/blob/main/semifinal/src/main.cpp"
click node_semi_controller "https://github.com/mineqihang/codecraft2025-public/blob/main/semifinal/src/controller.hpp"
click node_semi_disk "https://github.com/mineqihang/codecraft2025-public/blob/main/semifinal/src/disk.hpp"
click node_semi_request "https://github.com/mineqihang/codecraft2025-public/blob/main/semifinal/src/request.hpp"
click node_semi_object "https://github.com/mineqihang/codecraft2025-public/blob/main/semifinal/src/object.hpp"
click node_semi_utils "https://github.com/mineqihang/codecraft2025-public/blob/main/semifinal/src/utils.hpp"
click node_final_main "https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/main.cpp"
click node_final_controller1 "https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/controller_round1.hpp"
click node_final_disk1 "https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/disk_round1.hpp"
click node_final_controller2 "https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/controller_round2.hpp"
click node_final_disk2 "https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/disk_round2.hpp"
click node_final_controller "https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/controller.hpp"
click node_final_disk "https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/disk.hpp"
click node_final_request "https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/request.hpp"
click node_final_object "https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/object.hpp"
click node_final_utils "https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/utils.hpp"
click node_build_sh "https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/build.sh"
click node_pack_sh "https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/pack.sh"
click node_run_scripts "https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/run.sh"
click node_test_scripts "https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/test.sh"
click node_docs "https://github.com/mineqihang/codecraft2025-public/tree/main/preliminary/docs"
click node_analysis "https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/test/data-analyze.ipynb"

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_pre_main,node_pre_controller,node_pre_disk,node_pre_request,node_pre_object,node_pre_utils toneBlue
class node_semi_main,node_semi_controller,node_semi_disk,node_semi_request,node_semi_object,node_semi_utils toneAmber
class node_final_main,node_final_controller1,node_final_disk1,node_final_controller2,node_final_disk2,node_final_controller,node_final_disk,node_final_request,node_final_object,node_final_utils toneMint
class node_build_sh,node_pack_sh,node_run_scripts,node_test_scripts,node_docs,node_analysis toneRose
```

## Components

### Preliminary

Initial contest-stage solver and its local workflow.

- [main.cpp](https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/src/main.cpp): entry point · Wires stdin parsing, state setup, and solver execution for the preliminary stage. · `preliminary/src/main.cpp`
- [Controller](https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/src/controller.hpp): scheduler · Chooses actions for each decision step in the preliminary solver. · `preliminary/src/controller.hpp`
- [Disk model](https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/src/disk.hpp): storage model · Represents storage layout and emits disk operations for the preliminary solver. · `preliminary/src/disk.hpp`
- [Request](https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/src/request.hpp): event state · Parses judge requests and tracks per-request state. · `preliminary/src/request.hpp`
- [Object](https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/src/object.hpp): placement state · Stores object metadata and placement information. · `preliminary/src/object.hpp`
- [Utils](https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/src/utils.hpp): shared helpers · Common constants, macros, and helper functions. · `preliminary/src/utils.hpp`

### Semifinal

Mid-stage solver with the same core architecture as preliminary.

- [main.cpp](https://github.com/mineqihang/codecraft2025-public/blob/main/semifinal/src/main.cpp): entry point · Entry point for the semifinal solver and its interactive loop. · `semifinal/src/main.cpp`
- [Controller](https://github.com/mineqihang/codecraft2025-public/blob/main/semifinal/src/controller.hpp): scheduler · Coordinates semifinal-stage decisions under the stage-specific rules. · `semifinal/src/controller.hpp`
- [Disk model](https://github.com/mineqihang/codecraft2025-public/blob/main/semifinal/src/disk.hpp): storage model · Maintains disk behavior and generates operations for semifinal play. · `semifinal/src/disk.hpp`
- [Request](https://github.com/mineqihang/codecraft2025-public/blob/main/semifinal/src/request.hpp): event state · Request parsing and tracking for the semifinal stage. · `semifinal/src/request.hpp`
- [Object](https://github.com/mineqihang/codecraft2025-public/blob/main/semifinal/src/object.hpp): placement state · Object metadata and placement state for semifinal logic. · `semifinal/src/object.hpp`
- [Utils](https://github.com/mineqihang/codecraft2025-public/blob/main/semifinal/src/utils.hpp): shared helpers · Semifinal shared constants and utility helpers. · `semifinal/src/utils.hpp`

### Final

Two-round final-stage solver with shared state and round-specific logic.

- [main.cpp](https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/main.cpp): entry point · Entry point that dispatches the final-stage two-round solver. · `final/src/main.cpp`
- [Round 1 controller](https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/controller_round1.hpp): round strategy · Round 1 decision logic for uncertain or online information. · `final/src/controller_round1.hpp`
- [Round 1 disk](https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/disk_round1.hpp): round storage model · Round 1 disk behavior and emitted operations. · `final/src/disk_round1.hpp`
- [Round 2 controller](https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/controller_round2.hpp): round strategy · Round 2 planning logic using the accumulated state and more complete information. · `final/src/controller_round2.hpp`
- [Round 2 disk](https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/disk_round2.hpp): round storage model · Round 2 disk behavior and emitted operations. · `final/src/disk_round2.hpp`
- [Shared controller](https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/controller.hpp): common orchestration · Shared orchestration layer and common control abstractions for the final stage. · `final/src/controller.hpp`
- [Shared disk](https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/disk.hpp): common storage model · Shared disk abstraction reused by both final-stage rounds. · `final/src/disk.hpp`
- [Request](https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/request.hpp): event state · Common request parsing and state tracking for the final stage. · `final/src/request.hpp`
- [Object](https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/object.hpp): placement state · Common object metadata and placement state for both rounds. · `final/src/object.hpp`
- [Utils](https://github.com/mineqihang/codecraft2025-public/blob/main/final/src/utils.hpp): shared helpers · Final-stage shared constants, macros, and helper functions. · `final/src/utils.hpp`

### Tooling

Build, run, test, and packaging support outside the runtime path.

- [build.sh](https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/build.sh): build script · Local compilation wrapper for a stage. · `preliminary/build.sh`
- [pack.sh](https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/pack.sh): packaging script · Creates submission artifacts for a stage. · `preliminary/pack.sh`
- [run scripts](https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/run.sh): execution wrapper · Local replay wrappers for sample and custom runs. · `preliminary/run.sh`
- [test harness](https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/test.sh): validation wrapper · Regression and sample validation entry point. · `preliminary/test.sh`
- [Task docs](https://github.com/mineqihang/codecraft2025-public/tree/main/preliminary/docs): problem statements · Stage PDFs and sample data used to implement and validate the solvers. · `preliminary/docs`
- [Data analysis](https://github.com/mineqihang/codecraft2025-public/blob/main/preliminary/test/data-analyze.ipynb): offline notebook · Notebook-based tuning and offline evaluation workflow. · `preliminary/test/data-analyze.ipynb`

## Connections

- main.cpp → Request: parse · Main reads judge input into request state.
- main.cpp → Object: build · Main initializes object metadata and placement state.
- main.cpp → Controller: run · Main drives the preliminary controller loop.
- Controller → Disk model: emit ops · Controller asks the disk model for storage actions.
- Controller → Request: consume · Controller reacts to incoming requests and their state.
- Controller → Object: update · Controller updates object placement knowledge while scheduling.
- Controller → Utils: use · Controller relies on shared helpers and constants.
- Disk model → Utils: use · Disk model uses shared helpers and constants.
- main.cpp → Request: parse · Main reads semifinal judge input into request state.
- main.cpp → Object: build · Main initializes object metadata and placement state.
- main.cpp → Controller: run · Main drives the semifinal controller loop.
- Controller → Disk model: emit ops · Controller coordinates semifinal disk operations.
- Controller → Request: consume · Controller reacts to semifinal requests and state.
- Controller → Object: update · Controller updates object placement knowledge.
- Controller → Utils: use · Controller relies on shared helpers and constants.
- Disk model → Utils: use · Disk model uses shared helpers and constants.
- main.cpp → Request: parse · Main reads judge input into the common final-stage request model.
- main.cpp → Object: build · Main initializes the common object state.
- main.cpp → Shared controller: dispatch · Main dispatches into the shared final-stage orchestration layer.
- Shared controller → Round 1 controller: round 1 · Shared orchestration hands control to the round 1 strategy.
- Shared controller → Round 2 controller: round 2 · Shared orchestration hands control to the round 2 strategy.
- Round 1 controller → Round 1 disk: emit ops · Round 1 controller produces round-specific disk actions.
- Round 2 controller → Round 2 disk: emit ops · Round 2 controller produces round-specific disk actions.
- Round 1 controller → Request: consume · Round 1 logic consumes the shared request stream.
- Round 2 controller → Request: consume · Round 2 logic consumes the shared request stream.
- Round 1 controller → Object: update · Round 1 updates shared object state.
- Round 2 controller → Object: update · Round 2 updates shared object state.
- Round 1 controller → Utils: use · Round 1 depends on shared helpers and constants.
- Round 2 controller → Utils: use · Round 2 depends on shared helpers and constants.
- Round 1 disk → Utils: use · Round 1 disk model uses shared helpers and constants.
- Round 2 disk → Utils: use · Round 2 disk model uses shared helpers and constants.
- build.sh → main.cpp: builds · Build script compiles the preliminary solver.
- pack.sh → main.cpp: packages · Packaging script prepares the preliminary submission binary.
- run scripts → main.cpp: runs · Local run wrappers execute the preliminary solver.
- test harness → main.cpp: validates · Test harness replays cases against the preliminary solver.
- Task docs → main.cpp: specifies · Problem statements and samples guide solver implementation.
- Data analysis → Controller: tunes · Notebook workflow supports strategy tuning and offline evaluation.