SecureParcel is a real-time, highly secure campus locker management and parcel delivery platform. It bridges the gap between students, delivery couriers, and campus security through a unified ecosystem. Built with a decoupled microservice-like architecture, SecureParcel delivers an ultra-smooth mobile experience backed by a resilient Node.js infrastructure, real-time WebSocket synchronization, and a smart cascading AI assistant.
Whether managing high-volume package influxes or ensuring airtight parcel handovers via dynamic, time-sensitive QR codes, SecureParcel is designed for scale, speed, and absolute security.
- Student Hub: Real-time package tracking, interactive locker map, instant AI chat support, and dynamic retrieval QR generation.
- Delivery Courier Station: Streamlined parcel registration, intelligent locker allocation, and integrated photo-proof of delivery.
- Guard Verification Station: Dedicated scanning interface with instant JWT validation and automated locker door release signaling.
- Time-Sensitive QR Codes: Retrieval codes auto-regenerate every 30 seconds with encrypted payload signatures, preventing unauthorized screenshot sharing.
- Biometric Authentication: Native FaceID/TouchID integration ensures that only the authorized user can view secure pickup credentials.
- Defense-in-Depth Backend: Express APIs hardened with rate limiters, Helmet headers, CORS filters, and strict role-based access control (RBAC).
- Cascading LLM Architecture: Designed for 100% uptime with automated fallback routing (Groq ⚡️ → OpenAI GPT-4o 🧠 → Google Gemini Pro 🌐).
- Context-Aware Responses: The AI reads real-time locker occupancy and parcel state to provide highly accurate, contextual assistance to users.
- Offline Mock Fallbacks: Built-in smart NLP failovers ensure the assistant remains functional even during API outages.
- Instant Synchronization: Powered by Socket.io and Firebase Firestore, state changes (like a parcel deposit) instantly push to all connected clients.
- Optimized Offline Experience: Zustand state management seamlessly handles network drops with 1.5s safety timeouts, loading rich cached data environments to prevent application hangs.
SecureParcel leverages a modern, distributed topology ensuring clean separation of concerns.
graph TD
subgraph Mobile_Application ["📱 React Native Expo Client"]
SP[Student Portal]
DP[Delivery Portal]
GP[Guard Scan Station]
Zustand[Zustand Store Manager]
end
subgraph Native_Sensors ["🛠 Hardware / Native Bindings"]
Bio[Biometric Auth]
Cam[Expo Camera Scanner]
Hap[Haptic Engine]
end
subgraph Backend_Infrastructure ["⚙️ Node.js + TS Express Server"]
API[Secure REST API]
WS[Socket.io Real-time Server]
AuthMid[Firebase JWT Auth]
AIEng[AI Orchestrator]
end
subgraph Cloud_Providers ["☁️ Cloud Services"]
FB[Firebase Firestore & Auth]
Push[Expo Push Notifications]
LLM[Groq / OpenAI / Gemini]
end
%% Client Internals
SP --> Zustand
DP --> Zustand
GP --> Zustand
Zustand --> Bio
GP --> Cam
Zustand --> Hap
%% Network flows
Mobile_Application <--> |HTTPS + JWT| API
Mobile_Application <--> |WebSocket| WS
%% Cloud flows
API <--> FB
WS <--> FB
API --> Push
API <--> AIEng
AIEng <--> LLM
- Framework: React Native, Expo SDK 54
- Language: TypeScript
- State Management: Zustand (Multi-store architecture)
- Animations & UI: React Native Reanimated, Custom Glassmorphism
- Integrations: Expo Camera, Local Authentication, Haptics
- Environment: Node.js
- Framework: Express.js (TypeScript)
- Real-time Engine: Socket.io
- Authentication: Firebase Admin SDK (JWT Validation)
- Security: Helmet, express-rate-limit, cors
- Database: Firebase Firestore
- Notifications: Expo Push Notifications Servers
- AI Providers: Groq, OpenAI, Google Gemini
- Crash Reporting: Sentry SDK
- User Analytics: Mixpanel
- Monetization/IAP: RevenueCat
- Node.js (v18+)
- Xcode (for iOS builds) or Android Studio (for Android builds)
- Firebase Project Setup
Important
This app uses native modules (expo-notifications, react-native-purchases, @sentry/react-native, expo-local-authentication, etc.) and cannot run in Expo Go. A custom development build via expo-dev-client is required.
git clone https://github.com/Ishiezz/SecureParcel.git
cd SecureParcelDuplicate the provided .env.example to .env in both the root directory and the backend directory.
Backend Configuration (backend/.env):
PORT=5000
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_CLIENT_EMAIL=your-service-account-email
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
# AI Configuration
GROQ_API_KEY=your-groq-key
OPENAI_API_KEY=your-openai-key
GEMINI_API_KEY=your-gemini-keyFrontend Configuration (.env):
EXPO_PUBLIC_API_URL=http://localhost:5000
EXPO_PUBLIC_SENTRY_DSN=your-sentry-dsn
EXPO_PUBLIC_MIXPANEL_TOKEN=your-mixpanel-token
EXPO_PUBLIC_RC_APPLE_KEY=your-revenuecat-apple-key
EXPO_PUBLIC_RC_GOOGLE_KEY=your-revenuecat-google-keyStart the Node.js Backend Server:
cd backend
npm install
npm run devServer runs on http://localhost:5000 with hot-reloading.
Build & Run the React Native App (First Time):
Because the app uses native modules, you must compile a development build rather than using Expo Go.
# From the project root
npm install
# iOS (requires Xcode)
npx expo run:ios
# Android (requires Android Studio)
npx expo run:androidSubsequent Runs (after first build):
npx expo start --dev-clientOpens a dev server — the installed dev build on your device/simulator will connect automatically for fast refresh.
Type Checking: Run strict TypeScript validation across the project:
npx tsc --noEmitProduction Build (Backend): Compile the backend for production deployment:
cd backend
npm run build
npm start