MB Cargo
MB Cargo is a full-stack logistics platform designed for a Kyrgyzstan-to-China freight forwarder, enabling clients to register shipments and track them in real-time while administrators manage the entire fleet from a centralized dashboard. Clients access a public-facing interface where they register cargo shipments by entering recipient name, phone, direction (Kyrgyzstan → China or vice versa), and cargo description, receiving an auto-generated unique tracking code (format: MB{YYMM}-{XXXX}) and a shareable tracking link. The tracking page displays shipment progress via a visual 3-step progress bar showing warehouse → in-transit → arrived states with live status updates. Administrators log in via hardcoded credentials to access a comprehensive dashboard featuring a full shipment table with filtering by date range and status, inline editing capabilities for weight, price, and shipment status via modal dialogs, and an admin-only shipment creation tool. The system uses SQLite for zero-setup persistence, FastAPI for the backend REST API, and Next.js 14 with TypeScript and Tailwind CSS for a responsive, mobile-friendly frontend optimized for the Kyrgyz market.
Client Features
- •Register a cargo shipment with recipient name, phone, direction, and description
- •Auto-generated unique tracking code (e.g., MB2604-A7XQ) for each shipment
- •Shareable public tracking link — no login required to check status
- •Real-time 3-step progress bar showing shipment journey
- •Live status updates (На складе → В пути → Прибыл)
- •View all shipment details: sender, recipient, weight, price, date created
- •Track shipments from Kyrgyzstan → China or China → Kyrgyzstan
Admin Dashboard
- •Hardcoded admin login (admin / admin123) with static token auth
- •Dashboard displaying full table of all registered shipments
- •Filter shipments by date range (from/to) and status
- •Inline edit shipment status (warehouse / in-transit / arrived)
- •Update shipment weight and price via edit modal
- •Admin-only shipment creation with all fields pre-settable
- •Real-time updates reflected on public tracking pages
- •Logout functionality with token cleanup
Technical Stack
- •Backend: FastAPI (Python), SQLAlchemy ORM, Pydantic v2 validation
- •Frontend: Next.js 14 (App Router), React 18, TypeScript, Tailwind CSS 3
- •Database: SQLite (file-based, zero setup required)
- •Authentication: Static token-based admin auth (demo simplicity)
- •API: RESTful endpoints for shipments (CRUD) and admin login
- •Schemas: Separate request/response DTOs for API contracts
- •State: localStorage for token persistence on admin dashboard
- •Tracking code generation: unique MB{YYMM}-{4 random chars} with retry logic
- •Date filtering: ISO datetime query parameters on shipment list
- •CORS: Configured for localhost cross-origin requests (demo)