VEDS - Voyage Enterprise Decision System

image:[Palimpsest-MPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"]

A multimodal transport optimization platform with formal verification

Compete with Infor. Built for cooperative economics.

---

Overview

What is VEDS?

VEDS optimizes cargo movement across maritime, rail, road, and air simultaneously, considering:

• Cost - Minimize shipping expenses

• Carbon - Track and optimize environmental impact

• Time - Meet delivery windows

• Labor - Ensure fair wages and working conditions (ILO standards)

Unlike traditional TMS platforms, VEDS provides mathematically proven guarantees that routes satisfy constraints.

Key Features

Feature	Description
Multi-Modal Routing	Optimize across ship, train, truck, plane
Formal Verification	Ada/SPARK proofs guarantee constraint satisfaction
Bitemporal Audit	XTDB tracks "what we knew when" for compliance
Labor Ethics	Built-in ILO minimum wage and hours constraints
Carbon Optimization	First-class environmental objective
Real-Time Tracking	Sub-100ms position updates via Phoenix Channels
VoID/Linked Data	SPARQL endpoint for data federation
Julia Visualization	Publication-quality analytics with Makie.jl

Architecture

┌────────────────────────────────────────────────────────────────────┐
│                           VEDS                                     │
├────────────────────────────────────────────────────────────────────┤
│  Phoenix LiveView │ Julia/Genie.jl │ Pluto.jl    ← Presentation   │
├────────────────────────────────────────────────────────────────────┤
│              Elixir/Phoenix API Gateway                ← API       │
├────────────────────────────────────────────────────────────────────┤
│  Rust        │ Clojure    │ Ada/SPARK    │ Elixir     ← Domain    │
│  (Optimizer) │ (Datalog)  │ (Proofs)     │ (Tracking)             │
├────────────────────────────────────────────────────────────────────┤
│       XTDB        │    SurrealDB    │    Dragonfly   ← Data       │
│    (Bitemporal)   │   (Graph/Doc)   │     (Cache)                 │
└────────────────────────────────────────────────────────────────────┘

Technology Stack

Layer	Technology	Purpose
API	Elixir/Phoenix	REST, GraphQL, WebSocket
Routing	Rust	High-performance path optimization
Constraints	Clojure + XTDB	Datalog rules, bitemporal storage
Verification	Ada/SPARK	Formal proofs (Z3/CVC5)
Tracking	Elixir + Dragonfly	Real-time position handling
Analytics	Julia + Makie.jl	Interactive visualization
Graph/Doc	SurrealDB	Transport network, shipments
Cache	Dragonfly	Hot data, geo-indexing

Quick Start

Prerequisites

• Docker and Docker Compose

• Rust toolchain

• Elixir 1.15+

• Julia 1.9+

• Clojure CLI

Installation

# Clone repository
git clone https://github.com/hyperpolymath/voyage-enterprise-decision-system.git
cd voyage-enterprise-decision-system

# Start databases
docker-compose up -d xtdb surrealdb dragonfly

Running Services

Start each service in a separate terminal:

# Rust routing engine
cd src/rust-routing && cargo run

# Elixir API server
cd src/elixir-api && mix phx.server

# Clojure constraints engine
cd src/clojure-constraints && clj -M:run

# Julia visualization dashboard
cd src/julia-viz && julia --project=. -e "using VEDS; VEDS.start_dashboard()"

Access Points

URL	Service
http://localhost:4000	API + Dashboard
http://localhost:8081	Analytics Dashboard

API Reference

Create Shipment

curl -X POST http://localhost:4000/api/v1/shipments \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "CNSHA",
    "destination": "GBLHR",
    "weight_kg": 10000,
    "deliver_by": "2025-12-15T00:00:00Z",
    "constraints": {
      "max_carbon_kg": 5000,
      "min_labor_score": 0.8
    }
  }'

Get Optimized Routes

curl http://localhost:4000/api/v1/shipments/{id}/routes

Track Shipment (WebSocket)

wscat -c ws://localhost:4000/socket/tracking?shipment_id={id}

Documentation

Architecture

• Tech Stack - Complete technology decisions

Design Documents

• DFD Level 0 - System context diagram

• DFD Level 1 - Major processes

• DFD Level 2 - Sub-processes

• DFD Level 3 - Detailed data flows

• ER Diagram - Entity relationships

• UML Diagrams - Use cases, sequences, states

• Julia Viz - Visualization architecture

Vocabularies

• VoID Mapping - Linked data vocabulary

Roadmap

Phase 1: MVP (Current)

• ✓ Design documentation

• ❏ Database schemas

• ❏ Basic routing engine

• ❏ API skeleton

• ❏ Constraint DSL

Phase 2: Core Features

• ❏ Formal verification integration

• ❏ Real-time tracking

• ❏ Julia dashboards

• ❏ VoID/SPARQL endpoint

Phase 3: Production

• ❏ Transport API integrations

• ❏ Carbon accounting

• ❏ Labor compliance reporting

• ❏ Kubernetes deployment

Contributing

1. Read the design docs first

2. Open an issue for discussion

3. Submit PR against develop branch

4. Ensure formal proofs pass (for constraint changes)

See CONTRIBUTING.md for detailed guidelines.

License

This project is licensed under the Mozilla Public License, v. 2.0. See the LICENSE file for details.

SPDX-License-Identifier: CC-BY-SA-4.0

Credits

Concept & Architecture	Jonathan D.A. Jewell
Initial Design	Claude (Anthropic)
Year	2025

---

Built with cooperative economics in mind. Workers deserve fair treatment.

Architecture

See TOPOLOGY.md for a visual architecture map and completion dashboard.