project-maintenance-ide-configuration

name	Project Maintenance & IDE Configuration
description	Instructions for maintaining the QuanuX polyglot project structure and IDE integrations (VSCode, CLion, Xcode, Spyder).

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).