You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This project is a freight trading simulation that models the buying, selling, and assignment of cargo (loads) to transport capacity (trucks) across cities in the U.S. It provides an interactive map-based dashboard where users can initialize fleets, create new loads, and watch dynamic assignments in real-time, reflecting simplified freight market operations.
5
+
This project is a freight trading simulator I built for OwlHacks 2025. The idea is to mimic how trucks and shipments are matched in real life, so you can see who’s carrying what, track deliveries, and even create new loads on the fly. Everything is interactive and plotted on a map so you can watch the simulation happen in real-time.
6
6
7
7
Concept
8
8
9
-
Freight trading in the real world involves matching cargo with transport capacity, managing shipments efficiently, and sometimes speculating on freight price movements. In this simulation:
9
+
Freight trading is all about moving cargo efficiently—matching shipments with transport capacity and making smart delivery decisions. I tried to capture that in this project by:
10
10
11
-
Trucks represent available transport capacity.
11
+
Treating trucks like transport capacity and loads like shipments.
12
12
13
-
Loads represent shipments that need to be delivered.
13
+
Automatically assigning trucks to loads based on their capacity and location.
14
14
15
-
Truck assignment simulates the market decision of allocating transport capacity to maximize efficiency or profit.
15
+
Letting you create new loads dynamically, which is like new opportunities popping up in the market.
16
16
17
-
Dynamic load creation mimics new market opportunities or volatile demand.
17
+
Updating everything live so you can see trucks move toward their destinations.
│ ├── index.html # Web dashboard with map, inputs, and controls
33
-
│ ├── script.js # JS logic for fetching backend data, updating the map, and drawing lines
34
-
│ └── style.css # Styles for dashboard UI
30
+
│ ├── index.html # My web dashboard with map, inputs, and controls
31
+
│ ├── script.js # JS code for fetching backend data and updating the map
32
+
│ └── style.css # Styles for the dashboard UI
35
33
│
36
34
├── cli/
37
-
│ └── main.py # Optional CLI to run the simulation step by step in the terminal
35
+
│ └── main.py # Optional command-line interface version of the simulation
38
36
│
39
37
└── README.md # This file
40
38
41
-
File Descriptions
39
+
What each file does
42
40
43
41
backend/app.py
44
-
This is the FastAPI backend that exposes API endpoints for the frontend. It allows users to initialize the simulation, fetch real-time truck and load statuses, and create new loads dynamically.
42
+
This is where the backend API lives. It starts the simulation, updates truck positions, and lets the frontend ask for the current status or create new loads.
45
43
46
44
backend/freight_trading.py
47
-
Contains the main simulation logic. It defines trucks, loads, assignment rules, distance calculations, and updates truck positions step-by-step, mimicking freight market operations.
45
+
All the logic for the simulation happens here. Trucks, loads, assignment rules, distance calculations, and movement step-by-step are all handled in this file.
48
46
49
47
backend/requirements.txt
50
-
Lists all Python packages required to run the backend, including FastAPI, Uvicorn, Pandas, and NumPy.
48
+
Lists all the Python libraries you need to run the backend (FastAPI, Uvicorn, Pandas, NumPy).
51
49
52
50
frontend/index.html
53
-
The interactive web dashboard that visualizes the simulation. Users can input parameters, start the simulation, and see trucks and loads dynamically plotted on a U.S. map.
51
+
The dashboard where you control the simulation. You can input the number of trucks and loads, start the simulation, and watch everything happen on a map.
54
52
55
53
frontend/script.js
56
-
Handles the dynamic behavior of the dashboard: fetching backend data, updating truck markers, drawing lines to loads, and refreshing the map every second.
54
+
This JS handles fetching the backend data, updating truck markers, drawing lines to loads, and keeping the map live and dynamic.
57
55
58
56
frontend/style.css
59
-
Defines the styling of the dashboard, including layout, buttons, input fields, and the output console for truck and load statuses.
57
+
Simple styling for the dashboard—makes the inputs, buttons, and map look clean.
60
58
61
59
cli/main.py
62
-
Optional command-line interface to run the simulation in the terminal. Users can input parameters, create loads, assign trucks, and simulate steps without using the web interface.
60
+
A command-line version of the simulation. Lets you run everything step by step in the terminal without using the web interface.
63
61
64
62
How to Run
65
63
Backend
66
64
67
-
Navigate to backend/ and activate your virtual environment.
65
+
Go into the backend/ folder and activate your virtual environment.
68
66
69
67
Install dependencies:
70
68
@@ -76,45 +74,39 @@ Start the FastAPI server:
76
74
uvicorn app:app --reload
77
75
78
76
79
-
Server runs on:http://127.0.0.1:8000
77
+
Server runs on http://127.0.0.1:8000.
80
78
81
79
Frontend
82
80
83
-
Open frontend/index.html in a web browser (Chrome or Firefox recommended).
81
+
Open frontend/index.html in a web browser.
84
82
85
83
Enter simulation parameters and click Start Simulation.
86
84
87
85
Click Create Random Load to add new shipments dynamically.
88
86
89
87
CLI (Optional)
90
88
91
-
Navigate to cli/ folder.
89
+
Go to the cli/ folder.
92
90
93
91
Run:
94
92
95
93
python main.py
96
94
97
95
98
-
Follow prompts to simulate trucks and loads step by step in the terminal.
96
+
Follow the prompts to simulate trucks and loads step by step.
99
97
100
98
Features
101
99
102
-
Real-time map visualization of trucks and their assigned loads.
103
-
104
-
Dynamic creation of new loads to simulate a changing market.
105
-
106
-
Automatic assignment of trucks to loads based on capacity and proximity.
107
-
108
-
Visual tracking of deliveries with moving trucks and dashed lines connecting to destinations.
100
+
Real-time map showing trucks and the loads they’re carrying.
109
101
110
-
Optional CLI for terminal-based simulation.
102
+
Dynamic creation of new loads to simulate changing market demand.
111
103
112
-
Hackathon Notes
104
+
Automatic assignment of trucks based on capacity and location.
113
105
114
-
This project was developed for OwlHacks 2026. It demonstrates:
106
+
Dashed lines that show the path from trucks to their assigned loads.
115
107
116
-
Simulation of freight trading decisions in a simplified market.
108
+
Optional CLI version for terminal-based simulation.
117
109
118
-
Integration of Python backend, Pandas data processing, FastAPI APIs, and interactive frontend visualization with Leaflet.js.
110
+
Notes
119
111
120
-
Dynamic, real-time updates reflecting freight operations in a gamified environment.
112
+
I built this for OwlHacks 2025 to explore freight logistics and trading in a visual, interactive way. It’s not a real freight market, but it gives a sense of how capacity, demand, and delivery timing all interact.
0 commit comments