Project Maintenance Guide

This skill guides agents and developers on how to maintain the QuanuX project structure as it scales.

1. Build System: CMake Presets (CMakePresets.json)

QuanuX uses CMakePresets.json (version 3) as the source of truth for C++ build configurations. This file allows CLion, Visual Studio, and VSCode to share the same build definitions.

Adding a New C++ Component

When adding a new C++ project (e.g., QuanuX-Rust-Bridge):

1. •Define a Configure Preset: Add an entry under configurePresets.
   • •Set binaryDir to ${sourceDir}/<Component>/cpp/build.
   • •Ensure CMAKE_EXPORT_COMPILE_COMMANDS is ON (crucial for LSP/IntelliSense).
2. •Define a Build Preset: Add an entry under buildPresets.
   • •Target the executable name defined in your CMakeLists.txt.

2. VSCode Integration (.vscode/)

VSCode configuration is manual but relies on the artifacts generated by CMake.

• •c_cpp_properties.json:
  • •CRITICAL: Each configuration must point compileCommands to the specific build directory defined in CMakePresets.json.
  • •Example: "${workspaceFolder}/execution-node/cpp/build/compile_commands.json"
  • •Update includePath to include any new shared headers (e.g., QuanuX-Common).
• •tasks.json:
  • •Add build tasks invoking make or cmake --build in the respective directories.
• •launch.json:
  • •Add debug configurations for new binaries. Use lldb (macOS) or gdb (Linux).
  • •Set cwd to the binary's build directory to ensure relative paths (like config files) work.

3. Native IDE Support (Xcode & Spyder)

We provide helper scripts in scripts/ to generate native project files.

• •Xcode: scripts/generate_xcode.sh
  • •Action: Execute this script after adding a new CMake component to generate the .xcodeproj.
  • •Maintenance: If a new component is added, add a cmake .. -G Xcode block for it in the script.
• •Spyder: scripts/setup_spyder.py
  • •Action: Run this to initialize .spyproject.
  • •Maintenance: If a new Python package is added, ensure specific PYTHONPATH settings are documented or automatable if Spyder requires them (usually standard virtualenv suffices).

4. NATS & Polyglot Wiring

• •ABI Compatibility: Any shared C++ structs MUST reside in QuanuX-Common and use strictly defined types (uint64_t, double). Avoid std::string or STL containers in structs passed across ABI boundaries (DLLs/Shared Objects).
• •NATS Subjects:
  • •Market Data: market.data.<symbol>
  • •Simulation: SIM (Replayed ticks)
  • •Telemetry: node.telemetry.<type>

5. Directory Structure Sanity

• •server/: Python-only. Backend logic.
• •execution-node/: C++ Performance Critical.
• •QuanuX-Backtesting-Engine/: C++ Core + Python Bindings.
• •QuanuX-Common/: Pure Headers/Shared Logic.
• •extensions/: 3rd-party integrations (Rithmic, Databento).

Rule: Do not cross-link dependencies (e.g., Server importing Execution Node headers directly) unless via defined Interfaces (Protobuf/NATS/Common Headers).