BOL System Architecture Document

1.1 Purpose

This document describes the system architecture of BOL (Beginning of Life), a full-stack Python application that simulates prebiotic chemistry and the emergence of the first protocells. It covers the deployment topology, component interactions, security architecture, data flow, technology stack, and operational procedures.

1.2 System Context

BOL operates as a single-server web application serving a browser-based dashboard. The system has no external database dependencies — all persistent data is stored as JSON files on the local filesystem. The simulation engine runs in-process alongside the web server.

1.3 Key Characteristics

• Self-contained — No external databases, message queues, or microservices.
• Single-process — Flask app + simulation thread in one Python process (Gunicorn multi-worker in production).
• File-based persistence — JSON files for users, projects, scenarios, training, and bugs.
• Real-time — Polling-based live updates from running simulation to browser.

2.1 Production Architecture

  ┌───────────────────────────────────────────────────────┐
  │                  Client (Browser / PWA)                │
  │   • Dashboard, Microscope, AI Lab, Projects, etc.     │
  │   • Chart.js, Three.js, vanilla JS                    │
  └──────────────────────┬────────────────────────────────┘
                         │ HTTPS (443)
  ┌──────────────────────▼────────────────────────────────┐
  │              Nginx Reverse Proxy                       │
  │   • SSL termination (Let's Encrypt)                   │
  │   • bol.drel.us → 127.0.0.1:5000                     │
  │   • drel.us → static HTML landing page                │
  │   • Security headers (CSP, HSTS, X-Frame-Options)     │
  │   • Static file serving (/static/ → /opt/bol/...)     │
  │   • 10 MB upload limit                                │
  └──────────────────────┬────────────────────────────────┘
                         │ HTTP (5000, localhost only)
  ┌──────────────────────▼────────────────────────────────┐
  │         Gunicorn WSGI Server                           │
  │   • 3 worker processes                                │
  │   • 120-second request timeout                        │
  │   • Managed by systemd (bol.service)                  │
  │   • Auto-restart on failure (RestartSec=5)            │
  └──────────────────────┬────────────────────────────────┘
                         │
  ┌──────────────────────▼────────────────────────────────┐
  │         Flask Application (bol.web.server)             │
  │   • Page routes (30+ HTML templates)                  │
  │   • REST API endpoints (40+ routes)                   │
  │   • Authentication & session management               │
  │   • Security middleware (headers, rate limiting)       │
  │   • PDF document generation                           │
  ├───────────────────────────────────────────────────────┤
  │         Simulation Engine (background thread)          │
  │   • Stochastic chemistry (27 reactions)               │
  │   • Self-assembly (micelles → vesicles)               │
  │   • RNA replication with mutations                    │
  │   • Metrics collection & export                       │
  ├───────────────────────────────────────────────────────┤
  │         File System Storage                            │
  │   • profiles/*.json    (user accounts)                │
  │   • projects/*.json    (experiment projects)          │
  │   • scenarios/*.json   (4 preset scenarios)           │
  │   • training/modules.json (curriculum)                │
  │   • bugs/bugs.json     (bug tracker)                  │
  │   • .secret_key        (session signing key)          │
  │   • output/            (CSV/JSON exports)             │
  └───────────────────────────────────────────────────────┘

  Target: GCP Compute Engine (e2-small, Ubuntu 24.04 LTS)
  Domains: drel.us (landing), bol.drel.us (app)

2.2 Local Development

  Browser ──► http://127.0.0.1:5000 ──► Flask dev server (single thread)
                                        │
                                        ├── Simulation (background thread)
                                        └── File system (profiles/, projects/, etc.)

Local mode differences: no Nginx, no SSL, no Gunicorn, SESSION_COOKIE_SECURE=False.

2.3 Network Configuration

3.1 NIST SP 800-53 Control Mapping

3.2 CISA Compliance

3.3 Security Headers

Applied by both Flask middleware (@app.after_request) and Nginx:

3.4 Authentication & Session Security

• Password storage — PBKDF2-HMAC-SHA256, 260,000 iterations, 32-byte random salt per user.
• Password policy — Minimum 8 characters; must contain uppercase letter, lowercase letter, and digit.
• Session cookies — HttpOnly (no JS access), SameSite=Lax (CSRF mitigation), Secure (production only).
• Session lifetime — 8-hour expiry with PERMANENT_SESSION_LIFETIME.
• Secret key persistence — Session signing key stored in .secret_key file (gitignored); sessions survive server restarts.
• Timing-safe comparison — secrets.compare_digest() for password verification prevents timing attacks.

3.5 Input Validation & Output Encoding

• Server-side — Usernames validated against [a-zA-Z0-9_-] allowlist. Project IDs, lesson IDs, and filenames sanitised before filesystem access. JSON request bodies parsed with schema validation.
• Template engine — Jinja2 auto-escaping enabled globally. No |safe filter usage in templates.
• Client-side — escHtml() / _esc() helper functions and textContent used for safe DOM updates. All user-supplied strings escaped before insertion.
• Command injection prevention — shlex.split() with shell=False for subprocess execution. URL scheme validation (HTTP/HTTPS only) prevents SSRF.

4.1 Backend

4.2 Frontend

4.3 Infrastructure

5.1 Request/Response Flow

  Browser ──HTTPS──► Nginx ──HTTP──► Gunicorn ──► Flask Route
                                                    │
                                        ┌───────────┴───────────┐
                                        ▼                       ▼
                                   Page Route              API Route
                                   (Jinja2 → HTML)        (→ JSON)
                                                              │
                                                    ┌─────────┴────────┐
                                                    ▼                  ▼
                                              Read/Write          Simulation
                                              JSON files          state query

5.2 Simulation Data Flow

  Config ──► Simulation.init()
                 │
         ┌───────┴──────────────────────────────────────┐
         │  Step Loop (background thread)                │
         │  ┌─────────────────────────────────────────┐  │
         │  │  1. world.diffuse(molecules)            │  │
         │  │  2. energy.update(world)                │  │
         │  │  3. chemistry.react(molecules, world)   │  │
         │  │  4. assembly.step(molecules, world)     │  │
         │  │  5. replication.step(molecules, world)  │  │
         │  │  6. metrics.compute(molecules, ...)     │  │
         │  └─────────────────────────────────────────┘  │
         │                     │                         │
         │              metrics_history[]                 │
         └───────────────────┬──────────────────────────┘
                             │
                     ┌───────┴──────────┐
                     ▼                  ▼
              GET /api/state      GET /api/history
              (latest record)     (time series)

5.3 Authentication Flow

1. POST /api/profile/login with {"username": "...", "password": "..."}
2. Server checks rate limit (IP-based, 10/5min window)
3. Server loads profile JSON, computes PBKDF2 hash with stored salt
4. Timing-safe comparison with stored hash (secrets.compare_digest)
5. On success: set session["username"], session.permanent = True, return 200
6. On failure: return 401 with generic error message, record attempt

6.1 Service Management

# Check service status
sudo systemctl status bol

# Restart the application
sudo systemctl restart bol

# View application logs
sudo journalctl -u bol -f
tail -f /var/log/bol-access.log
tail -f /var/log/bol-error.log

# Check Nginx
sudo nginx -t
sudo systemctl reload nginx

6.2 Deployment Update Procedure

1. Run tests locally: python -m pytest tests/ -v
2. Deploy to server: .\deploy\deploy_to_server.ps1
3. SSH to server and restart service: sudo systemctl restart bol
4. Verify HTTPS endpoint is responding
5. Check logs for errors: sudo journalctl -u bol --since "5 minutes ago"

6.3 SSL Certificate Renewal

Certbot is configured for automatic renewal via cron/systemd timer. Manual renewal:

sudo certbot renew --dry-run    # Test renewal
sudo certbot renew              # Actual renewal

6.4 Backup Strategy

• Code — Git repository; deploy from local machine via rsync.
• User data — profiles/, projects/, bugs/, training/ directories. Should be backed up periodically.
• Secret key — .secret_key file. Loss invalidates all active sessions (users must re-login).

6.5 Monitoring

• Uptime — systemd auto-restart with RestartSec=5 recovers from crashes within seconds.
• Access logging — Gunicorn access log at /var/log/bol-access.log.
• Error logging — Gunicorn error log at /var/log/bol-error.log.
• Firewall — ufw allows only ports 22, 80, 443; all others denied by default.

7.1 Current Capacity

• Concurrent users — Gunicorn’s 3 workers can serve ~50 concurrent browser sessions.
• Simulation size — Up to ~10,000 molecules per simulation with acceptable step latency.
• Storage — JSON files are lightweight; thousands of projects and profiles feasible on SSD.

7.2 Scaling Options

• Vertical — Upgrade to larger GCP instance (e2-medium or e2-standard) for more CPU/RAM.
• Worker processes — Increase Gunicorn workers (currently 3) to match available CPU cores.
• Database migration — If file-based storage becomes a bottleneck, migrate to SQLite or PostgreSQL.
• CDN — Serve static assets via CloudFlare or GCP Cloud CDN for global performance.