BOL Integration Document

1.1 Purpose

This document specifies every integration point in the BOL system: REST API endpoints, external service dependencies, data exchange formats, inter-module communication protocols, and the deployment pipeline. It serves as the definitive guide for integrating with, extending, or deploying BOL.

1.2 Integration Architecture

BOL follows a monolithic-with-clean-boundaries pattern. All components run in a single Python process, but communicate through well-defined interfaces:

• Browser ↔ Server — REST API (JSON over HTTPS) + static asset serving.
• Server ↔ Simulation — In-process Python calls with threading locks for concurrency safety.
• Server ↔ Filesystem — JSON file I/O for profiles, projects, scenarios, training, and bugs.
• Browser ↔ External CDNs — Chart.js, Three.js, Font Awesome loaded from CDN at runtime.
• Browser ↔ Web Speech API — TTS for training lesson reader (browser-native, no external service).

2.1 General Conventions

• Base URL: https://bol.drel.us (production) or http://127.0.0.1:5000 (local)
• Content-Type: All request/response bodies are application/json unless noted.
• Authentication: Session cookie (session=...) set after POST /api/profile/login.
• Error format: {"error": "Human-readable message"} with appropriate HTTP status code.
• Rate limiting: Login endpoint is rate-limited to 10 requests per 5-minute window per IP.

2.2 Simulation Control Endpoints

2.3 Data Endpoints

2.4 AI Laboratory Endpoint

2.5 Project Management Endpoints

2.6 User Account Endpoints

2.7 Training & Bug Tracker Endpoints

3.1 Python Packages

3.2 Client-Side CDN Dependencies

3.3 Browser APIs

4.1 Project JSON Schema

{
  "id": "username_timestamp_hex",
  "name": "Project Name",
  "owner": "username",
  "description": "...",
  "created": "2025-01-15T10:30:00",
  "updated": "2025-01-15T12:00:00",
  "config": {
    "initial_molecules": {"CO2": 50, "H2": 30, ...},
    "environment": {"temperature_min": 280, "temperature_max": 400, "ph_min": 5, "ph_max": 9, "pressure": 1},
    "energy_sources": {"thermal": true, "redox": true, "uv": false, "lightning": false},
    "reactions": {"reaction_radius": 2.5, "base_rate_constant": 0.008, "catalyst_multiplier": 50},
    "replication": {"error_rate": 0.02},
    "world_size": [20, 20, 20]
  },
  "runs": [
    {
      "timestamp": "2025-01-15T11:00:00",
      "steps": 500, "seed": 42,
      "results": {"complexity": 12.5, "total_molecules": 450, "vesicles": 3, "diversity": 0.82, "fitness": 0.15}
    }
  ]
}

4.2 Scenario JSON Schema

{
  "name": "Warm Little Pond",
  "description": "Wet-dry cycling in terrestrial hot springs...",
  "initial_molecules": {"CO2": 40, "H2O": 100, ...},
  "environment": {"temperature_min": 300, ...},
  "energy_sources": {"thermal": true, ...},
  "reactions": {"reaction_radius": 2.5, ...},
  "replication": {"error_rate": 0.05}
}

4.3 User Profile JSON Schema

{
  "username": "dave",
  "password_hash": "hex-encoded PBKDF2 hash",
  "salt": "hex-encoded 32-byte salt",
  "display_name": "Dave",
  "bio": "...",
  "role": "user",
  "created": "2025-01-15T10:00:00"
}

4.4 Metrics Export Formats

• CSV — One row per simulation step with columns: step, total_molecules, vesicle_count, diversity_index, complexity_score, max_fitness. Exported to output/<scenario>/metrics.csv.
• JSON — Final summary object with all metrics plus configuration. Exported to output/<scenario>/metrics.json.
• PDF — Multi-page project report generated using stdlib-only PDF builder (no external dependencies).

5.1 Deployment Steps

1. Provision Server — setup_server.sh: Creates bol user, installs Python 3.12, Nginx, certbot; configures firewall (ufw allow 22,80,443).
2. Deploy Code — deploy_to_server.ps1: Rsync project to /opt/bol on server, create virtualenv, install requirements.
3. Configure Services — finish_setup.sh: Creates systemd unit (bol.service), generates secret key, configures Nginx virtual hosts, obtains SSL certificates.
4. Harden Headers — fix_nginx_headers.sh: Applies security headers (CSP, HSTS, X-Frame-Options, etc.) to Nginx config.
5. Verify — Check systemd status, test HTTPS endpoint, verify security headers with browser dev tools.

5.2 Environment Variables

5.3 Infrastructure

6.1 Simulation Thread Model

The simulation runs in a background thread while Flask serves HTTP requests on the main thread. Communication uses shared Python objects with threading locks:

• _sim_lock — Guards access to the Simulation instance, preventing concurrent reads during a step.
• _project_lock — Guards access to project JSON files for atomic read/write operations.
• _bug_lock — Guards access to the bug tracker JSON file.

6.2 Module Dependency Graph

config.py ──────────────────────────────────────────┐
    │                                                │
    ▼                                                │
world.py ───┬──► energy.py                          │
            │                                        │
            ├──► chemistry.py ──► Molecule           │
            │                                        │
            ├──► assembly.py ──► Vesicle, Micelle    │
            │                                        │
            └──► replication.py ──► RNA copying       │
                                                     │
simulation.py ◄── all core modules ◄─────────────────┘
    │
    ▼
metrics.py ──► CSV/JSON export
    │
    ▼
web/server.py ──► Flask routes + REST API
    │
    ▼
ai.py ──► 27 analysis functions

6.3 Data Flow: Browser to Simulation

1. User clicks “Start” on Dashboard → POST /api/start
2. Flask route creates Config + Simulation instance
3. Background thread starts calling sim._step() in a loop
4. Dashboard polls GET /api/state every 1s for live metrics
5. User clicks “Stop” → POST /api/stop sets a flag; thread exits cleanly