ParcelPath

Consumer

Original Idea

Package Delivery Aggregator A mobile app that tracks all your incoming packages from any carrier in one timeline with delivery window predictions.

Product Requirements Document (PRD): ParcelPath

Version: 1.0 (2026 Edition)
Status: Final
Product Manager: [Senior PM Name]

1. Executive Summary

ParcelPath is a next-generation package delivery aggregator designed to solve the fragmentation of modern e-commerce logistics. By centralizing tracking data from over 1,200 carriers into a single, ML-enhanced timeline, ParcelPath provides users with "The Truth in Delivery." Leveraging privacy-first email scanning and advanced spatial-temporal machine learning, the app provides delivery windows that are more accurate than carrier estimates, reducing "delivery anxiety" and package theft.

2. Problem Statement

Consumers today order from multiple platforms (Amazon, Etsy, direct-to-consumer) using various carriers (UPS, FedEx, DHL, regional couriers). Managing this requires checking multiple apps/emails, leading to:

  • Fragmentation: No single view of all incoming goods.
  • Inaccuracy: Carrier ETAs are often "optimistic" and fail to account for local micro-events.
  • Security Risks: Unpredictable arrival times lead to packages sitting on porches, increasing theft risk.
  • Manual Burden: Users must manually copy/paste tracking numbers from emails into various trackers.

3. Goals & Success Metrics

  • User Retention: 40% Day-30 retention for frequent shoppers.
  • Accuracy Lift: ML-predicted delivery windows to be 25% more accurate than standard carrier ETAs.
  • Automation Rate: 85% of tracking numbers should be captured via auto-scanning (Gmail/Outlook) without manual entry.
  • Performance: App launch to "Status Visible" in under 1.5 seconds.

4. User Personas

  1. "The Online Shopaholic" (Sarah): Orders 5-10 items weekly. Needs a unified view to ensure she's home for high-value deliveries.
  2. "The Side-Hustler" (Marcus): Small business owner receiving supplies. Needs precise timing to manage his production schedule.
  3. "The Security-Conscious Suburbanite" (Linda): Lives in an area with high porch piracy. Needs "Two Stops Away" alerts and photo proof of delivery.

5. User Stories

  • As a user, I want to link my Gmail account so that tracking numbers are automatically pulled into my timeline without manual effort.
  • As a user, I want to see a predicted arrival window based on real-time traffic and driver behavior so I can plan my day.
  • As a user, I want to see a live map of my package when it is "out for delivery" so I know exactly when to walk to my front door.
  • As a user, I want to view a photo of where the package was left so I can find it if it was hidden by the driver.

6. Functional Requirements

6.1. Unified Timeline & Tracking

  • Multi-Carrier Support: Integration with 1,200+ carriers via AfterShip API.
  • Chronological Sorting: Automatic sorting of all packages by "Next Arrival."
  • Manual Entry: Auto-detection of carrier based on tracking number regex.

6.2. Privacy-First Email Scanning

  • OAuth 2.0 Integration: Secure linking for Gmail and Microsoft Graph.
  • Read-Scan-Discard Pipeline: Scan only for logistics-related keywords (Schema.org/JSON-LD). Never store the body of an email.
  • CASA Compliance: Adherence to Google’s Cloud Application Security Assessment standards.

6.3. Predictive ML Engine (TransPDT)

  • Predictive Windows: Use a Transformer-based model to analyze historical route performance and current micro-events (weather, labor strikes).
  • Confidence Scores: Show "90% probability" windows for arrival times.

6.4. Real-time Mapping & Notifications

  • Live Activities (iOS): Real-time progress bar and ETA on the Lock Screen/Dynamic Island.
  • Mapbox Integration: Smooth "snake" route animations using line-gradient rendering.
  • Two-Stop Alert: Proactive notification when the courier is within a 2-block radius.

7. Technical Requirements

7.1. Tech Stack (2026 Standards)

  • Frontend: React Native v0.83.x (New Architecture/Fabric enabled by default).
  • Backend: NestJS v11.1.12 running on Node.js LTS (Express 5 for path-traversal security).
  • Database: PostgreSQL v18 (utilizing io_uring for high-volume I/O) + TimescaleDB extension for tracking history.
  • Real-time: Firebase Cloud Messaging (FCM) + Apple Push Notification service (APNs) for Live Activities.

7.2. Core Integrations

  • Carrier Data: AfterShip API (Standardized 33 sub-statuses).
  • Email Access: Gmail API (Restricted Scopes) & Microsoft Graph API.
  • Maps: Mapbox SDK with GPU-accelerated rendering.
  • Security: AWS KMS for Envelope Encryption of OAuth tokens.

