BugLab - Maze Pathfinding & Optimization Project

C++ pathfinding and maze optimization project for buglab.ru.

Project Architecture & Directory Structure

buglab/
├── CMakeLists.txt        # CMake build configuration (C++23)
├── Makefile              # Build shortcuts (wraps CMake)
├── run.sh                # Background runner with cpulimit (160% CPU)
├── README.md             # Project documentation
├── src/
│   └── main.cpp          # Core Tabu Search optimizer engine & logger
├── deploy/               # Isolated runtime instances (ignored in git)
│   └── main/             # Main production instance (binary, logs, best.txt)
├── junk/                 # Utility scripts (decoders, encoders, score testers)
├── docs/                 # Project documentation and research logs
│   ├── ideas.md          # Short-term ideas and backlog
│   ├── observations.md   # Key heuristics and insights
│   ├── research.md       # General research and milestone notes
│   └── experiments/      # Detailed logs for specific experiments
└── storage/              # Global research repository & database
    ├── labyrinths.db     # SQLite database for saved labyrinths & metadata
    ├── schema.sql        # Database schema definition
    └── logs/             # Structured daily logs (UTC+3 / Minsk timezone)
        ├── service/      # Telemetry & step-by-step metrics (service_YYYY-MM-DD.log)
        └── highscores/   # Full ASCII dumps for scores > 1,000,000 (high_YYYY-MM-DD.log)

Instance Deployment Architecture

To support simultaneous running of experimental and production optimizer instances without interfering with source compilation, BugLab uses an isolated deploy/ directory structure:

• deploy/main/: The primary standalone execution environment. It contains its own compiled optimizer binary, its local working best.txt, and localized log directories.
• Experimental Instances: Additional folders (e.g., deploy/experiment-1/) can be set up independently to test new algorithmic parameters or heuristics in parallel.
• Global Storage: The storage/ directory serves as a centralized research repository where high-performing labyrinths and telemetry data from various test runs can be aggregated.

Database Schema (storage/schema.sql)

The SQLite database tracks high-performing labyrinths, scores, and categorical tags:

• labyrinths: Stores core metadata and layout blobs.
  • id (INTEGER, PK): Unique record identifier.
  • score (INTEGER): Calculated performance score (indexed descending for fast queries).
  • field_blob (BLOB): Raw serialized labyrinth layout.
  • width (INTEGER): Grid width (default 29).
  • height (INTEGER): Grid height (default 19).
  • created_at (TIMESTAMP): Record creation timestamp.
• tags & labyrinth_tags: Many-to-many relationship tables for categorizing labyrinths (e.g., by algorithm version, experiment phase, or benchmark status).

Logging & Monitoring

• Timezone: Timestamps are synchronized to Europe/Minsk (UTC+3).
• Telemetry: Service logs record step, current score, best score, and distance from best every 100 steps, as well as every new best record.
• Highscores: Mazes achieving a score above 1,000,000 are automatically dumped with full ASCII art.
• Automation: A monitoring cron job (buglab-progress-monitor) runs every 4 hours to review progress and report status.

Build & Run

1. Build the project:

   make
   

2. Deploy to an instance (e.g., deploy/main/):

   mkdir -p deploy/main
   cp build/optimizer deploy/main/
   

3. Run optimizer in background with resource limit (160% CPU):

   cd deploy/main
   ./run.sh ./optimizer
   

4. Clean build artifacts:

   make clean