Repository Layout

Repository Layout

Beez uses a flat module layout: public headers under include/beez/, implementations under src/, tests mirroring production code. Do not nest extra src/ or include/ folders inside modules.

Top level

Path	Purpose
include/beez/	Public C++ API headers
src/	Implementation (.cpp) grouped by module
tests/	Unit, integration, system, performance, fuzz tests
cmake/	Shared CMake modules (warnings, sanitizers, coverage)
scripts/	QA scripts, CI helpers, shell completion
conan/	Conan profiles
report/	Generated QA output (gitignored)
build/	Build tree (gitignored)

Source modules

Module	Headers	Implementation	Responsibility
core	include/beez/core/	src/core/	Models, registry, orchestrator, cache, config, settings
cli	include/beez/cli/	src/cli/	Argument parsing, target execution, listing
logging	include/beez/logging/	src/logging/	Output modes, progress UI backend, run logs
plugins/lua	include/beez/plugins/lua/	src/plugins/lua/	build.lua DSL parsing and settings
plugins/shell	include/beez/plugins/shell/	src/plugins/shell/	Shell command execution
app	-	src/app/	main() entry point

Tests

Directory	Binary / runner	What it covers
tests/unit/	beez_tests	Isolated logic, mirrors src/ structure
tests/integration/	beez_integration_tests	Multi-component pipelines, CLI subprocess
tests/system/	beez_system_tests	Black-box runs against fixture build.lua projects
tests/performance/	beez_perf_tests	Throughput benchmarks (labeled performance)
tests/fuzz/	fuzz_lua_dsl	Robustness of Lua DSL parser

System fixtures live at tests/system/fixtures/<name>/build.lua.

Fuzz seeds live at tests/fuzz/corpus/lua_dsl/*.lua.

Adding a new file

1. Place the header in include/beez/<module>/
2. Place the .cpp in src/<module>/
3. Register the .cpp in the module CMakeLists.txt
4. Add tests in the matching tests/<level>/ folder
5. Register test .cpp files in that level's CMakeLists.txt

Layering rules

Typical dependency direction:

app → cli → core ← plugins (lua, shell)
              ↑
           logging

• Core must not depend on CLI or plugins.
• Plugins translate external input (Lua tables, shell) into core models.
• Touch src/app/main.cpp only when global CLI wiring changes.

Related pages

• Feature Development Workflow - which layer to change for a feature
• Testing - where to put each test type
• Building and Setup - compile commands