8. Data Model

| Entity | Attributes | Notes | | :--- | :--- | :--- | | User | id (UUIDv7), email, encrypted_oauth_token, settings_jsonb | UUIDv7 for time-ordered indexing. | | Shipment | id (UUIDv7), user_id, tracking_num, carrier_id, status | Core object for tracking. | | TrackingEvent | id (BigInt), shipment_id, status_code, timestamp, location_geom | Partitioned by month in PostgreSQL. | | ML_Prediction | shipment_id, predicted_window_start, predicted_window_end, confidence | Updated every 15 mins during transit. |

9. API Specification (Key Endpoints)

9.1. POST /v1/sync/email

  • Input: OAuth Authorization Code.
  • Process: Triggers "Read-Scan-Discard" pipeline to extract tracking numbers.
  • Output: 202 Accepted (Background task started).

9.2. GET /v1/shipments/timeline

  • Response: 
    {
  "items": [{
    "tracking_number": "1Z999...",
    "carrier": "UPS",
    "current_status": "OUT_FOR_DELIVERY",
    "ml_eta": "2026-05-20T14:30:00Z",
    "confidence": 0.92
  }]
}

10. UI/UX Requirements

  • The "Arrivals" Hub: A clean, vertical timeline with brand-colored icons for each carrier.
  • Map Interaction: Swiping up on a shipment card expands into a full-screen Mapbox view with real-time driver interpolation.
  • Empty State: One-tap "Connect Email" button with clear privacy disclosures about what is not scanned.
  • Dark Mode: Native support for system-level dark mode toggles.

11. Non-Functional Requirements

  • Security: AES-256-GCM encryption for all PII. OAuth tokens must be managed via Envelope Encryption.
  • Scalability: Horizontal scaling of NestJS microservices; PostgreSQL sharding via Citus if user base exceeds 1M.
  • Privacy: No retention of email bodies; logs must be purged of PII every 30 days.
  • Accessibility: WCAG 2.1 Level AA compliance; full support for screen readers and high-contrast modes.

12. Out of Scope

  • Returns Management: (Phase 2 feature) Printing return labels.
  • Social Shipping: No sharing tracking links with friends in v1.
  • Direct Carrier Communication: App will not facilitate direct chat with drivers in v1.

13. Risks & Mitigations

  • Risk: Google/Microsoft revoke API access due to "Limited Use" policy changes.
    • Mitigation: Pursue annual CASA Tier 2 audits early; prioritize JSON-LD extraction to stay within privacy guidelines.
  • Risk: ML models provide inaccurate windows during extreme peak seasons (Black Friday).
    • Mitigation: Fall back to carrier ETAs if ML confidence score is <60%.

14. Implementation Tasks

Phase 1: Project Setup & Infrastructure

  • [ ] Initialize React Native 0.83 project with Fabric/TurboModules enabled.
  • [ ] Set up NestJS 11.1.12 backend with Express 5.
  • [ ] Configure PostgreSQL 18 with UUID v7 as primary keys.
  • [ ] Set up AWS KMS for secure token management.

Phase 2: Core Tracking & API

  • [ ] Integrate AfterShip API for multi-carrier normalization.
  • [ ] Implement manual tracking number entry with auto-detection logic.
  • [ ] Build the Shipment Timeline UI (Chronological view).
  • [ ] Implement Webhook listeners for real-time status updates.

Phase 3: Email Sync (The "Read-Scan-Discard" Pipeline)

  • [ ] Implement OAuth 2.0 flow for Gmail and Microsoft Graph.
  • [ ] Build the serverless "Read-Scan-Discard" function to extract tracking numbers.
  • [ ] Add regex and JSON-LD logic for shipment discovery.
  • [ ] Complete CASA security documentation for Google verification.

Phase 4: Machine Learning & Mapping

  • [ ] Deploy TransPDT model on AWS SageMaker for ETA predictions.
  • [ ] Integrate Mapbox SDK with line-gradient route rendering.
  • [ ] Implement Turf.js for smooth marker interpolation between GPS pings.
  • [ ] Build Live Activities for iOS using ActivityKit.

Phase 5: Polish & Security

  • [ ] Implement AVIF image caching for Proof-of-Delivery photos.
  • [ ] Add Carbon Footprint calculation using Climatiq API (ISO 14083).
  • [ ] Perform penetration testing on OAuth token storage.
  • [ ] Finalize Dark Mode and Accessibility audit.