https://github.com/narinsak-u/ship-it-out
A real-time shipment tracking platform with a Vue 3 frontend and Go backend. 🚚
https://github.com/narinsak-u/ship-it-out
docker fiber golang leaflet-map opencage-api pinia postgresql shadcn-vue vuejs
Last synced: 20 days ago
JSON representation
A real-time shipment tracking platform with a Vue 3 frontend and Go backend. 🚚
- Host: GitHub
- URL: https://github.com/narinsak-u/ship-it-out
- Owner: narinsak-u
- Created: 2026-05-20T08:53:12.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-31T13:12:33.000Z (about 1 month ago)
- Last Synced: 2026-05-31T13:13:32.242Z (about 1 month ago)
- Topics: docker, fiber, golang, leaflet-map, opencage-api, pinia, postgresql, shadcn-vue, vuejs
- Language: Vue
- Homepage: https://ship-it-out.up.railway.app/
- Size: 1.04 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Thun-u-der Express — Shipment Tracking Dashboard
Real-time shipment tracking platform with a **Vue 3** frontend and **Go** backend. Monitor cargo globally with interactive maps, status updates, and timeline tracking.
---
## Tech Stack
### Frontend
| Component | Technology |
|-----------|-----------|
| Framework | Vue 3.5 (Composition API, ``) |
| Build tool | Vite 6 |
| Language | TypeScript 5.7 (strict mode) |
| Routing | Vue Router 4 (lazy-loaded routes) |
| State management | Pinia (client state) + TanStack Vue Query (server/cache state) |
| UI components | shadcn-vue (New York style) on reka-ui |
| Styling | Tailwind CSS v4 |
| Icons | lucide-vue-next |
| Maps | Leaflet with CARTO dark tiles |
| Geocoding | OpenCage API (`opencage-api-client`) |
| Toast | vue-sonner |
| Package manager | Bun |
### Backend
| Component | Technology |
|-----------|-----------|
| Language | Go 1.24 |
| HTTP framework | Fiber v2 (FastHTTP) |
| ORM | GORM v2 with PostgreSQL |
| Auth | JWT (HS256), HTTP-only cookies |
| Password hashing | bcrypt |
| Cache | N/A (in-memory rate limiter) |
| WebSocket | gorilla/websocket via fiber/contrib |
| Logging | zerolog |
| Containerization | Docker Compose (Postgres 16) |
---
## Project Structure
```
ship-it-out/
├── frontend/ # Vue 3 SPA
│ ├── src/
│ │ ├── components/ # Shared Vue components
│ │ │ └── ui/ # shadcn-vue primitives (auto-generated)
│ │ ├── views/ # Page-level route components (lazy-loaded)
│ │ ├── lib/ # Types, API client, utilities, seed data
│ │ │ └── api/ # Endpoint functions + response mappers
│ │ ├── hooks/ # TanStack Vue Query hooks
│ │ ├── stores/ # Pinia store (auth)
│ │ ├── composables/ # Reusable composition functions
│ │ ├── router/ # Vue Router config (6 routes)
│ │ ├── App.vue # Root component
│ │ ├── main.ts # Entry point
│ │ └── styles.css # Tailwind entry + Ocean Deep theme
│ ├── docs/OVERVIEW.md # Frontend architecture reference
│ ├── package.json
│ ├── vite.config.ts
│ ├── tsconfig.json
│ └── components.json # shadcn-vue config
├── backend/ # Go API server
│ ├── cmd/server/main.go # Entry point: bootstrap, migrate, seed, routes
│ ├── internal/
│ │ ├── config/ # Environment-based configuration
│ │ ├── database/ # GORM (PostgreSQL) connection
│ │ ├── models/ # User, Shipment, ShipmentEvent, Hub
│ │ ├── middleware/ # Auth (JWT), CORS, Logger
│ │ ├── auth/ # Register, Login, Me, Logout
│ │ ├── shipment/ # Shipment CRUD + status updates
│ │ ├── hub/ # Hub CRUD
│ │ ├── tracking/ # Public tracking lookup
│ │ ├── analytics/ # Dashboard aggregate stats
│ │ ├── seed/ # Demo data (6 hubs, 12 shipments)
│ │ └── websocket/ # Real-time tracking infrastructure
│ ├── pkg/utils/ # Response writers, bcrypt helpers
│ ├── docs/ # OVERVIEW.md, WORKFLOW.md
│ ├── Dockerfile
│ ├── docker-compose.yml
│ └── go.mod
└── README.md
```
---
## Getting Started
### Frontend
```bash
cd frontend
bun install
npm run dev # Start Vite dev server
npm run build # vue-tsc typecheck + vite build
npm run preview # Preview production build
npm run lint # ESLint check
npm run format # Prettier auto-format
```
### Backend
```bash
# With Docker Compose (recommended)
cd backend
docker compose up
# Or manually (Postgres required)
cd backend
go run .
```
The backend starts on `http://localhost:8080` and the frontend dev server on `http://localhost:5173`.
---
## Frontend Scripts
| Command | Description |
|---------|-------------|
| `npm run dev` | Start Vite dev server |
| `npm run build` | `vue-tsc` typecheck + `vite build` |
| `npm run preview` | Preview production build locally |
| `npm run lint` | ESLint check (flat config) |
| `npm run format` | Prettier auto-format |
---
## Features
- **Tracking search** — find shipments by order ID or tracking number from the home page
- **Filterable manifest** — paginated orders table with status filters, text search, and CRUD
- **Route visualization** — Leaflet map showing origin → current → destination with styled polylines and custom markers
- **Timeline** — chronological event history per shipment with status indicators and location
- **Live telemetry overlay** — floating card on map showing current coordinates
- **Status updates with hub awareness** — changing a shipment's status to a hub-based state (departed, in_transit) updates the map position to that hub's real coordinates
- **Geocoding** — addresses are resolved to real lat/lng via OpenCage API before creating orders or hubs
- **Hub management** — CRUD operations for logistics hubs with capacity tracking
- **Analytics dashboard** — KPI cards and carrier performance breakdowns
- **Dark theme** — Ocean Deep OKLCH color palette
- **Responsive layout** — mobile-first grid system
---
## Backend API Overview
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/auth/register` | No | Register a new user |
| POST | `/api/auth/login` | No | Login, returns JWT + cookie |
| GET | `/api/auth/me` | JWT | Get current user profile |
| POST | `/api/auth/logout` | No | Clear auth cookie |
| GET | `/api/shipments` | No | List shipments (paginated, searchable, filterable) |
| GET | `/api/shipments/:orderId` | No | Get shipment by order ID |
| POST | `/api/shipments` | JWT | Create a new shipment |
| PATCH | `/api/shipments/:orderId/status` | JWT | Update status + log event |
| PUT | `/api/shipments/:orderId` | JWT | Update shipment fields |
| DELETE | `/api/shipments/:orderId` | JWT | Delete shipment + events |
| GET | `/api/track/:trackingNumber` | No | Public tracking lookup |
| GET | `/api/hubs` | No | List all hubs |
| GET | `/api/hubs/:id` | No | Get hub by ID |
| POST | `/api/hubs` | JWT | Create a hub |
| PUT | `/api/hubs/:id` | JWT | Update hub fields |
| DELETE | `/api/hubs/:id` | JWT | Delete a hub |
| GET | `/api/health` | No | Container liveness probe |
| GET | `/api/analytics/overview` | No | Dashboard aggregate stats |
| GET | `/api/analytics/timeseries` | No | Shipment trends by month and day-of-week |
| GET | `/ws/tracking/:trackingNumber` | No | Real-time tracking WebSocket |
---
## Design Tokens
CSS custom properties defined in `frontend/src/styles.css` under the `:root` block:
| Token | Purpose |
|-------|---------|
| `--color-background` | Page background |
| `--color-primary` | Accent/action color (cyan) |
| `--color-success` | Delivered status |
| `--color-warning` | Warning states |
| `--color-destructive` | Error/delayed states |
| `--color-info` | In-transit status |
| `--gradient-hero` | Hero section gradient |
| `--shadow-glow` | Glowing accent shadow |
---
## Environment Variables
### Backend (`backend/.env`)
| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `8080` | Server listen port |
| `DATABASE_URL` | `postgres://user:pass@localhost:5432/shipments` | PostgreSQL DSN |
| `JWT_SECRET` | `change-me` | HMAC secret for JWT |
### Frontend (`frontend/.env`)
| Variable | Description |
|----------|-------------|
| `VITE_OPENCAGE_API_KEY` | OpenCage Geocoding API key |
---
## Documentation
- `frontend/docs/OVERVIEW.md` — Frontend architecture, components, data flow
- `backend/docs/OVERVIEW.md` — Backend architecture, routes, data model
- `backend/docs/WORKFLOW.md` — Detailed request/response flows for every endpoint