Skip to content

Commit 58182ee

Browse files
Jonathan D.A. Jewellclaude
Jonathan D.A. Jewell
and
claude
committed
fix: Restore original README content
The previous RSR standardization commit accidentally replaced the full README content with a minimal template. This restores the original project documentation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 7b83d13 commit 58182ee

1 file changed

Lines changed: 173 additions & 55 deletions

File tree

‎README.adoc‎

Lines changed: 173 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,194 @@
1-
= Voyage-Enterprise-Decision-System
2-
Jonathan D.A. Jewell <jonathan.jewell@gmail.com>
3-
:toc: macro
4-
:icons: font
5-
:source-highlighter: rouge
6-
:experimental:
7-
:url-github: https://github.com/hyperpolymath/Voyage-Enterprise-Decision-System
8-
:url-gitlab: https://gitlab.com/hyperpolymath/Voyage-Enterprise-Decision-System
9-
:url-bitbucket: https://bitbucket.org/hyperpolymath/Voyage-Enterprise-Decision-System
10-
:url-codeberg: https://codeberg.org/hyperpolymath/Voyage-Enterprise-Decision-System
1+
= VEDS - Voyage Enterprise Decision System
112

12-
Enterprise voyage optimization with formal verification
3+
*A multimodal transport optimization platform with formal verification*
4+
5+
Compete with Infor. Built for cooperative economics.
6+
7+
---
8+
9+
== What is VEDS?
1310

14-
image:https://img.shields.io/badge/RSR-Certified-gold[RSR Certified]
15-
image:https://img.shields.io/badge/License-AGPL%20v3-blue[License]
11+
VEDS optimizes cargo movement across *maritime, rail, road, and air* simultaneously, considering:
1612

17-
toc::[]
13+
- *Cost* - Minimize shipping expenses
14+
- *Carbon* - Track and optimize environmental impact
15+
- *Time* - Meet delivery windows
16+
- *Labor* - Ensure fair wages and working conditions (ILO standards)
17+
18+
Unlike traditional TMS platforms, VEDS provides *mathematically proven* guarantees that routes satisfy constraints.
19+
20+
---
21+
22+
== Architecture
23+
24+
```
25+
┌────────────────────────────────────────────────────────────────────┐
26+
│ VEDS │
27+
├────────────────────────────────────────────────────────────────────┤
28+
│ Phoenix LiveView │ Julia/Genie.jl │ Pluto.jl ← Presentation │
29+
├────────────────────────────────────────────────────────────────────┤
30+
│ Elixir/Phoenix API Gateway ← API │
31+
├────────────────────────────────────────────────────────────────────┤
32+
│ Rust │ Clojure │ Ada/SPARK │ Elixir ← Domain │
33+
│ (Optimizer) │ (Datalog) │ (Proofs) │ (Tracking) │
34+
├────────────────────────────────────────────────────────────────────┤
35+
│ XTDB │ SurrealDB │ Dragonfly ← Data │
36+
│ (Bitemporal) │ (Graph/Doc) │ (Cache) │
37+
└────────────────────────────────────────────────────────────────────┘
38+
```
39+
40+
---
41+
42+
== Key Features
43+
44+
| Feature | Description |
45+
|---------|-------------|
46+
| *Multi-Modal Routing* | Optimize across ship, train, truck, plane |
47+
| *Formal Verification* | Ada/SPARK proofs guarantee constraint satisfaction |
48+
| *Bitemporal Audit* | XTDB tracks "what we knew when" for compliance |
49+
| *Labor Ethics* | Built-in ILO minimum wage and hours constraints |
50+
| *Carbon Optimization* | First-class environmental objective |
51+
| *Real-Time Tracking* | Sub-100ms position updates via Phoenix Channels |
52+
| *VoID/Linked Data* | SPARQL endpoint for data federation |
53+
| *Julia Visualization* | Publication-quality analytics with Makie.jl |
54+
55+
---
56+
57+
== Technology Stack
58+
59+
| Layer | Technology | Purpose |
60+
|-------|------------|---------|
61+
| API | Elixir/Phoenix | REST, GraphQL, WebSocket |
62+
| Routing | Rust | High-performance path optimization |
63+
| Constraints | Clojure + XTDB | Datalog rules, bitemporal storage |
64+
| Verification | Ada/SPARK | Formal proofs (Z3/CVC5) |
65+
| Tracking | Elixir + Dragonfly | Real-time position handling |
66+
| Analytics | Julia + Makie.jl | Interactive visualization |
67+
| Graph/Doc | SurrealDB | Transport network, shipments |
68+
| Cache | Dragonfly | Hot data, geo-indexing |
69+
70+
---
71+
72+
== Quick Start
73+
74+
```bash
75+
= Clone repository
76+
git clone https://github.com/your-org/veds.git
77+
cd veds
78+
79+
= Start databases
80+
docker-compose up -d xtdb surrealdb dragonfly
81+
82+
= Run services (in separate terminals)
83+
cd src/rust-routing && cargo run
84+
cd src/elixir-api && mix phx.server
85+
cd src/clojure-constraints && clj -M:run
86+
cd src/julia-viz && julia --project=. -e "using VEDS; VEDS.start_dashboard()"
87+
88+
= Access
89+
open http://localhost:4000 # API + Dashboard
90+
open http://localhost:8081 # Analytics
91+
```
92+
93+
---
94+
95+
== Documentation
96+
97+
| Document | Description |
98+
|----------|-------------|
99+
| [Tech Stack](docs/architecture/TECH-STACK.md) | Complete technology decisions |
100+
| [DFD Level 0](docs/design/DFD-LEVEL-0-CONTEXT.md) | System context diagram |
101+
| [DFD Level 1](docs/design/DFD-LEVEL-1-MAJOR-PROCESSES.md) | Major processes |
102+
| [DFD Level 2](docs/design/DFD-LEVEL-2-SUBPROCESSES.md) | Sub-processes |
103+
| [DFD Level 3](docs/design/DFD-LEVEL-3-DETAILED.md) | Detailed data flows |
104+
| [ER Diagram](docs/design/ER-DIAGRAM.md) | Entity relationships |
105+
| [UML Diagrams](docs/design/UML-DIAGRAMS.md) | Use cases, sequences, states |
106+
| [Julia Viz](docs/design/JULIA-VISUALIZATION.md) | Visualization architecture |
107+
| [VoID Mapping](docs/vocab/VOID-MAPPING.md) | Linked data vocabulary |
108+
109+
---
110+
111+
== API Example
112+
113+
```bash
114+
= Create shipment
115+
curl -X POST http://localhost:4000/api/v1/shipments \
116+
-H "Content-Type: application/json" \
117+
-d '{
118+
"origin": "CNSHA",
119+
"destination": "GBLHR",
120+
"weight_kg": 10000,
121+
"deliver_by": "2025-12-15T00:00:00Z",
122+
"constraints": {
123+
"max_carbon_kg": 5000,
124+
"min_labor_score": 0.8
125+
}
126+
}'
127+
128+
= Get optimized routes
129+
curl http://localhost:4000/api/v1/shipments/{id}/routes
130+
131+
= Track shipment (WebSocket)
132+
wscat -c ws://localhost:4000/socket/tracking?shipment_id={id}
133+
```
134+
135+
---
18136

