How pmcgee-personal/parcel-tracker works
Parcel Tracker is a personal shipment dashboard. Users register tracking numbers in the frontend; the tracking handler retrieves carrier data and stores shipment details and events. Carrier webhooks are verified and update those records, while listing reads shipment and event data for the paginated dashboard and expandable timelines. The README documents the API, storage, and hosting topology; source excerpts confirm key handler, helper, and component relationships. Some backend handlers and shared helpers are indexed but not excerpted, so their internal call details are not expanded.
Main entry points: webhook/index.js Carrier webhook · track/index.js Register shipment · App.jsx Dashboard state · list/index.js Paginated listing
Components 26
Dashboard
- Dashboard state
frontend/src/App.jsx - Shipment form
frontend/src/components/ShipmentForm.jsx - Shipment cards
frontend/src/components/ShipmentCard.jsx - Event timeline
frontend/src/components/EventTimeline.jsx - Delivery drift
frontend/src/DriftIndicator.jsx
API workflows
- Register shipment
src/handlers/track/index.js - Carrier webhook
src/handlers/webhook/index.js - Paginated listing
src/handlers/list/index.js - Shipment deletion
src/handlers/delete/index.js - Staleness monitor
src/handlers/monitor-staleness/index.js
Backend helpers
- DynamoDB access
src/lib/ddb.js - Event mapping
src/lib/events.js - Signature verification
src/lib/verifyShipEngineSignature.js - Date handling
src/lib/dates.js - Retry helpers
src/lib/dynamodbRetry.js - HTTP fetch retry
src/lib/fetchWithRetry.js - Operation tracking
src/lib/operationTracker.js - Push notifications
src/lib/ntfy.js
Shipment data
- Shipments table
template.yaml - Events table
template.yaml
Other components
- Dashboard user
- API Gateway
- ShipEngine API
- Carrier services
- ShipEngine JWKS
- S3 and CloudFront
Connections 39
- Dashboard user → Dashboard state: uses
README.md - Dashboard state → Shipment form: renders
frontend/src/App.jsx - Dashboard state → Shipment cards: renders
frontend/src/App.jsx - Shipment cards → Event timeline: renders
frontend/src/components/ShipmentCard.jsx - Shipment cards → Delivery drift: renders
frontend/src/components/ShipmentCard.jsx - Dashboard state → API Gateway: requests
README.md - API Gateway → Register shipment: routes registration
README.md - API Gateway → Paginated listing: routes listing
README.md - API Gateway → Carrier webhook: routes events
README.md - Shipment form → Dashboard state: submits input
frontend/src/App.jsx - Register shipment → ShipEngine API: fetches tracking
src/handlers/track/index.js - Register shipment → DynamoDB access: uses
src/handlers/track/index.js - Register shipment → Event mapping: maps events
src/handlers/track/index.js - Register shipment → Date handling: normalizes dates
src/handlers/track/index.js - Register shipment → HTTP fetch retry: retries requests
src/handlers/track/index.js - Register shipment → Shipments table: writes shipment
README.md - Register shipment → Events table: writes timeline
README.md - Carrier services → Carrier webhook: sends updates
README.md - Carrier webhook → Signature verification: verifies payload
src/handlers/webhook/index.js - Signature verification → ShipEngine JWKS: fetches keys
src/lib/verifyShipEngineSignature.js - Carrier webhook → DynamoDB access: reads and writes
src/handlers/webhook/index.js - Carrier webhook → Event mapping: maps events
src/handlers/webhook/index.js - Carrier webhook → Date handling: normalizes dates
src/handlers/webhook/index.js - Carrier webhook → Retry helpers: retries writes
src/handlers/webhook/index.js - Carrier webhook → Operation tracking: tracks processing
src/handlers/webhook/index.js - Carrier webhook → Shipments table: updates status
README.md - Carrier webhook → Events table: stores events
README.md - Carrier webhook → Push notifications: sends alerts
src/handlers/webhook/index.js - Paginated listing → DynamoDB access: queries data
src/handlers/list/index.js - Paginated listing → Shipments table: reads shipments
README.md - Paginated listing → Events table: reads timelines
README.md - Paginated listing → API Gateway: returns page
README.md - Dashboard state → Shipment cards: displays results
README.md - Shipment deletion → DynamoDB access: deletes records
src/handlers/delete/index.js - Shipment deletion → ShipEngine API: stops tracking
src/handlers/delete/index.js - Shipment deletion → Push notifications: alerts failures
src/handlers/delete/index.js - Staleness monitor → DynamoDB access: checks records
src/handlers/monitor-staleness/index.js - Staleness monitor → Push notifications: sends alerts
src/handlers/monitor-staleness/index.js - Dashboard state → S3 and CloudFront: is hosted by
README.md