Project plan and architecture: components, data flow, end-to-end workflows and the execution roadmap

[fasharif]

Adds PROJECT-PLAN.md, a single project plan and architecture document for greenbench as it stands on main (79469ec, harness 2.2.0). It summarises and links to the README, docs/study.md, docs/decisions.md (ADR 1 to 20), docs/bare-metal.md and docs/results.md rather than repeating them. A reader who reads only the plan can still follow it.

What the plan covers

1. Overview: purpose and scope, current status (built, measured and published, pending, planned), a tech stack table with pinned versions, a system components diagram and a data flow diagram.

2. Requirements: 24 functional and 10 non-functional requirements. Each one names the modules that meet it and says whether it is built, partly built or planned.

3. Architecture: the style (a batch pipeline of command-line programs that hand off through files), the layers and boundaries, the runtime and CI topology, the file-based data store (runs.csv, meta.json, environment.txt, summary.csv, the grid table and the generated docs), and what each ADR does to the architecture.

4. Modules: all 15 modules (M1 to M15), from the workload core and the three workers through the harness, RAPL reader, analysis and report to the scripts, CI and test infrastructure. Each one uses the same 15 headings in order, from Purpose to Deployment. Headings that do not apply say "Not applicable" and give the reason.

5. End-to-end feature workflows: 9 features (F1 to F9): probe, measure a run, cross-language parity, the report and README block (including the withheld-timings mode), carbon, the bare-metal study, the Docker timing run, the smoke run and CI. Each has a trigger, preconditions, numbered happy-path steps and a sequence diagram. Each also has a failure-path table: where the failure is detected, the exact message and exit status, the state left behind, and how to recover.

6. Cross-cutting concerns: the security model (including the RAPL side channel, CVE-2020-8694), configuration, logging, performance, accessibility and internationalisation.

7. Execution roadmap: 11 prioritised items, each with files, dependencies, acceptance criteria and a size:

   • settling the Docker image's Node.js version, and optionally building the Dockerfile in CI;
   • the pending bare-metal energy study and its publication;
   • README roadmap items 1 to 4;
   • the comparison of pinned and unpinned runs.

   Five decisions follow (D1 to D5).

How it was checked

• A fact-check compared the plan with the source, tests, scripts, CI workflow and docs. It looked at file paths, function names, constants, option ranges, exit statuses, CSV columns, meta.json fields, test names and quoted error messages. It found no critical or major problems. All 14 minor corrections were applied. Examples: per-sort time and energy share one set of bootstrap draws, but the other estimates are resampled separately; counters_move is in greenbench.c, and the F2 diagram now shows the real call order; the missing pin_cpus and rapl_open messages were added; the depth of the find_repository search is now correct. The three coverage gaps were also filled: the Node.js tsconfig.json and eslint.config.js, a happy path for --withhold-timings, and a roadmap row for building the Dockerfile in CI.
• All 13 Mermaid diagrams were rendered with mermaid-cli in Docker, with no errors. They were rendered again after the F1 and F2 diagrams changed. The render outputs were not committed.
• The plan is documentation only. No code, data or generated results change.

🤖 Generated with Claude Code

[fasharif]

Closing: the project plan is kept locally instead of in the repository.