19-
== Overview
137+
== License
20138

21-
Voyage-Enterprise-Decision-System is part of the link:https://rhodium.sh[Rhodium Standard] (RSR) ecosystem.
139+
Dual-licensed under your choice of:
22140

23-
Domain: *logistics*
141+
- *MIT License* - Maximum permissiveness
142+
- *AGPL-3.0* - Copyleft protection
24143

25-
== Installation
144+
Plus the *Palimpsest Philosophical Overlay* encouraging:
145+
- Cooperative economics
146+
- Environmental responsibility
147+
- Knowledge sharing
148+
- Worker solidarity
26149

27-
[source,bash]
28-
----
29-
# Clone from GitHub (primary)
30-
git clone {url-github}
150+
See [LICENSE](LICENSE) for details.
31151

32-
# Or from mirrors
33-
git clone {url-gitlab}
34-
git clone {url-codeberg}
35-
----
152+
---
36153

37-
== RSR Stack
154+
== Contributing
38155

39-
This project follows RSR conventions:
156+
1. Read the design docs first
157+
2. Open an issue for discussion
158+
3. Submit PR against `develop` branch
159+
4. Ensure formal proofs pass (for constraint changes)
40160

41-
* ✅ ReScript for frontend/logic
42-
* ✅ Deno for JS runtime
43-
* ✅ WASM for performance-critical code
44-
* ✅ Rust/OCaml/Haskell for systems/proofs
45-
* ✅ Guile/Scheme for configuration
46-
* ❌ No TypeScript
47-
* ❌ No Go
48-
* ❌ No npm
161+
---
49162

50-
== Mirrors
163+
== Roadmap
51164

52-
[cols="1,2"]
53-
|===
54-
| Platform | URL
165+
=== Phase 1: MVP (Current)
166+
- [x] Design documentation
167+
- [ ] Database schemas
168+
- [ ] Basic routing engine
169+
- [ ] API skeleton
170+
- [ ] Constraint DSL
55171

56-
| GitHub (primary) | {url-github}
57-
| GitLab | {url-gitlab}
58-
| Bitbucket | {url-bitbucket}
59-
| Codeberg | {url-codeberg}
60-
|===
172+
=== Phase 2: Core Features
173+
- [ ] Formal verification integration
174+
- [ ] Real-time tracking
175+
- [ ] Julia dashboards
176+
- [ ] VoID/SPARQL endpoint
61177

62-
== License
178+
=== Phase 3: Production
179+
- [ ] Transport API integrations
180+
- [ ] Carbon accounting
181+
- [ ] Labor compliance reporting
182+
- [ ] Kubernetes deployment
63183

64-
Licensed under AGPL-3.0-or-later OR LicenseRef-Palimpsest-0.5.
184+
---
65185

66-
See link:LICENSE[LICENSE] for details.
67-
68-
== Contributing
186+
== Credits
69187

70-
See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc].
188+
*Concept & Architecture:* Jonathan D.A. Jewell
189+
*Initial Design:* Claude (Anthropic)
190+
*Year:* 2025
71191

72-
== Metadata
192+
---
73193

74-
* Domain: logistics
75-
* Framework: RSR (Rhodium Standard Repository)
76-
* Dublin Core: link:.well-known/dc.xml[.well-known/dc.xml]
194+
*Built with cooperative economics in mind. Workers deserve fair treatment.*

0 commit comments

Comments
 (0)