www.UnknownYet.com - TMS Demo

Welcome to a guided tour of unknownyet.com. It is a compact Transportation Management System demo that you can touch right now. This post shows what the site does, how the parts connect, and how you can run a smooth demo with live trucks on a map.

🧭 What does the site deliver?

At a glance you get a clean web API, a modern single page app, and a live map that shows the most recent position for every driver. The API exposes locations, carriers, orders, shipments, loads, tenders, drivers, events, and telemetry. The map polls fresh GPS points every few seconds and drops a crisp vector truck marker for each driver.

💡 Think of the app as a tiny control tower. You plan freight, you assign a driver, and you watch movement as it happens. Simple, clear, and fast.

🗺️ Live trucks in a few clicks

Open the Map page and the view centers on your active drivers. Each marker is an inline SVG truck (moving or not), so there is no extra asset fetch. Tooltips show driver number, optional load number, speed, and time of the last point. The view auto fits to visible markers and refreshes on a steady rhythm.

📚 Explore the API

Open /api/docs for the interactive explorer. Useful routes include

• GET /api/health for a quick readiness check
• GET /api/locations and POST /api/locations
• GET /api/carriers and POST /api/carriers
• GET /api/orders and POST /api/orders
• POST /api/shipments/plan with an order id
• POST /api/loads/optimize with a shipment id
• GET /api/loads then PATCH /api/loads/{id}/status with an action such as dispatch or deliver
• POST /api/loads/{id}/assign_driver with a driver id
• POST /api/tenders then POST /api/tenders/{id}/respond
• GET /api/events and POST /api/events
• POST /api/telemetry for GPS points
• GET /api/telemetry/latest for the newest point per driver
• GET /api/drivers/{id}/track to fetch recent points

🧪 One click seed for a compelling demo

Run POST /api/seed once in the docs page (https://www.UnknownYet.com/docs). The app creates three locations, two carriers, two drivers, an order with shipment and load, then an assignment that ties the first driver to that load.

🏗️ How the parts fit

• Frontend uses React with TypeScript and Vite. It renders the dashboard and the map and speaks to the API under the /api path.
• Backend uses FastAPI with SQLAlchemy and a modern Psycopg driver for PostgreSQL. It serves OpenAPI docs and JSON schema out of the box.
• Data store is PostgreSQL on the same host for a simple demo flow. Roles and grants are set during setup.
• Edge is Nginx. It serves the built frontend, forwards all /api calls to the app on localhost, and holds the TLS cert from Let’s Encrypt through Certbot.
• Process control uses systemd. Gunicorn with Uvicorn workers binds to localhost, and systemd keeps it running.

🧩 Data model

• Location holds name, address, latitude, and longitude
• Carrier holds partner info
• Order links origin and destination with time windows plus freight facts
• Shipment is the planning unit for an order
• Load carries dates, distance, cost, and status from planned to delivered
• Tender records an offer and a response
• Driver and Equipment represent people and assets
• Assignment ties a driver to a load
• Event captures domain changes for audit and timelines
• Position stores GPS samples with time, latitude, longitude, speed, and heading

🛡️ Reliability choices that help

• Systemd restarts the app on failure and starts it on boot
• Nginx terminates TLS and serves the static app with smart timeouts
• Certbot renews the cert on a schedule
• Database setup and the demo seed are idempotent, so you can run them again without a mess

🎯 A quick demo script you can follow

1. Open /api/docs and run the seed route
2. Open the Map and confirm a truck marker appears
3. Visit Loads, change status to dispatch, then deliver, and watch events update
4. Optional step, post a few GPS samples through the docs page and watch the marker move

🚀 What I can add next...

• User sign in and roles
• Multi stop route planning with time window checks and a distance matrix
• Server sent events for instant UI updates
• Webhooks for carrier responses and device feeds
• Proof of delivery capture with gallery views
• Reports for cost, service, and fleet use

UnknownYet.com gives you a working slice of a real TMS. You can plan, you can assign, and you can see movement in real time. The code is small enough to study in one session, the concepts map to live operations, and the path to production features is clear. If you want a walk through or a focused feature push, say the word and we can build it together.

Tags: tms, demo, fastapi, react, postgres, logistics, mapping, seed data

Email me anytime for the whole project as needed - Sean@CompanyLister.com & thanks for reading!

Have a good day!