Skip to content
artalis-ioPublic

About

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.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

OTTO

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.

Platform Components

Core Engines

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 -

Planned Engines

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)

Quick Start

# 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)

Windows (MSYS2 / UCRT64)

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 test

MSYS2'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 (Production)

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.

Build Modes

Production Build (Default)

make all                  # Build all libraries and tests
make carta velo locus     # Build specific modules

Production 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 in mk/toolchain.mk before 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

Debug Build (with Sanitizers)

make -C velo debug        # Single module with ASan + UBSan
make -C carta debug       # Catches memory errors, UB at runtime

Debug flags include:

  • -g -O0 - Debug symbols, no optimization
  • -fsanitize=address,undefined - AddressSanitizer + UBSan
  • -fno-omit-frame-pointer - Better stack traces

macOS ARM64 Note

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.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  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.

API Examples

# 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}'

Performance

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

Documentation

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

Regenerating API Documentation

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-docs

Building & Serving the Site

The 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 :8000

Structure:

  • site/ - Source files (templates, config, Makefile)
  • site/build/ - Deployable files only (gitignored, auto-generated)

API Audit Tool

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 tests

What it checks:

  • Handler header/implementation exist ({prefix}_api.h, {prefix}_api.c)
  • Handler interface types defined (Context, Request, Response)
  • @api and @demo annotations present in headers
  • WASM wrapper and JS handlers configured
  • Test coverage for each @demo endpoint
  • api.html up-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-docs

Component Documentation

Each component has a CLAUDE.md with API details:

Design Philosophy

  • 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

Transport-Agnostic Architecture

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.

Render Backend Agnostic UI

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.

Defense-in-Depth Security

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.

Requirements

  • 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

License

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

About

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.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages