Navin Frontend

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

---

Security Headers

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.

Header	Value	Purpose
Content-Security-Policy	see below	Restricts which origins can load scripts, styles, fonts, images, and connections
X-Frame-Options	DENY	Prevents clickjacking of wallet-signing flows (legacy fallback for frame-ancestors)
Referrer-Policy	strict-origin-when-cross-origin	Keeps password-reset tokens (in query strings) out of cross-origin Referer headers
X-Content-Type-Options	nosniff	Blocks MIME-type sniffing
Permissions-Policy	camera=(), microphone=(), geolocation=()	Disables browser features the app does not use

Content-Security-Policy

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_BASE_URL); not in the committed policy, see the note below
• Soroban RPC — Stellar RPC endpoint used for contract calls
• Sentry ingest — https://*.ingest.sentry.io for error reporting
• Fonts — bundled with the app (see frontend/src/fonts.css), so no font CDN is allowed
• 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' 'unsafe-inline' https://browser.sentry-cdn.com;
style-src 'self' 'unsafe-inline';
font-src 'self' data:;
img-src 'self' data: blob: https://*.tile.openstreetmap.org https://tile.openstreetmap.org;
connect-src 'self' https://*.sentry.io https://*.ingest.sentry.io https://soroban-testnet.stellar.org https://soroban-mainnet.stellar.org https://horizon-testnet.stellar.org https://horizon.stellar.org;
worker-src 'self' blob:;
manifest-src 'self';
upgrade-insecure-requests;

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

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.

---

What the Frontend Does

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

---

Production Documentation

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

---

Project Structure

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

---

Quick Start

Prerequisites

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

Installation

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

Useful Commands

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.

---

Contributing

🌿 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 Frontend Component & Styling Conventions for styling guidelines.

Developer Guides

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

---

Community

Have questions or want to discuss ideas?

• Navin Telegram Group

---

Related Repositories

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

---

Star the Project ⭐

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

---

License

This project is licensed under the MIT License.