NPS Codebase Map¶
A generated, docs-only map of the NPS monorepo. Two thin Avalonia apps on top of one shared C# shell + host border + one deep C++ engine behind a frozen C ABI.
This is the canonical place to start when you want to know what exists
where, what crosses which boundary, and which file owns which contract.
For the architectural why and the design rationale, follow the links
into docs/architecture.md, docs/modules/*.md, and docs/abi-inventory.md.
This section is docs only. It must never modify anything under
src/. It is regenerated by the nps-codebase-map skill from the
live tree (headers, apps, tests, scripts). Temporary agent caches
under /tmp/ are optional and not authoritative.
Reading order¶
The pages are ordered for a first-time reader. Skip to any page; each is self-contained.
| # | Page | Contents |
|---|---|---|
| 1 | overview.md | What NPS is, top-down layer diagram, 30-second shape. |
| 2 | layers-and-contracts.md | The six layers, forbidden edges, include DAG. |
| 3 | engine-modules.md | C++ modules under src/Engine/internal/, what each owns and does not. |
| 4 | c-abi.md | The frozen C ABI surface, every production export + test-gated symbols, POD layouts. |
| 5 | engine-host.md | Nps.EngineHost C# host-border (P/Invoke + RAII + session facade). |
| 6 | shell-and-apps.md | Nps.Shell and the two Avalonia apps. |
| 7 | user-flows.md | Boot, load -> gen demo -> analyze -> render, finding click, playback. |
| 8 | data-model.md | PODs, mesh/gcode/finding data model, golden fixture. |
| 9 | test-coverage.md | Dual-harness (C++ Catch2 + C# xUnit) counts and matrix. |
| 10 | quality-gates.md | Scripts, ctest gates, lefthook pipeline. |
| 11 | glossary.md | Naming, wire-id constants, acronyms. |
How this artifact is maintained¶
- It is a generated artifact. Re-run the
nps-codebase-mapskill after large merges that change modules, ABI, app flows, or tests. - All authoritative contracts live in
docs/architecture.md,docs/abi-inventory.md, and the per-module docs underdocs/modules/. This map links to them rather than restating them.
Hard rules¶
- DOCUMENTATION ONLY. Nothing under
src/may be modified by this artifact. - The demo toolpath generator (
GenerateGcode/EngineSession.GenerateDemoToolpath) is NOT a production slice. It is explicitly labeled inengine.h, in the generated G-code header, in the UI status text, and here. GetMeshBoundsis a C ABI export only whenNPS_ENABLE_TEST_HOOKSis defined. The C++ class still exposes it for Catch2 load-validation, but the C ABI export is gated.