🚢 ShipGuard AI

Real-time Shipment Risk Monitoring & Logistics Intelligence Platform

Real-time Tracking • Risk Assessment • Intelligent Alerts • Analytics Dashboard • Webhook Integration

Live Demo • Features • Quick Start • API Docs

📖 About

ShipGuard AI is an enterprise-grade logistics monitoring platform that provides real-time visibility into shipment operations, automated risk assessment, and predictive analytics. Built for modern supply chains, it seamlessly integrates with Transportation Management Systems (TMS), Enterprise Resource Planning (ERP) systems, and carrier APIs.

The platform leverages Firebase Firestore for real-time data synchronization, enabling instant updates across dashboards, alerts, and analytics. With intelligent webhook ingestion, weather integration, and logistics news aggregation, ShipGuard AI delivers actionable insights that help businesses proactively manage shipment risks and optimize operations.

Whether you're tracking a single shipment or managing thousands across multiple carriers and modes, ShipGuard AI provides the tools you need for complete logistics visibility and control.

✨ Features

✅ Real-time Shipment Tracking — Monitor shipments across multiple carriers and transport modes
✅ Automated Risk Scoring — Dynamic risk calculation with visual distribution analytics
✅ Intelligent Alert System — Proactive notifications for high-risk events and delays
✅ Live Analytics Dashboard — Trend analysis, operational metrics, and KPIs
✅ Webhook Integration — Seamless ingestion from TMS/ERP systems with secure authentication
✅ Webhook Security Hardening — HMAC signature verification, payload validation, and rate limiting
✅ Weather Monitoring — Location-based weather forecasts for route planning
✅ Logistics News Feed — Real-time industry news aggregation
✅ Route Intelligence — Alternative route recommendations with operational risk context
✅ Firestore Real-time Sync — Instant updates across all connected clients
✅ Multi-carrier Support — DHL, FedEx, UPS, and custom carrier integration
✅ Custom Reporting — Configurable views, filters, and data exports
✅ User Settings Persistence — Firestore-backed preferences and configurations
✅ Secure API Routes — Weather, news, and route proxy endpoints with backend-only provider keys
✅ Session Protection — Frontend session timeout controls and protected route enforcement
✅ Resilience Layer — Frontend retry/timeout handling and offline/online status UX
✅ Observability Ready — Optional Sentry integration for frontend and backend error monitoring
✅ CI Automation — Frontend and backend GitHub Actions workflows

🛠️ Tech Stack

Frontend

React 18 — Modern component-based UI framework
Vite — Lightning-fast build tool and dev server
Tailwind CSS — Utility-first styling with custom design system
Recharts — Interactive data visualization and charting
Firebase Web SDK — Client-side Firestore subscriptions and authentication

Backend

Node.js — JavaScript runtime for server-side logic
Express — Minimal and flexible web application framework
Firebase Admin SDK — Server-side Firestore operations and authentication
CORS + Helmet + Morgan — Cross-origin controls, security headers, and request logging
Joi + express-rate-limit — Payload validation and abuse protection

Monitoring & Quality

Sentry — Optional application error monitoring (frontend + backend)
GitHub Actions — Frontend build checks and backend syntax validation

Database & Authentication

Cloud Firestore — Scalable NoSQL document database with real-time sync
Firebase Authentication — Secure user authentication and authorization

External Integrations

OpenWeather API — Weather data and location-based forecasts
News API — Logistics and supply chain news aggregation

📁 Project Structure

shipguard-ai/
├── backend/
│   ├── server.js                 # Express server, API routes, webhook handler
│   ├── .env                      # Backend environment variables
│   ├── .env.example              # Backend env template
│   ├── service-account.json      # Firebase Admin credentials (gitignored)
│   ├── package.json              # Backend dependencies
│   └── node_modules/
├── src/
│   ├── components/               # Reusable React components
│   ├── pages/                    # Page-level components (Dashboard, Analytics, Alerts)
│   ├── lib/                      # Firebase client & API integrations
│   │   ├── api/                  # Backend proxy API clients + retry utility
│   │   └── ml/                   # Risk prediction and recommendation utilities
│   ├── App.jsx                   # Main application component
│   └── main.jsx                  # React entry point
├── public/                       # Static assets
├── .env                          # Frontend environment variables
├── .env.example                  # Frontend env template
├── .gitignore                    # Git ignore configuration
├── package.json                  # Frontend dependencies and scripts
├── vite.config.js                # Vite build configuration
├── tailwind.config.js            # Tailwind CSS customization
├── postcss.config.js             # PostCSS configuration
└── README.md                     # Project documentation

🚀 Quick Start

Prerequisites

Ensure you have the following installed:

Node.js v16 or higher
npm or yarn
Firebase project with Firestore and Authentication enabled
API keys for OpenWeather and News API

Installation

# Clone the repository
git clone https://github.com/LegendarySumit/shipguard-ai.git
cd shipguard-ai

# Install frontend dependencies
npm install

# Install backend dependencies
cd backend
npm install
cd ..

Configuration

Create .env file in project root:

# Firebase Client Configuration
VITE_FIREBASE_API_KEY=your_firebase_api_key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id

# Backend API URL
VITE_BACKEND_URL=http://localhost:8787

Create backend/.env file:

# Server Configuration
PORT=8787
NODE_ENV=development
ALLOWED_ORIGINS=http://localhost:5173,http://127.0.0.1:5173

# Webhook Security
WEBHOOK_SECRET=your_secure_webhook_secret_min_32_chars
WEBHOOK_URL=http://localhost:8787
WEBHOOK_REQUIRE_HMAC=true
WEBHOOK_ALLOW_LEGACY_SECRET=false

# External APIs
OPENWEATHER_API_KEY=your_openweather_api_key
NEWS_API_KEY=your_news_api_key

# PII encryption (required for encrypted storage of customer/product fields)
PII_ENCRYPTION_KEY=replace_with_strong_random_secret

# Webhook retry queue (prevents data loss on transient failures)
WEBHOOK_RETRY_ENABLED=true
WEBHOOK_RETRY_INTERVAL_SEC=60
WEBHOOK_RETRY_MAX_ATTEMPTS=6
WEBHOOK_RETRY_BATCH_SIZE=25

# Firestore retention policy
RETENTION_ENABLED=true
RETENTION_DAYS=365
RETENTION_RUN_EVERY_HOURS=24

# Firebase Admin (choose one method)
FIREBASE_SERVICE_ACCOUNT_PATH=backend/service-account.json
# OR FIREBASE_SERVICE_ACCOUNT_JSON={"type":"service_account",...}
# OR FIREBASE_SERVICE_ACCOUNT_JSON_BASE64=base64_encoded_json

Generate Webhook Secret

node -e "console.log(require('crypto').randomBytes(48).toString('base64url'))"

Deploy Firestore Security Rules

This project includes hardened rules in firestore.rules.

firebase deploy --only firestore:rules

Run the Application

Terminal 1 — Start Frontend:

npm run dev

Frontend available at http://localhost:5173

Terminal 2 — Start Backend:

npm run backend:dev

Backend available at http://localhost:8787

Build for Production

# Build frontend
npm run build

# Preview production build
npm run preview

# Run backend in production
cd backend
NODE_ENV=production node server.js

📚 Usage

Dashboard

Access the main dashboard at http://localhost:5173 to view:

Real-time shipment risk distribution
Active alerts and notifications
Quick statistics and KPIs

Analytics

Navigate to /analytics for:

Trend analysis with historical data
Carrier and mode performance metrics
Risk score evolution over time

Webhook Testing

Send a test shipment via webhook:

curl -X POST http://localhost:8787/api/webhooks/shipments \
  -H "Content-Type: application/json" \
  -H "x-webhook-secret: YOUR_WEBHOOK_SECRET" \
  -d '{
    "shipment": {
      "trackingId": "TEST-1001",
      "status": "in_transit",
      "origin": "Berlin, DE",
      "destination": "Munich, DE",
      "riskScore": 25
    }
  }'

