# pmcgee-personal/parcel-tracker architecture

> Architecture diagram of the GitHub repository pmcgee-personal/parcel-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pmcgee-personal/parcel-tracker
- Repository: https://github.com/pmcgee-personal/parcel-tracker

## Overview

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: [`src/handlers/webhook/index.js`](https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/handlers/webhook/index.js) (Carrier webhook), [`src/handlers/track/index.js`](https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/handlers/track/index.js) (Register shipment), [`frontend/src/App.jsx`](https://github.com/pmcgee-personal/parcel-tracker/blob/main/frontend/src/App.jsx) (Dashboard state), [`src/handlers/list/index.js`](https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/handlers/list/index.js) (Paginated listing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard"]
  node_app["Dashboard state<br/>[App.jsx]"]
  node_form["Shipment form<br/>[ShipmentForm.jsx]"]
  node_card["Shipment cards<br/>[ShipmentCard.jsx]"]
  node_timeline["Event timeline<br/>[EventTimeline.jsx]"]
  node_drift["Delivery drift<br/>[DriftIndicator.jsx]"]
end

subgraph group_api["API workflows"]
  node_track["Register shipment<br/>[index.js]"]
  node_webhook["Carrier webhook<br/>[index.js]"]
  node_list["Paginated listing<br/>[index.js]"]
  node_delete["Shipment deletion<br/>[index.js]"]
  node_staleness["Staleness monitor<br/>[index.js]"]
end

subgraph group_shared["Backend helpers"]
  node_helpers["DynamoDB access<br/>[ddb.js]"]
  node_event_mapping["Event mapping<br/>[events.js]"]
  node_signature["Signature verification"]
  node_date_helpers["Date handling<br/>[dates.js]"]
  node_retry_helpers["Retry helpers<br/>[dynamodbRetry.js]"]
  node_fetch_retry["HTTP fetch retry<br/>[fetchWithRetry.js]"]
  node_operation["Operation tracking"]
  node_notifications["Push notifications<br/>[ntfy.js]"]
end

subgraph group_data["Shipment data"]
  node_shipments[("Shipments table<br/>[template.yaml]")]
  node_events_table[("Events table<br/>[template.yaml]")]
end

node_user(("Dashboard user"))
node_api_gateway["API Gateway"]
node_shipengine["ShipEngine API"]
node_carriers["Carrier services"]
node_jwks["ShipEngine JWKS"]
node_frontend_host["S3 and CloudFront"]

node_user -->|"uses"| node_app
node_app -->|"renders"| node_form
node_app -->|"renders"| node_card
node_card -->|"renders"| node_timeline
node_card -->|"renders"| node_drift
node_app -->|"requests"| node_api_gateway
node_api_gateway -->|"routes registration"| node_track
node_api_gateway -->|"routes listing"| node_list
node_api_gateway -->|"routes events"| node_webhook
node_form -.->|"submits input"| node_app
node_track -->|"fetches tracking"| node_shipengine
node_track -->|"uses"| node_helpers
node_track -->|"maps events"| node_event_mapping
node_track -->|"normalizes dates"| node_date_helpers
node_track -->|"retries requests"| node_fetch_retry
node_track -->|"writes shipment"| node_shipments
node_track -->|"writes timeline"| node_events_table
node_carriers -->|"sends updates"| node_webhook
node_webhook -->|"verifies payload"| node_signature
node_signature -->|"fetches keys"| node_jwks
node_webhook -->|"reads and writes"| node_helpers
node_webhook -->|"maps events"| node_event_mapping
node_webhook -->|"normalizes dates"| node_date_helpers
node_webhook -->|"retries writes"| node_retry_helpers
node_webhook -->|"tracks processing"| node_operation
node_webhook -->|"updates status"| node_shipments
node_webhook -->|"stores events"| node_events_table
node_webhook -->|"sends alerts"| node_notifications
node_list -->|"queries data"| node_helpers
node_list -->|"reads shipments"| node_shipments
node_list -->|"reads timelines"| node_events_table
node_list -->|"returns page"| node_api_gateway
node_app -->|"displays results"| node_card
node_delete -->|"deletes records"| node_helpers
node_delete -->|"stops tracking"| node_shipengine
node_delete -->|"alerts failures"| node_notifications
node_staleness -->|"checks records"| node_helpers
node_staleness -->|"sends alerts"| node_notifications
node_app -->|"is hosted by"| node_frontend_host

click node_app "https://github.com/pmcgee-personal/parcel-tracker/blob/main/frontend/src/App.jsx"
click node_form "https://github.com/pmcgee-personal/parcel-tracker/blob/main/frontend/src/components/ShipmentForm.jsx"
click node_card "https://github.com/pmcgee-personal/parcel-tracker/blob/main/frontend/src/components/ShipmentCard.jsx"
click node_timeline "https://github.com/pmcgee-personal/parcel-tracker/blob/main/frontend/src/components/EventTimeline.jsx"
click node_drift "https://github.com/pmcgee-personal/parcel-tracker/blob/main/frontend/src/DriftIndicator.jsx"
click node_track "https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/handlers/track/index.js"
click node_webhook "https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/handlers/webhook/index.js"
click node_list "https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/handlers/list/index.js"
click node_delete "https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/handlers/delete/index.js"
click node_staleness "https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/handlers/monitor-staleness/index.js"
click node_shipments "https://github.com/pmcgee-personal/parcel-tracker/blob/main/template.yaml"
click node_events_table "https://github.com/pmcgee-personal/parcel-tracker/blob/main/template.yaml"
click node_helpers "https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/lib/ddb.js"
click node_event_mapping "https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/lib/events.js"
click node_signature "https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/lib/verifyShipEngineSignature.js"
click node_date_helpers "https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/lib/dates.js"
click node_retry_helpers "https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/lib/dynamodbRetry.js"
click node_fetch_retry "https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/lib/fetchWithRetry.js"
click node_operation "https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/lib/operationTracker.js"
click node_notifications "https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/lib/ntfy.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_form,node_card,node_timeline,node_drift,node_user toneBlue
class node_track,node_webhook,node_list,node_delete,node_staleness toneAmber
class node_helpers,node_event_mapping,node_signature,node_date_helpers,node_retry_helpers,node_fetch_retry,node_operation,node_notifications,node_api_gateway,node_shipengine toneMint
class node_shipments,node_events_table toneRose
class node_carriers,node_jwks,node_frontend_host toneIndigo
```

## Components

### Dashboard

- [Dashboard state](https://github.com/pmcgee-personal/parcel-tracker/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Shipment form](https://github.com/pmcgee-personal/parcel-tracker/blob/main/frontend/src/components/ShipmentForm.jsx): `frontend/src/components/ShipmentForm.jsx`
- [Shipment cards](https://github.com/pmcgee-personal/parcel-tracker/blob/main/frontend/src/components/ShipmentCard.jsx): `frontend/src/components/ShipmentCard.jsx`
- [Event timeline](https://github.com/pmcgee-personal/parcel-tracker/blob/main/frontend/src/components/EventTimeline.jsx): `frontend/src/components/EventTimeline.jsx`
- [Delivery drift](https://github.com/pmcgee-personal/parcel-tracker/blob/main/frontend/src/DriftIndicator.jsx): `frontend/src/DriftIndicator.jsx`

### API workflows

- [Register shipment](https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/handlers/track/index.js): `src/handlers/track/index.js`
- [Carrier webhook](https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/handlers/webhook/index.js): `src/handlers/webhook/index.js`
- [Paginated listing](https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/handlers/list/index.js): `src/handlers/list/index.js`
- [Shipment deletion](https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/handlers/delete/index.js): `src/handlers/delete/index.js`
- [Staleness monitor](https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/handlers/monitor-staleness/index.js): `src/handlers/monitor-staleness/index.js`

### Backend helpers

- [DynamoDB access](https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/lib/ddb.js): `src/lib/ddb.js`
- [Event mapping](https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/lib/events.js): `src/lib/events.js`
- [Signature verification](https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/lib/verifyShipEngineSignature.js): `src/lib/verifyShipEngineSignature.js`
- [Date handling](https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/lib/dates.js): `src/lib/dates.js`
- [Retry helpers](https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/lib/dynamodbRetry.js): `src/lib/dynamodbRetry.js`
- [HTTP fetch retry](https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/lib/fetchWithRetry.js): `src/lib/fetchWithRetry.js`
- [Operation tracking](https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/lib/operationTracker.js): `src/lib/operationTracker.js`
- [Push notifications](https://github.com/pmcgee-personal/parcel-tracker/blob/main/src/lib/ntfy.js): `src/lib/ntfy.js`

### Shipment data

- [Shipments table](https://github.com/pmcgee-personal/parcel-tracker/blob/main/template.yaml): `template.yaml`
- [Events table](https://github.com/pmcgee-personal/parcel-tracker/blob/main/template.yaml): `template.yaml`

### Other components

- **Dashboard user**
- **API Gateway**
- **ShipEngine API**
- **Carrier services**
- **ShipEngine JWKS**
- **S3 and CloudFront**

## Connections

- Dashboard user → Dashboard state: uses (evidence: `README.md`)
- Dashboard state → Shipment form: renders (evidence: `frontend/src/App.jsx`)
- Dashboard state → Shipment cards: renders (evidence: `frontend/src/App.jsx`)
- Shipment cards → Event timeline: renders (evidence: `frontend/src/components/ShipmentCard.jsx`)
- Shipment cards → Delivery drift: renders (evidence: `frontend/src/components/ShipmentCard.jsx`)
- Dashboard state → API Gateway: requests (evidence: `README.md`)
- API Gateway → Register shipment: routes registration (evidence: `README.md`)
- API Gateway → Paginated listing: routes listing (evidence: `README.md`)
- API Gateway → Carrier webhook: routes events (evidence: `README.md`)
- Shipment form → Dashboard state: submits input (evidence: `frontend/src/App.jsx`)
- Register shipment → ShipEngine API: fetches tracking (evidence: `src/handlers/track/index.js`)
- Register shipment → DynamoDB access: uses (evidence: `src/handlers/track/index.js`)
- Register shipment → Event mapping: maps events (evidence: `src/handlers/track/index.js`)
- Register shipment → Date handling: normalizes dates (evidence: `src/handlers/track/index.js`)
- Register shipment → HTTP fetch retry: retries requests (evidence: `src/handlers/track/index.js`)
- Register shipment → Shipments table: writes shipment (evidence: `README.md`)
- Register shipment → Events table: writes timeline (evidence: `README.md`)
- Carrier services → Carrier webhook: sends updates (evidence: `README.md`)
- Carrier webhook → Signature verification: verifies payload (evidence: `src/handlers/webhook/index.js`)
- Signature verification → ShipEngine JWKS: fetches keys (evidence: `src/lib/verifyShipEngineSignature.js`)
- Carrier webhook → DynamoDB access: reads and writes (evidence: `src/handlers/webhook/index.js`)
- Carrier webhook → Event mapping: maps events (evidence: `src/handlers/webhook/index.js`)
- Carrier webhook → Date handling: normalizes dates (evidence: `src/handlers/webhook/index.js`)
- Carrier webhook → Retry helpers: retries writes (evidence: `src/handlers/webhook/index.js`)
- Carrier webhook → Operation tracking: tracks processing (evidence: `src/handlers/webhook/index.js`)
- Carrier webhook → Shipments table: updates status (evidence: `README.md`)
- Carrier webhook → Events table: stores events (evidence: `README.md`)
- Carrier webhook → Push notifications: sends alerts (evidence: `src/handlers/webhook/index.js`)
- Paginated listing → DynamoDB access: queries data (evidence: `src/handlers/list/index.js`)
- Paginated listing → Shipments table: reads shipments (evidence: `README.md`)
- Paginated listing → Events table: reads timelines (evidence: `README.md`)
- Paginated listing → API Gateway: returns page (evidence: `README.md`)
- Dashboard state → Shipment cards: displays results (evidence: `README.md`)
- Shipment deletion → DynamoDB access: deletes records (evidence: `src/handlers/delete/index.js`)
- Shipment deletion → ShipEngine API: stops tracking (evidence: `src/handlers/delete/index.js`)
- Shipment deletion → Push notifications: alerts failures (evidence: `src/handlers/delete/index.js`)
- Staleness monitor → DynamoDB access: checks records (evidence: `src/handlers/monitor-staleness/index.js`)
- Staleness monitor → Push notifications: sends alerts (evidence: `src/handlers/monitor-staleness/index.js`)
- Dashboard state → S3 and CloudFront: is hosted by (evidence: `README.md`)
