JanSahay

Project Title & Taglines

• Project Name: CivicAid Dispatch
• One-Line Pitch (Under 100 characters): A simulation-first, real-time coordination and failure-recovery engine for perishable crisis aid.
• Short Summary (For preview cards): CivicAid Dispatch connects food/medical donors, volunteer riders, and relief shelters through a deterministic logistics engine that automatically splits large batches, blocks unsafe/expired deliveries, revokes ghost riders, and reroutes drivers mid-transit when shelters reach capacity. Full Project Description (Copy-Paste for Main Submission Form) Inspiration & The Problem In disaster relief and civic aid operations, coordinating perishable food and fragile medical supplies is a race against the clock. Standard delivery platforms treat a box of expiring medicine or 180 hot meals the same as a retail parcel. In the real world, relief logistics fail when:
• A restaurant donates 180 meals, but individual volunteer riders can only carry 40 meals at a time.
• Raw rations or temperature-sensitive medicines are sent to shelters that lack clean water, cooking fuel, or refrigeration.
• A volunteer rider claims a pickup and goes offline ("ghosting"), leaving perishable aid to spoil.
• A shelter reaches maximum capacity while a rider is already in transit. We built CivicAid Dispatch to move beyond basic CRUD tracking and solve the hardest part of humanitarian logistics: automated safety validation and real-time mid-transit failure recovery. What It Does CivicAid Dispatch is a real-time coordination platform uniting Donors, Volunteer Riders, Shelters, and Operations Admins. Instead of relying on manual dispatching, the platform enforces strict backend logistics rules across four core workflows:
• Dynamic Batch Splitting & Greedy Matching: When a donor posts a large batch (e.g., 180 cooked meals), the matching engine automatically splits the load across multiple available riders based on vehicle capacity (e.g., 40, 40, 40, 40, and 20 meals) and matches them to open shelters ranked by urgency, ETA, and distance.
• Hard Safety & Facility Filtering: Before any route is created, the engine verifies facility compatibility (e.g., blocking raw rations if a shelter lacks clean water and cooking fuel, or blocking medicine without cold-chain refrigeration). It also enforces an expiry safety buffer (now + travelTime + safetyBuffer < expiresAt) so spoiled or impossible deliveries are rejected upfront.
• Anti-Ghost-Rider Watchdog: Riders must maintain active heartbeats and claim tasks within a strict time window. If a rider goes unresponsive/AFK, a server-side watchdog automatically revokes the reservation, returns the quantity to the pool, and reassigns the task to an active rider.
• Mid-Transit Rerouting & Recovery: If a shelter suddenly clicks Mark Full or closes while a rider is already en route, the system cancels unstarted tasks and dynamically recalculates a new destination from the rider's last known coordinates. If no compatible shelter can be reached before the batch expires, it flags RECOVERY_REQUIRED for immediate human intervention rather than silently delivering spoiled aid.
• Interactive Simulation Control Panel: Built with a simulation-first philosophy, the Operations Dashboard features one-click controls to advance the server clock, simulate AFK riders, trigger tight-expiry blocks, and inspect an append-only audit timeline explaining why every routing or rejection decision was made. How We Built It (Architecture & Tech Stack) We engineered CivicAid Dispatch using a strict 10-Layer Build Architecture inside a TypeScript monorepo, ensuring the backend remains the single authority for safety, capacity, and state transitions:
• Shared Domain Contract (packages/shared): Shared TypeScript enums, strict delivery/batch state machines, pure logistics functions, and Zod validation schemas shared across frontend and backend.
• Backend (apps/api): Node.js, Express, and TypeScript backed by MongoDB and Mongoose. We utilized 2dsphere geospatial indexes for spatial queries and MongoDB Multi-Document Transactions to ensure claiming deliveries, splitting quantities, and marking shelters full happen atomically without race conditions.
• Real-Time Transport: Socket.IO rooms (operations, rider:, shelter:, batch:) broadcast live state changes, acting as cache-invalidation signals for TanStack Query so the UI always reflects authoritative database state.
• Frontend (apps/web): React, Vite, Tailwind CSS, and shadcn/ui for the operational command center, paired with Leaflet (react-leaflet) and OpenStreetMap to visualize pickup points, color-coded shelter statuses, live rider locations, and rerouted polylines.
• Testing & Quality: Unit and API test suites powered by Vitest, Supertest, and MongoDB Memory Server. Challenges We Ran Into
• Preventing Double-Claims & Race Conditions: Ensuring two riders couldn't claim the last remaining portion of a batch simultaneously, or that a rider couldn't complete a delivery to a shelter that just marked itself full. Solving this required wrapping multi-model updates inside MongoDB transactions and enforcing strict state-transition guards.
• Mid-Transit ETA Recalculation: When a shelter closes mid-delivery, rerouting cannot be calculated from the original donor pickup point—it has to calculate travel time from the rider's current in-transit coordinates while re-verifying facility compatibility and the batch's countdown timer.
• Making Complex Rules Explainable: A backend that blocks a delivery looks like a bug unless the operator knows why. We built a structured OperationEvent audit log and Decision Inspector so every rejection or reroute surfaces a clear, human-readable reason in the UI. Accomplishments That We're Proud Of
• Isolating our entire matching, splitting, and recovery engine into pure, deterministic functions before touching the UI, allowing us to prove all four crisis failure scenarios reliably.
• Building a repeatable, one-click simulation engine with a controllable server clock so anyone testing the app can witness expiry blocks and heartbeat timeouts without waiting hours in real time. What's Next for CivicAid Dispatch
• Integrating a live turn-by-turn routing engine (OSRM / Mapbox) behind our travel-time estimation abstraction.
• Upgrading our greedy matching heuristic to a multi-stop vehicle routing optimization solver.
• Replacing the demo role-switcher with production JWT authentication and SMS/WhatsApp webhook alerts for field riders in low-connectivity zones. Quick Tags / Technologies List (For Form Dropdowns) TypeScript React Vite Node.js Express MongoDB Mongoose Socket.IO TailwindCSS shadcn/ui TanStack Query Leaflet Zod Vitest