Verify the shipment appears in Firestore and updates the dashboard in real-time.

🔌 API Reference

Health Check

GET /api/health

Response:

{
  "ok": true,
  "timestamp": "2026-03-18T10:30:00.000Z",
  "integrations": {
    "firestoreIngestion": true,
    "weatherAPI": true,
    "newsAPI": true
  }
}

Weather Endpoints

Endpoint	Method	Description
`/api/weather/by-city`	GET	Get weather by city name
`/api/weather/by-coords`	GET	Get weather by coordinates
`/api/weather/geocode`	GET	Convert location to coordinates
`/api/weather/forecast`	GET	Get weather forecast
`/api/routes/alternatives`	POST	Get route alternatives from backend intelligence layer

Example — Weather by City:

GET /api/weather/by-city?city=London&units=metric

Query Parameters:

city (required) — City name
units (optional) — metric, imperial, or standard (default: metric)

Example — Weather by Coordinates:

GET /api/weather/by-coords?lat=51.5074&lon=-0.1278&units=metric

Query Parameters:

lat (required) — Latitude
lon (required) — Longitude
units (optional) — Temperature units

News Endpoint

GET /api/news/logistics

Response:

{
  "articles": [
    {
      "title": "Global Shipping Disruptions Continue",
      "description": "Latest updates on supply chain issues...",
      "url": "https://example.com/article",
      "publishedAt": "2026-03-18T10:00:00Z",
      "source": { "name": "Logistics Weekly" }
    }
  ]
}

Webhook Ingestion

POST /api/webhooks/shipments

Headers:

Content-Type: application/json
X-Webhook-Timestamp: <unix-seconds>
X-Webhook-Signature: sha256=<hmac_sha256(secret, timestamp.rawBody)>

Migration compatibility (temporary):

x-webhook-secret: your_webhook_secret

Single Shipment Payload:

{
  "shipment": {
    "trackingId": "TMS-1002",
    "status": "in_transit",
    "carrier": "DHL",
    "mode": "road",
    "origin": "Hamburg, DE",
    "destination": "Cologne, DE",
    "riskScore": 31,
    "riskLevel": "low"
  }
}

Batch Shipments Payload:

{
  "shipments": [
    {
      "trackingId": "TMS-1001",
      "status": "in_transit",
      "carrier": "DHL",
      "mode": "road",
      "origin": "Berlin, DE",
      "destination": "Munich, DE",
      "riskScore": 42,
      "riskLevel": "medium"
    },
    {
      "trackingId": "TMS-1002",
      "status": "delivered",
      "carrier": "FedEx",
      "mode": "air",
      "origin": "London, UK",
      "destination": "Paris, FR",
      "riskScore": 15,
      "riskLevel": "low"
    }
  ]
}

Shipment Schema:

Field	Type	Required	Description
`trackingId`	string	✅	Unique tracking identifier
`status`	string	✅	`pending`, `in_transit`, `delivered`, `delayed`
`carrier`	string	❌	Carrier name (DHL, FedEx, UPS)
`mode`	string	❌	Transport mode: `road`, `air`, `sea`, `rail`
`origin`	string	✅	Origin location
`destination`	string	✅	Destination location
`riskScore`	number	✅	Risk score (0-100)
`riskLevel`	string	❌	`low`, `medium`, `high` (auto-calculated)

Success Response:

{
  "ok": true,
  "written": 2,
  "message": "Shipments processed successfully"
}

Error Response:

{
  "ok": false,
  "error": "Invalid webhook secret"
}

📊 Project Status

Current Implementation

Feature	Status
Real-time Firestore Subscriptions	✅ Complete
Webhook Ingestion	✅ Complete
Risk Analytics Dashboard	✅ Complete
Trend Analysis (Firestore Aggregates)	✅ Complete
Weather API Integration	✅ Complete
News API Integration	✅ Complete
Settings Persistence	✅ Complete
Firebase Authentication	✅ Complete
Multi-carrier Support	✅ Complete
Session Timeout Controls	✅ Complete
Route Intelligence Recommendations	✅ Complete
Request Retry + Timeout Layer	✅ Complete
Frontend Error Boundary	✅ Complete
CI Workflows (Frontend + Backend)	✅ Complete

