{"id":50926502,"url":"https://github.com/narinsak-u/ship-it-out","last_synced_at":"2026-06-16T23:32:19.623Z","repository":{"id":359492947,"uuid":"1244425236","full_name":"narinsak-u/ship-it-out","owner":"narinsak-u","description":"A real-time shipment tracking platform with a Vue 3 frontend and Go backend. 🚚","archived":false,"fork":false,"pushed_at":"2026-05-31T13:12:33.000Z","size":1088,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T13:13:32.242Z","etag":null,"topics":["docker","fiber","golang","leaflet-map","opencage-api","pinia","postgresql","shadcn-vue","vuejs"],"latest_commit_sha":null,"homepage":"https://ship-it-out.up.railway.app/","language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/narinsak-u.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-20T08:53:12.000Z","updated_at":"2026-05-31T11:28:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/narinsak-u/ship-it-out","commit_stats":null,"previous_names":["narinsak-u/ship-simple","narinsak-u/ship-it-out"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/narinsak-u/ship-it-out","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narinsak-u%2Fship-it-out","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narinsak-u%2Fship-it-out/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narinsak-u%2Fship-it-out/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narinsak-u%2Fship-it-out/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/narinsak-u","download_url":"https://codeload.github.com/narinsak-u/ship-it-out/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narinsak-u%2Fship-it-out/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34428196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","fiber","golang","leaflet-map","opencage-api","pinia","postgresql","shadcn-vue","vuejs"],"created_at":"2026-06-16T23:32:18.922Z","updated_at":"2026-06-16T23:32:19.602Z","avatar_url":"https://github.com/narinsak-u.png","language":"Vue","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Thun-u-der Express — Shipment Tracking Dashboard\n\nReal-time shipment tracking platform with a **Vue 3** frontend and **Go** backend. Monitor cargo globally with interactive maps, status updates, and timeline tracking.\n\n![Dashboard screenshot](frontend/public/Screenshot.png)\n\n---\n\n## Tech Stack\n\n### Frontend\n\n| Component | Technology |\n|-----------|-----------|\n| Framework | Vue 3.5 (Composition API, `\u003cscript setup lang=\"ts\"\u003e`) |\n| Build tool | Vite 6 |\n| Language | TypeScript 5.7 (strict mode) |\n| Routing | Vue Router 4 (lazy-loaded routes) |\n| State management | Pinia (client state) + TanStack Vue Query (server/cache state) |\n| UI components | shadcn-vue (New York style) on reka-ui |\n| Styling | Tailwind CSS v4 |\n| Icons | lucide-vue-next |\n| Maps | Leaflet with CARTO dark tiles |\n| Geocoding | OpenCage API (`opencage-api-client`) |\n| Toast | vue-sonner |\n| Package manager | Bun |\n\n### Backend\n\n| Component | Technology |\n|-----------|-----------|\n| Language | Go 1.24 |\n| HTTP framework | Fiber v2 (FastHTTP) |\n| ORM | GORM v2 with PostgreSQL |\n| Auth | JWT (HS256), HTTP-only cookies |\n| Password hashing | bcrypt |\n| Cache | N/A (in-memory rate limiter) |\n| WebSocket | gorilla/websocket via fiber/contrib |\n| Logging | zerolog |\n| Containerization | Docker Compose (Postgres 16) |\n\n---\n\n## Project Structure\n\n```\nship-it-out/\n├── frontend/                     # Vue 3 SPA\n│   ├── src/\n│   │   ├── components/           # Shared Vue components\n│   │   │   └── ui/               # shadcn-vue primitives (auto-generated)\n│   │   ├── views/                # Page-level route components (lazy-loaded)\n│   │   ├── lib/                  # Types, API client, utilities, seed data\n│   │   │   └── api/              # Endpoint functions + response mappers\n│   │   ├── hooks/                # TanStack Vue Query hooks\n│   │   ├── stores/               # Pinia store (auth)\n│   │   ├── composables/          # Reusable composition functions\n│   │   ├── router/               # Vue Router config (6 routes)\n│   │   ├── App.vue               # Root component\n│   │   ├── main.ts               # Entry point\n│   │   └── styles.css            # Tailwind entry + Ocean Deep theme\n│   ├── docs/OVERVIEW.md          # Frontend architecture reference\n│   ├── package.json\n│   ├── vite.config.ts\n│   ├── tsconfig.json\n│   └── components.json           # shadcn-vue config\n├── backend/                      # Go API server\n│   ├── cmd/server/main.go        # Entry point: bootstrap, migrate, seed, routes\n│   ├── internal/\n│   │   ├── config/               # Environment-based configuration\n│   │   ├── database/             # GORM (PostgreSQL) connection\n│   │   ├── models/               # User, Shipment, ShipmentEvent, Hub\n│   │   ├── middleware/           # Auth (JWT), CORS, Logger\n│   │   ├── auth/                 # Register, Login, Me, Logout\n│   │   ├── shipment/             # Shipment CRUD + status updates\n│   │   ├── hub/                  # Hub CRUD\n│   │   ├── tracking/             # Public tracking lookup\n│   │   ├── analytics/            # Dashboard aggregate stats\n│   │   ├── seed/                 # Demo data (6 hubs, 12 shipments)\n│   │   └── websocket/            # Real-time tracking infrastructure\n│   ├── pkg/utils/                # Response writers, bcrypt helpers\n│   ├── docs/                     # OVERVIEW.md, WORKFLOW.md\n│   ├── Dockerfile\n│   ├── docker-compose.yml\n│   └── go.mod\n└── README.md\n```\n\n---\n\n## Getting Started\n\n### Frontend\n\n```bash\ncd frontend\nbun install\nnpm run dev        # Start Vite dev server\nnpm run build      # vue-tsc typecheck + vite build\nnpm run preview    # Preview production build\nnpm run lint       # ESLint check\nnpm run format     # Prettier auto-format\n```\n\n### Backend\n\n```bash\n# With Docker Compose (recommended)\ncd backend\ndocker compose up\n\n# Or manually (Postgres required)\ncd backend\ngo run .\n```\n\nThe backend starts on `http://localhost:8080` and the frontend dev server on `http://localhost:5173`.\n\n---\n\n## Frontend Scripts\n\n| Command | Description |\n|---------|-------------|\n| `npm run dev` | Start Vite dev server |\n| `npm run build` | `vue-tsc` typecheck + `vite build` |\n| `npm run preview` | Preview production build locally |\n| `npm run lint` | ESLint check (flat config) |\n| `npm run format` | Prettier auto-format |\n\n---\n\n## Features\n\n- **Tracking search** — find shipments by order ID or tracking number from the home page\n- **Filterable manifest** — paginated orders table with status filters, text search, and CRUD\n- **Route visualization** — Leaflet map showing origin → current → destination with styled polylines and custom markers\n- **Timeline** — chronological event history per shipment with status indicators and location\n- **Live telemetry overlay** — floating card on map showing current coordinates\n- **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\n- **Geocoding** — addresses are resolved to real lat/lng via OpenCage API before creating orders or hubs\n- **Hub management** — CRUD operations for logistics hubs with capacity tracking\n- **Analytics dashboard** — KPI cards and carrier performance breakdowns\n- **Dark theme** — Ocean Deep OKLCH color palette\n- **Responsive layout** — mobile-first grid system\n\n---\n\n## Backend API Overview\n\n| Method | Path | Auth | Description |\n|--------|------|------|-------------|\n| POST | `/api/auth/register` | No | Register a new user |\n| POST | `/api/auth/login` | No | Login, returns JWT + cookie |\n| GET | `/api/auth/me` | JWT | Get current user profile |\n| POST | `/api/auth/logout` | No | Clear auth cookie |\n| GET | `/api/shipments` | No | List shipments (paginated, searchable, filterable) |\n| GET | `/api/shipments/:orderId` | No | Get shipment by order ID |\n| POST | `/api/shipments` | JWT | Create a new shipment |\n| PATCH | `/api/shipments/:orderId/status` | JWT | Update status + log event |\n| PUT | `/api/shipments/:orderId` | JWT | Update shipment fields |\n| DELETE | `/api/shipments/:orderId` | JWT | Delete shipment + events |\n| GET | `/api/track/:trackingNumber` | No | Public tracking lookup |\n| GET | `/api/hubs` | No | List all hubs |\n| GET | `/api/hubs/:id` | No | Get hub by ID |\n| POST | `/api/hubs` | JWT | Create a hub |\n| PUT | `/api/hubs/:id` | JWT | Update hub fields |\n| DELETE | `/api/hubs/:id` | JWT | Delete a hub |\n| GET | `/api/health` | No | Container liveness probe |\n| GET | `/api/analytics/overview` | No | Dashboard aggregate stats |\n| GET | `/api/analytics/timeseries` | No | Shipment trends by month and day-of-week |\n| GET | `/ws/tracking/:trackingNumber` | No | Real-time tracking WebSocket |\n\n---\n\n## Design Tokens\n\nCSS custom properties defined in `frontend/src/styles.css` under the `:root` block:\n\n| Token | Purpose |\n|-------|---------|\n| `--color-background` | Page background |\n| `--color-primary` | Accent/action color (cyan) |\n| `--color-success` | Delivered status |\n| `--color-warning` | Warning states |\n| `--color-destructive` | Error/delayed states |\n| `--color-info` | In-transit status |\n| `--gradient-hero` | Hero section gradient |\n| `--shadow-glow` | Glowing accent shadow |\n\n---\n\n## Environment Variables\n\n### Backend (`backend/.env`)\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PORT` | `8080` | Server listen port |\n| `DATABASE_URL` | `postgres://user:pass@localhost:5432/shipments` | PostgreSQL DSN |\n| `JWT_SECRET` | `change-me` | HMAC secret for JWT |\n\n### Frontend (`frontend/.env`)\n\n| Variable | Description |\n|----------|-------------|\n| `VITE_OPENCAGE_API_KEY` | OpenCage Geocoding API key |\n\n---\n\n## Documentation\n\n- `frontend/docs/OVERVIEW.md` — Frontend architecture, components, data flow\n- `backend/docs/OVERVIEW.md` — Backend architecture, routes, data model\n- `backend/docs/WORKFLOW.md` — Detailed request/response flows for every endpoint\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnarinsak-u%2Fship-it-out","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnarinsak-u%2Fship-it-out","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnarinsak-u%2Fship-it-out/lists"}