TBM Configuration Management System

A prototype for managing Tunnel Boring Machine configurations at remote locations. This system handles configuration versioning, approval workflows, and deployment tracking for TBM fleets.

---

Table of Contents

• Features
• Screenshots
• Quick Start
• Usage
• Architecture
• API Reference
• Configuration Format
• Troubleshooting
• Known Limitations
• TODO

---

Features

Configuration Management

• Create, edit, and version configurations
• Approval workflow (Draft -> Approved -> Archived)
• Clone existing configs as starting point
• Compare any two configs side-by-side
• Export as JSON or YAML

Machine Fleet Management

• Real-time online/offline status
• Operational modes: Active, Standby, Maintenance, Decommissioned
• Current configuration version per machine
• Deployment history per machine

Deployment System

• Deploy approved configs to compatible machines
• Real-time deployment status tracking
• Success/failure reporting from machines

Audit and Compliance

• Every action logged with timestamp, user, and details
• Searchable audit log
• Deployment history preserved

---

Screenshots

Dashboard

Fleet overview with real-time machine status, deployment metrics, and recent activity.

Configuration Deployment

Deploy approved configurations to machines with status tracking.

Audit Log

Complete audit trail of all system actions for compliance.

---

Quick Start

Prerequisites

• Python 3.10+
• Node.js 18+
• npm or yarn

Installation

# Clone the repository
cd tbm-config

# Backend setup
cd backend
pip install -r requirements.txt
cp .env.example .env          # Configure credentials
python seed_data.py           # Creates database with sample data

# Frontend setup (new terminal)
cd frontend
npm install

Running

# Terminal 1: Backend API
cd backend
uvicorn main:app --reload
# -> http://localhost:8000

# Terminal 2: Frontend UI
cd frontend
npm run dev
# -> http://localhost:5173

# Terminal 3+: Machine Simulators (optional)
cd simulator
python machine.py PRF4-001
python machine.py PRF4-002  # In another terminal

Test Credentials

Demo credentials are configured in the .env file. A credential helper is available in the Dashboard login screen for testing purposes until production deployment.

---

Usage

Dashboard

The main dashboard shows:

• Fleet Overview - All machines with status and current config
• Summary Stats - Online count, pending deployments, weekly activity
• Alerts Banner - Active machines that are offline
• Recent Activity - Latest actions from audit log

Managing Configurations

1. Create: Click "New Configuration", fill in parameters, save as draft
2. Review: Expand a draft config to see all parameters
3. Approve: Click Approve to make it deployable
4. Reject: Delete drafts you don't want
5. Archive: Retire approved configs (preserves history)
6. Clone: Copy an existing config as starting point
7. Compare: See differences between two configs
8. Export: Download as JSON or YAML

Deploying to Machines

1. Go to Machines page
2. Click Deploy Config on target machine
3. Select an approved configuration
4. Click Deploy
5. Watch for success notification (machine must be online)

Machine Modes

Mode	Meaning	Alerts if Offline?
Active	Should be running	Yes
Standby	Intentionally idle	No
Maintenance	Under repair	No
Decommissioned	Retired	No

---

Architecture

+------------------+     +------------------+     +------------------+
|    Frontend      |---->|    Backend       |---->|    Database      |
|  React + Vite    |     |    FastAPI       |     |     SQLite       |
|  localhost:5173  |     |  localhost:8000  |     |  tbm_config.db   |
+------------------+     +------------------+     +------------------+
                               ^
                               |
                         +-----+-----+
                         | Simulator |
                         |  Python   |
                         | (per TBM) |
                         +-----------+

Data Flow: Deploying a Config

1. User clicks Deploy -> Frontend POST /api/deployments
2. Backend creates deployment (pending), adds to pending_configs
3. Simulator polls -> Backend returns pending config
4. Simulator applies config -> Sends ACK to backend
5. Backend updates deployment (success), updates machine version
6. Frontend polls -> Shows updated status

Project Structure

tbm-config/
├── backend/
│   ├── main.py              # FastAPI application
│   ├── seed_data.py         # Database seeder
│   ├── requirements.txt     # Python dependencies
│   ├── .env.example         # Environment template
│   └── .env                  # Local credentials (git-ignored)
├── frontend/
│   ├── src/
│   │   ├── pages/           # React page components
│   │   ├── components/      # Shared components
│   │   ├── api.ts           # API client
│   │   ├── types.ts         # TypeScript interfaces
│   │   └── store.ts         # Zustand state management
│   ├── package.json
│   └── vite.config.ts
├── simulator/
│   └── machine.py           # Machine simulator
└── docs/
    └── CONFIGURATION_EXAMPLES.md

Tech Stack

