🚨 Contributors: All PRs must target the dev branch, not main.
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 ⭐

The Vercel deployment (frontend/vercel.json) sets security headers on every response. Because the app keeps the auth token in localStorage and signs Stellar transactions, these headers are a defense-in-depth layer against XSS and clickjacking.

The policy allows only the origins the app actually talks to:

• 'self' — the app bundle and its own assets
• API origin — the Navin backend (VITE_API_URL)
• Soroban RPC — Stellar RPC endpoint used for contract calls
• Sentry ingest — https://*.ingest.sentry.io for error reporting
• Google Fonts — https://fonts.googleapis.com (styles) and https://fonts.gstatic.com (font files)
• OpenStreetMap tiles — https://*.tile.openstreetmap.org for Leaflet maps

default-src 'self';
base-uri 'self';
object-src 'none';
frame-ancestors 'none';
form-action 'self';
script-src 'self';
style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;
font-src 'self' https://fonts.gstatic.com data:;
img-src 'self' data: blob: https://*.tile.openstreetmap.org;
connect-src 'self' https://*.ingest.sentry.io;

Note: The API and Soroban RPC origins are environment-specific. Add them to connect-src in frontend/vercel.json for each deployment (e.g. https://api.navin.example https://soroban-testnet.stellar.org). If you need to roll out a change safely, switch the header name to Content-Security-Policy-Report-Only first, confirm there are no violations in the browser console, then rename it back to Content-Security-Policy.

Tech Stack Rationale: See Technology Choices for detailed explanation of TypeScript, Tailwind CSS, and pnpm.

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

• Node.js v18 or later
• pnpm v8 or later (install globally: npm install -g pnpm)

# 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 dev

Your 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 use pnpm (not npm or yarn) to maintain consistency. Using different package managers creates lock file conflicts and dependency mismatches.

🌿 Git Flow Workflow
We use a dev → main workflow:

• dev = Active development (all PRs go here)
• main = Production-ready code (Vercel deploys from here)

Never submit PRs to main directly. All feature work goes to dev first.

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 (not main)
• 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).

Have questions or want to discuss ideas?

• Navin Telegram Group

• Smart Contracts: navin-contracts
• Backend API: navin-backend

If you find Navin useful,

This project is licensed under the MIT License.

This project is licensed under the MIT License.

• #907: [Refactor] Remove the Promise.resolve().then(() => setState(...)) workaround used in effects

• #903: [Theme] NotificationsPage and UserManagement use hardcoded dark colours and look broken in light theme /* … truncated 333 chars — edit only what you need near the top … */