Optimization for Trucking and Transport Operations
A comprehensive trucking and logistics optimization platform combining route planning, fuel cost minimization, Hours of Service compliance, fleet scheduling, and custom map rendering. Built entirely in C with zero external dependencies, designed for native and WebAssembly deployment.
| Component | Description | Port |
|---|---|---|
| Ralph | Zero-dependency LP/MIP solver (Revised Simplex, Branch & Bound) | - |
| Velo | OSM routing engine (Dijkstra, A*, bidirectional, landmarks) | 8082 |
| Carta | Map tile generator (MVT vector, PNG raster) | 8081 |
| Locus | OSM geocoding (forward search, autocomplete, reverse lookup) | 8083 |
| FuelWise | Refueling optimization library | 8080 |
| ClayShards | Immediate mode UI components (WebGL, TUI renderers) | - |
| Shared | Common utilities: geo, protobuf, zlib, rate limiting | - |
| Component | Description |
|---|---|
| Fuse | State integrity (Fleet Unified Signal and Estimation) - multi-source fusion, vehicle identity, confidence-weighted geofencing |
| HoSE | Hours of Service (Hours of Service Engine) - FMCSA/EC561 |
| Tempo | Time windows and business rules (Time-window and Event Management Policy Orchestrator) |
| Arbor | State-space search engine (Algorithmic Recursive Branching and Optimization Runtime) |
| Surge | Rich VRP/PDPTW solver (Scheduler for Urban Routing and General Express) - now shipping with the unified stop-state kernel that drives VRPTW and PDPTW benchmarks, feeding the Li & Lim 100-task workload. |
| Sigma | Fleet plan selection via MIP (Selection and Integration for Global Multi-assignment Allocation) |
| Pulse | Execution tracker / PTA engine (Plan Utilization and Live State Estimator) |
| Forge | Async job queue (Flexible Orchestration and Runtime for General Execution) |
| Apex | Pre-computation engine (Asynchronous Pre-computation Execution) - tiles, routes, cache |
| Nexus | TMS/ELD/LoadBoard integration gateway (Normalized External Unified Snapshots) |
| Iris | LLM natural language interface (Intelligent Request Interpretation System) |
| Quota | Pricing engine (Quote Underwriting and Tariff Optimization Algorithm) |
| Atlas | Network design (Allocation and Tactical Lane Analysis System) |
# Build everything
make all
# Run tests (~1500 tests)
make test
# Start API servers
./carta/api/carta-tile-server data/hungary-latest.osm.pbf # Tiles on :8081
./velo/api/velo-route-server data/hungary-latest.osm.pbf # Routes on :8082
./locus/api/locus-geocoder data/hungary-latest.osm.pbf # Geocoding on :8083
./fuelwise/api/fuelwise-api # Optimization on :8080
# Download OSM data
./scripts/data-download-osm.sh hungary # ~300MB
./scripts/data-download-osm.sh monaco # ~1MB (for testing)Build with mingw32-make, not make:
pacman -S mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-make
mingw32-make all
mingw32-make testMSYS2's /usr/bin/make clears TMPDIR, TMP and TEMP from the recipe
environment. GCC then falls back to C:\WINDOWS, cannot write there, and the
build dies on the first source file:
Cannot create temporary file in C:\WINDOWS\: Permission denied
make[1]: *** [Makefile:127: src/sh_pal_posix.o] Error 127
That is the environment, not the tree. Exporting the variables does not help,
because make strips them; mingw32-make passes them through. CI does not hit
this because msys2/setup-msys2 provides a shell that sets them itself.
docker-compose up # Full platform
docker-compose up carta velo locus # GIS services only
# Or build individual images
docker build -f docker/Dockerfile.carta -t otto-carta .
docker build -f docker/Dockerfile.velo -t otto-velo .See docker/README.md for data management and security options.
make all # Build all libraries and tests
make carta velo locus # Build specific modulesProduction flags include:
-O3 -march=native- Full optimization-ffp-contract=off, and no-ffast-math- IEEE arithmetic, identically on every CPU. This is deliberate and load-bearing: with fast math the solver took a different path per machine and failed to terminate at all on some, and removing it cost nothing measurable (2.4% faster across the NETLIB regression set). See the FP block inmk/toolchain.mkbefore changing it.-fstack-protector-strong- Stack buffer overflow protection-D_FORTIFY_SOURCE=2- Buffer overflow detection-fPIE+-pie(Linux) - Position independent executables-Wl,-z,relro,-z,now(Linux) - Full RELRO
make -C velo debug # Single module with ASan + UBSan
make -C carta debug # Catches memory errors, UB at runtimeDebug flags include:
-g -O0- Debug symbols, no optimization-fsanitize=address,undefined- AddressSanitizer + UBSan-fno-omit-frame-pointer- Better stack traces
Velo uses OpenMP for parallel landmark computation. On macOS ARM64 with Homebrew's libomp, you may see linker errors:
# If OpenMP linking fails on macOS:
make -C velo NOMP=1 # Build without OpenMP (slightly slower landmarks)This is not needed for Docker builds (Linux) or Intel Macs.
┌─────────────────────────────────────────────────────────────────┐
│ Applications: React UI / WASM (Browser) / REST APIs / CLI │
├─────────────────────────────────────────────────────────────────┤
│ Fleet Optimization [Planned]: HoSE, Tempo, Arbor, Surge, Sigma, Pulse │
│ Network Analysis [Planned]: Atlas, Quota │
├─────────────────────────────────────────────────────────────────┤
│ State Integrity [Planned]: Fuse (signal fusion, geofencing) │
├─────────────────────────────────────────────────────────────────┤
│ Domain Libraries: FuelWise, Velo, Carta, Locus │
├─────────────────────────────────────────────────────────────────┤
│ Core: Ralph (LP/MIP) │ Shared (geo, protobuf, rate limiting) │
├─────────────────────────────────────────────────────────────────┤
│ Vendor: miniz (zlib) │ Keel (HTTP) │ Clay (UI layout) │
└─────────────────────────────────────────────────────────────────┘
Fuse is the state integrity layer that provides confidence-weighted vehicle positions to all other engines. Geofencing, detention tracking, and ETA stability all depend on Fuse's unified reality model.
# Route calculation
curl 'http://localhost:8082/api/v1/route?from=47.5,19.0&to=46.2,20.1&profile=truck'
# Map tile
curl 'http://localhost:8081/tiles/14/9058/5729.png' -o tile.png
# Geocoding
curl 'http://localhost:8083/api/v1/search?q=Budapest'
# Refueling optimization
curl -X POST http://localhost:8080/api/v1/optimize \
-H "Content-Type: application/json" \
-d '{"stations":[...],"route":[...],"tank_capacity":300}'| Operation | Time | Notes |
|---|---|---|
| LP solve (1000 vars) | <100ms | Ralph simplex |
| Route (country-scale) | <100ms | Velo A* + landmarks |
| PNG tile (512x512) | ~75ms | Carta rasterizer |
| Geocoding | <20µs | Locus trie + ngram |
| PBF parse (Hungary) | ~10s | 300MB, 35M nodes |
| Document | Purpose |
|---|---|
| CLAUDE.md | Development guide and patterns |
| docs/ARCHITECTURE.md | System architecture, layers, data flow |
| docs/MANIFESTO.md | Design philosophy (C, WASM, transport-agnostic) |
| docs/internals/security-model.md | Security architecture, role separation, hardening |
| docs/business/ | Strategy, valuation |
| docs/roadmaps/ | Active development roadmaps (15 components) |
| site/api.html | Interactive API docs with WASM demos |
The API documentation (site/api.html) is generated from C header annotations and includes live WASM demos. It auto-rebuilds when sources change:
make api-docs # Generate site/api.html (rebuilds dependencies as needed)
make api-docs-check # Verify docs are up-to-date (for CI)Dependency chain (all automatic):
data/monaco-latest.osm.pbf → data/monaco.vlg → WASM demos → site/api.html
↓ ↓ ↓
(downloads if missing) (rebuilds if velo/ changes) (copies to site/js/)
To force a full rebuild:
rm -f data/monaco.vlg velo/wasm/src/monaco_vlg.h carta/wasm/src/monaco_pbf.h
make api-docsThe site/ directory contains source files. Deployable files are built into site/build/:
make site-build # Build site/build/ (only deployable files)
make site-serve # Build and serve on :8000Structure:
site/- Source files (templates, config, Makefile)site/build/- Deployable files only (gitignored, auto-generated)
Automated validation of API modules for compliance with the transport-agnostic manifesto:
./scripts/api-audit.sh velo # Audit single module
./scripts/api-audit.sh all # Audit all modules
./scripts/api-audit.sh all --test # Also run WASM demo testsWhat it checks:
- Handler header/implementation exist (
{prefix}_api.h,{prefix}_api.c) - Handler interface types defined (Context, Request, Response)
@apiand@demoannotations present in headers- WASM wrapper and JS handlers configured
- Test coverage for each
@demoendpoint api.htmlup-to-date status
# First-time setup for WASM tests
make test-api-docs-install
# Run WASM demo tests (rebuilds api.html if needed)
make test-api-docsEach component has a CLAUDE.md with API details:
- Zero Dependencies - Core libraries use only standard C
- WASM-First - All components compile to WebAssembly (50-150KB)
- Transport-Agnostic APIs - Core is pure C functions; HTTP/WASM/embedded are thin wrappers
- C11 - Compound literals, designated initializers, no runtime overhead
- Arena Allocators - Bulk alloc, bulk free, no fragmentation
- Immediate Mode UI - No retained state, deterministic rendering
Every OTTO API is fundamentally a pure C function:
int carta_render_tile(int z, int x, int y, uint8_t **out, size_t *len);
int vl_route(VLGraph *g, int from, int to, VLRoute *route);HTTP (Keel) and WASM (Emscripten) are just thin wrappers (~10 lines each) over the same core. This means:
- The demo IS the product - Browser WASM demos run the actual algorithms
- Zero-infrastructure evaluation - Send a single HTML file, no server needed
- Edge-ready by design - If it runs in WASM, it runs anywhere
See docs/MANIFESTO.md for the full manifesto.
ClayShards applies the same philosophy to the frontend. UI code produces render commands—WebGL, TUI terminal, OpenGL ES are thin renderers over the same component code:
// Hybrid design: declarative layout (Clay) + imperative interaction (ClayShards)
CLAY(CLAY_ID("Panel"), CLAY_LAYOUT(.padding = {16, 16, 16, 16})) {
if (cs_button(CS_ID("submit"), "Submit", NULL).clicked) {
handle_submit(); // Immediate mode: if clicked, react now
}
}
// Layout answers "where and how big?" — Components answer "what does it do?"- Declarative layout - Clay handles sizing, padding, flex layouts
- Imperative interaction - Immediate mode widgets respond to input inline
- Render commands as contract - UI produces commands; renderers consume them
- TUI as strictest target - If it works in terminal, it works everywhere
See clayshards/clay-shards/MANIFESTO.md for ClayShards-specific details.
OTTO implements role-based privilege separation with three deployment modes:
- In-process (default) - Worker threads via
sh_worker_pool, systemd hardening - WASM (demos/edge) - Parsing + compute bundled in WASM sandbox
- Process pool (high-security) - Long-lived parser processes with seccomp/pledge
The same *_api_handle() interface works identically in all modes. No system(), exec*(), popen(), dlopen(). OSM parsing is offline-only—derived indexes are mmap'd read-only.
See docs/internals/security-model.md for the full security architecture.
- Build: GCC/Clang (C11), GNU Make
- Windows: MSYS2 UCRT64 (
mingw32-make, see Windows) - WASM: Emscripten (optional)
- UI: Node.js 20+ (optional)
- Maps: OSM PBF files from Geofabrik
Dual-licensed: AGPLv3 + Commercial License with Trucking Exception.
- Trucking companies: Free forever (owner-operators to mega-fleets)
- SaaS vendors: Commercial license required
See LICENSE for details.
OTTO - Optimization for Trucking and Transport Operations