Layer	Technology
Backend	FastAPI, SQLite, Python 3.10+
Frontend	React 18, TypeScript, Vite, Tailwind CSS
State	Zustand
Simulator	Python asyncio, httpx

Database Schema

machines (id, name, machine_type, operational_mode, current_version, last_seen)
configurations (id, version, name, machine_type, status, config, created_by, created_at)
deployments (id, config_id, config_version, machine_id, status, initiated_by, initiated_at, completed_at, error)
pending_configs (machine_id, config_id, deployment_id)
audit_logs (id, timestamp, user, action, resource, details)

---

API Reference

Authentication

Method	Endpoint	Description
POST	/api/auth/login	Get auth token
GET	/api/auth/me	Current user info

Machines

Method	Endpoint	Description
GET	/api/machines	List all machines
GET	/api/machines/{id}	Get single machine
PUT	/api/machines/{id}	Update operational mode
GET	/api/machines/{id}/history	Deployment history

Configurations

Method	Endpoint	Description
GET	/api/configs	List (filter by status, type)
POST	/api/configs	Create draft
PUT	/api/configs/{id}	Update draft
PUT	/api/configs/{id}/approve	Approve draft
PUT	/api/configs/{id}/reject	Reject (delete) draft
PUT	/api/configs/{id}/archive	Archive approved
PUT	/api/configs/{id}/unarchive	Restore archived
POST	/api/configs/{id}/clone	Clone to new draft
GET	/api/configs/{id}/export	Export JSON/YAML
GET	/api/configs/diff/{a}/{b}	Compare two configs

Deployments

Method	Endpoint	Description
GET	/api/deployments	List all
POST	/api/deployments	Create (initiate)

Dashboard

Method	Endpoint	Description
GET	/api/dashboard	Fleet overview + metrics

Machine API (Simulator)

Method	Endpoint	Description
POST	/api/machine-api/poll	Machine checks for pending config
POST	/api/machine-api/ack	Machine reports deployment result

---

Configuration Format

See docs/CONFIGURATION_EXAMPLES.md for detailed examples.

Basic structure:

{
  "excavation": {
    "thrust_kn": 18500,
    "cutterhead_rpm": 2.4,
    "penetration_mm_rev": 8,
    "advance_rate_mm_min": 45
  },
  "pressure": {
    "face_pressure_bar": 2.8,
    "min_pressure_bar": 2.4,
    "max_pressure_bar": 3.4
  },
  "safety": {
    "max_thrust_kn": 26000,
    "torque_limit_pct": 85,
    "emergency_stop_enabled": true
  },
  "navigation": {
    "horizontal_tolerance_mm": 50,
    "vertical_tolerance_mm": 40,
    "steering_mode": "semi_auto"
  }
}

Note: Configuration parameters are placeholders. Actual machine parameters will be defined during production integration.

---

Troubleshooting

"Database is locked" error

Multiple simultaneous write operations to SQLite.

# Stop all processes, delete database, restart
del tbm_config.db  # Windows
rm tbm_config.db   # Mac/Linux
python seed_data.py
uvicorn main:app --reload

Machine stuck on "offline"

Is the simulator running for that machine?

python machine.py PRF4-001

Machines go offline 30 seconds after simulator stops.

Deployment stuck on "pending"

Backend terminal should show [ACK] messages when simulator reports success.

Debug:

sqlite3 tbm_config.db "SELECT status FROM deployments ORDER BY initiated_at DESC LIMIT 1;"

Frontend not updating

Check browser console for errors. Network tab should show /api/machines and /api/dashboard requests every 5 seconds.

---

Known Limitations

1. No persistent sessions - Restart server = re-login required
2. No token expiry - Tokens valid until server restart
3. No audit log cleanup - Grows indefinitely
4. No database backup system
5. No HTTPS - Development only
6. No user management UI - Users configured via environment variables

---

TODO

High Priority - Security

• Implement password hashing (bcrypt/Argon2)
• Add JWT tokens with expiration
• Authenticate machine API endpoints (certificates or API keys)
• Implement role-based access control (RBAC) - roles exist but not enforced
• Enable HTTPS/TLS for production

Medium Priority - Security

• Encrypt database at rest
• Move token storage from localStorage (XSS vulnerable) to httpOnly cookies
• Add input validation/sanitization on all endpoints
• Implement rate limiting
• Restrict CORS methods/headers (currently wildcards)
• Add audit log retention policy

Features

• Switch from polling to WebSocket for real-time updates
• Config import (upload JSON/YAML)
• User management UI
• Database migrations system
• Docker containerization
• Production deployment guide

Technical Debt

• Modularize backend (currently single file)
• Remove technical internals from documentation for production
• Database backup strategy
• Comprehensive error handling

---

Author

Zack