🚨 Contributors: All PRs must target the
devbranch, notmain.
See CONTRIBUTING.md for details.
Navin is a blockchain-powered logistics platform that improves supply chain visibility for enterprises through tokenized shipments, immutable milestone tracking, and automated settlements. By creating a zero-trust interface between logistics providers and their clients, Navin ensures both parties access identical real-time data — removing information asymmetry and enabling seamless, dispute-free operations.
This repository is the React frontend of the Navin platform — built with TypeScript and Vite — giving logistics companies and their customers a single, real-time interface to track shipments, verify on-chain milestones, and monitor automated payment settlements powered by Stellar Soroban.
⭐ If this project interests you, please star the repository! It helps the project grow, attracts contributors, and supports open-source development. Star Navin Frontend ⭐
| Layer | Technology | Why |
|---|---|---|
| UI Framework | React 19 | Component-based UI — the industry standard |
| Language | TypeScript | Type safety for complex Soroban SDK interactions and multi-dashboard data flows |
| Styling | Tailwind CSS | Utility-first CSS for consistent, maintainable styling with design tokens |
| Build Tool | Vite | Lightning-fast dev server and production bundler |
| Package Manager | pnpm | Fast, disk-efficient package manager with strict dependency management |
| Testing | Vitest + Testing Library | Fast unit and component testing |
| Routing | React Router v7 | Client-side navigation |
| HTTP Client | Axios | API communication with the Navin backend |
| Blockchain | Stellar Soroban | Smart contract interaction for payments and milestones |
Tech Stack Rationale: See Technology Choices for detailed explanation of TypeScript, Tailwind CSS, and pnpm.
| Feature | Description |
|---|---|
| Real-time Shipment Dashboards | Companies and customers see live shipment status — no information gap between both parties |
| On-chain Milestone Visualization | Immutable milestone records (picked up, in transit, delivered) surfaced clearly in the UI |
| Automated Settlement Tracking | Payment status updated automatically when verified delivery events occur on-chain |
| Company Dashboard | Logistics companies manage shipments, users, and track performance analytics |
| Customer Dashboard | Customers track their active shipments and delivery history in one place |
| Shipment Detail View | Full breakdown of a single shipment — milestones, IoT sensor data, payment status, and delivery proof |
| Notification System | Real-time alerts for shipment updates, delays, and payment events |
| Responsive Interface | Works across desktop, tablet, and mobile |
For deployment and configuration guidance:
- Environment Setup Guide - Configure environment variables for all deployment platforms
- Legacy CSS Migration Guide - Migrate components from CSS to Tailwind
- Technology Choices - Why TypeScript, Tailwind CSS, and pnpm
frontend/
├── src/
│ ├── components/ # Reusable UI components (Navbar, Modal, StatusBadge, etc.)
│ ├── pages/ # Page-level components (LandingPage, Dashboard, ShipmentDetail, etc.)
│ ├── services/ # Axios API service layer (shipmentService.ts, authService.ts, etc.)
│ ├── context/ # React context providers (ToastContext, AuthContext)
│ ├── hooks/ # Custom React hooks
│ ├── types/ # Shared TypeScript interfaces and types
│ ├── utils/ # Utility/helper functions
│ └── test/ # Test setup and smoke tests
├── public/
│ └── images/ # Static assets (logos, icons, illustrations)
├── tsconfig.json # TypeScript config
├── vite.config.ts # Vite + Vitest config
└── package.json
# Fork the repository and clone your fork
git clone https://github.com/yourusername/navin-frontend.git
cd navin-frontend/frontend
# Set up your environment variables
cp .env.example .env
# Install dependencies with pnpm
pnpm install
# Start the development server
pnpm run devYour app runs at http://localhost:5173.
pnpm run dev # Start local dev server (hot reload)
pnpm run build # Type-check + production build
pnpm run lint # Run ESLint
pnpm run test # Run all tests (Vitest)
pnpm run test:watch # Run tests in watch mode
⚠️ Important: Always usepnpm(notnpmoryarn) to maintain consistency. Using different package managers creates lock file conflicts and dependency mismatches.
🌿 Git Flow Workflow
We use adev→mainworkflow:
dev= Active development (all PRs go here)main= Production-ready code (Vercel deploys from here)Never submit PRs to
maindirectly. All feature work goes todevfirst.
We welcome contributors of all experience levels — whether you're building your first open-source component or you're a seasoned TypeScript developer.
Read our CONTRIBUTING.md for the full guide on branching, commits, PRs, and our review process.
Quick overview:
- Browse open issues on the Issues page
- Comment on an issue and wait to be assigned before starting
- Create your branch from
dev(notmain) - Implement the feature and ensure your PR targets
dev - All frontend PRs must include a screenshot of the UI change
- Use pnpm for all package management commands (not npm or yarn)
- Use Tailwind CSS utility classes for styling (no vanilla CSS files for new components)
💡 All components should be written in TypeScript (
.tsx). Follow the file structure in each issue — it tells you exactly where to create your files. See TAILWIND_MIGRATION.md for styling guidelines (available after Issue #92 is merged).
| Guide | Description |
|---|---|
| Frontend Component & Styling Conventions | Folder structure, naming rules, Tailwind-first styling, path aliases, and legacy CSS migration policy — start here |
| Component Conventions | TypeScript, exports, props interfaces, and dead code rules |
| Tailwind Migration Guide | Step-by-step CSS → Tailwind conversion reference |
| Tailwind Before/After Examples | Side-by-side migration examples |
| Tailwind PR Checklist | Checklist for Tailwind migration PRs |
Have questions or want to discuss ideas?
- Smart Contracts: navin-contracts
- Backend API: navin-backend
If you find Navin useful, interesting, or want to support decentralized logistics infrastructure — please give us a star on GitHub! It helps us attract more contributors and grow the community.
⭐ Star Navin Frontend on GitHub
This project is licensed under the MIT License.