🐛 Troubleshooting

Backend Won't Start

Error: Cannot find module 'firebase-admin'

Solution:

cd backend
npm install

Webhook Returns 401 Unauthorized

Error: Invalid webhook secret

Solution:

Verify x-webhook-secret header matches WEBHOOK_SECRET in backend/.env
Ensure secret is at least 32 characters
Check for extra spaces or line breaks in the secret

Firestore Permission Denied

Error: Missing or insufficient permissions

Solution:

Check Firebase security rules
Verify user is authenticated
Ensure service account has Firestore read/write permissions
Deploy the repository rules file: firebase deploy --only firestore:rules

Frontend Can't Connect to Backend

Error: Network Error or CORS error

Solution:

Verify backend is running on port 8787
Check VITE_BACKEND_URL=http://localhost:8787 in frontend .env
Verify ALLOWED_ORIGINS in backend/.env includes http://localhost:5173

Weather/News API Not Working

Error: 401 Unauthorized or 403 Forbidden

Solution:

Verify API keys are correct in backend/.env
Check API key restrictions in provider dashboards
Ensure API usage limits haven't been exceeded
Test API keys directly: curl "https://api.openweathermap.org/data/2.5/weather?q=London&appid=YOUR_KEY"

🔮 Future Enhancements

🔒 Security

Best Practices

🔐 Never commit credentials — Keep .env files out of version control
🔑 Service account protection — Ensure backend/service-account.json is gitignored
🔄 Rotate secrets regularly — Update webhook secret every 90 days
🔒 Use HTTPS in production — Always use SSL/TLS certificates
🚪 Restrict CORS — Limit ALLOWED_ORIGINS to your frontend domain only
🛡️ Firebase security rules — Implement proper read/write restrictions
🔐 Environment variables — Use secret management in production (Railway, Render, etc.)
🚫 API key restrictions — Restrict keys by domain/IP in provider dashboards

Security Checklist

.env and backend/.env are in .gitignore
Service account JSON is not committed to repository
Webhook secret is strong (48+ characters, generated cryptographically)
CORS is restricted to frontend domain in production
HTTPS is enabled for production deployment
Firebase security rules enforce authentication
API keys have domain/IP restrictions configured
Rate limiting is enabled on webhook endpoint

📄 License

This project is licensed under the MIT License.

See LICENSE for full terms.

👨‍💻 Author

LegendarySumit

GitHub: @LegendarySumit
Project Repository: ShipGuard AI
Live Demo: Launch Platform

🚢 Revolutionizing Logistics with Real-time Intelligence

Built with React, Node.js, Firebase, and dedication to supply chain excellence

⭐ Star this repo if you find it helpful!

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.github/workflows		.github/workflows
backend		backend
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
vercel.json		vercel.json
vite.config.js		vite.config.js

Folders and files

Latest commit

History

Repository files navigation

🚢 ShipGuard AI

📖 About

✨ Features

🛠️ Tech Stack

Frontend

Backend

Monitoring & Quality

Database & Authentication

External Integrations

📁 Project Structure

🚀 Quick Start

Prerequisites

Installation

Configuration

Generate Webhook Secret

Deploy Firestore Security Rules

Run the Application

Build for Production

📚 Usage

Dashboard

Analytics

Webhook Testing

🔌 API Reference

Health Check

Weather Endpoints

News Endpoint

Webhook Ingestion

📊 Project Status

Current Implementation

🐛 Troubleshooting

Backend Won't Start

Webhook Returns 401 Unauthorized

Firestore Permission Denied

Frontend Can't Connect to Backend

Weather/News API Not Working

🔮 Future Enhancements

🔒 Security

Best Practices

Security Checklist

📄 License

👨‍💻 Author

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages