nd-assets - Delivery Management System

A serverless delivery management platform built with Next.js 15, AWS Amplify Gen 2, and Cognito. It includes role-aware administrator, operator, and customer portals, route planning and execution workflows, customer-specific dashboards, and invoice management with SES email delivery.

Overview

Layer	Technology
Frontend	Next.js 15, React 18, TypeScript
Hosting	AWS Amplify Hosting + CloudFront
Authentication	AWS Cognito User Pools
API	AWS AppSync (GraphQL via Amplify Data)
Database	Amazon DynamoDB (Amplify-managed models)
CI/CD	GitHub Actions + Amplify Console

Current Features

• Role-aware login with branded Amplify Authenticator, request-access signup, pending approval, and multi-role portal selection.
• Administrator, operator, and customer portals share one shell (PortalShell) with a collapsible mobile sidebar and safe-area-aware bottom padding: navy staff chrome for administrators and operators, a theme-following sidebar for customers.
• Administrator portal with dashboard KPIs, customer management, user management, route management, invoice management, and settings.
• Route management with create/edit/detail flows, customer-aware listings, status filtering, and support for copying stops from a previous route or importing schedule files. Route creation is blocked on any date either the operator (no drivers available) or the customer (agency closed) has marked out on the service calendar.
• Operator portal with a phone-friendly dashboard for planned and active routes, a legacy route detail flow for stop execution and map-based route review, and a five-phase Driver Sign Run flow (Load → Placement → Pickup → Unload → Finalise) for routes with drivingModeEnabled, covering van sign counts, placement/pickup progression with missing-sign tracking, and billing finalisation.
• Customer portal with dashboard analytics, route history, invoice listing, and user settings.
• Customer access controls with account_owner and read_only roles, where invoice access is restricted to the account owner; both roles can add route instructions.
• Invoice management with PDF upload and parsing support, SES-backed email delivery through /api/admin/send-invoice-email, and emailSentAt tracking on invoices.
• Route and stop maps with numbered markers, service-aware coloring, and multiple map style options.
• Customer-user assignment support with first-user assignment handling.

Notes:

• Some third-party tile styles require provider API keys in their tile URL configuration for production use.

User Groups

Create these Cognito groups in your User Pool:

Group	Purpose
administrator	Full administration access
operator	Operations access
customer	Customer portal access

After sign-in:

• Single-role users are redirected automatically.
• Multi-role users choose a destination portal.
• Users with no portal role are sent to pending approval.

Data Model

Amplify Data schema currently defines 17 entities:

• Customer
• Operator
• Route
• Stop
• Invoice
• LineItem
• PaymentRecord
• AuditLog
• CustomerUser
• Administrator
• UserSettings
• OrganizationSettings
• OperatorAvailabilityBlock
• CustomerClosureBlock
• RateLine
• OperatorPayout

Getting Started

Prerequisites

• Node.js 22+
• AWS CLI v2
• AWS account in ap-southeast-2 (or adjust region settings consistently)

Local Setup

git clone https://github.com/anodyne74/amplify-null-device.git
cd amplify-null-device

npm ci
npm run generate:config
npm run dev

App URL: http://localhost:3000

Scripts

Command	Purpose
npm run dev	Start Next.js dev server
npm run build	Production build
npm run start	Start production server
npm run lint	ESLint checks
npm run typecheck	TypeScript checks
npm run test	Jest watch mode
npm run test:ci	Jest CI run with coverage
npm run generate:config	Generate local amplify_outputs.json
npm run validate:amplify-outputs	Validate generated Amplify outputs
npm run import:prep	Prepare or apply a legacy tracker + route-list import bundle
npm run backfill:geocodes	Backfill Stop.latitude/longitude for stops missing GPS coordinates

Configuration

amplify_outputs.json

amplify_outputs.json is generated and should not be manually edited. For local work:

npm run generate:config

Amplify Environment Variables

Set these in Amplify Console for builds/runtime:

Variable	Description
AMPLIFY_COGNITO_USER_POOL_ID	Cognito User Pool ID
AMPLIFY_COGNITO_CLIENT_ID	Cognito App Client ID
AMPLIFY_IDENTITY_POOL_ID	Cognito Identity Pool ID
AWS_REGION	AWS region (for example ap-southeast-2)
SES_SENDER_EMAIL	Sender used by SES invoice email API
SES_INVOICE_TEMPLATE_NAME	SES template name for invoice emails (default: branch-scoped, e.g. NullDeviceInvoiceTemplate-main)
SES_INVITATION_TEMPLATE_NAME	SES template name for branded customer invite emails (default: branch-scoped, e.g. NullDeviceInvitationTemplate-main)
SES_STAFF_INVITATION_TEMPLATE_NAME	SES template name for branded operator/administrator invite emails (default: branch-scoped, e.g. NullDeviceStaffInvitationTemplate-main)
SES_MISSING_SIGNS_REPORT_TEMPLATE_NAME	SES template name for Missing Signs Report emails (default: branch-scoped, e.g. NullDeviceMissingSignsReportTemplate-main)
SES_COMPANY_ADDRESS	Postal address shown in email footers (invoice + invitation)
NEXT_PUBLIC_SUPPORT_EMAIL	Support address shown in email footers and "not expecting this?" text
NEXT_PUBLIC_APP_URL	Base URL used to build portal/reset links and the logo asset URL in emails

Notes:

• If SES_SENDER_EMAIL is not set, API falls back to no-reply@<domain>, where <domain> is the host of NEXT_PUBLIC_APP_URL (or nulldevice.com.au if that isn't set either). nulldevice.dev is used for the development branch, nulldevice.com.au for main/production.
• If SES_INVOICE_TEMPLATE_NAME (or its SES_INVITATION_TEMPLATE_NAME / SES_STAFF_INVITATION_TEMPLATE_NAME / SES_MISSING_SIGNS_REPORT_TEMPLATE_NAME siblings) is not set, the API falls back to the branch-scoped name amplify/backend.ts deployed, read out of amplify_outputs.json's custom section (see lib/amplifyOutputsCustom.ts) -- not from AWS_BRANCH/AMPLIFY_BRANCH, which aren't set in the Amplify Hosting SSR runtime (only during the CDK build step).
• If SES_COMPANY_ADDRESS is not set, emails fall back to a placeholder ("Melbourne, Australia") -- set it per environment so production email doesn't ship the placeholder.
• If NEXT_PUBLIC_SUPPORT_EMAIL is not set, emails fall back to [email protected].
• Verify sender identity/domain in SES for the configured region.
• The SES template is provisioned by Amplify backend deployment in amplify/backend.ts.

Legacy Import

Use scripts/import-prep.js to turn a historical tracker CSV plus matching route-list CSVs into an import bundle, or to apply that bundle directly into Amplify Data.

The tracker file should use the meaningful A-K columns only. Any calculated columns after K are ignored.

Example dry run:

npm run import:prep -- \
	--tracker "/home/dave/Downloads/Tracker - Jobs.csv" \
	--route-lists-dir "/home/dave/Downloads/route-lists" \
	--customer-id "YOUR_CUSTOMER_ID" \
	--mode dry-run \
	--output legacy-import-bundle.json

Example apply run:

export IMPORT_PREP_USERNAME="[email protected]"
export IMPORT_PREP_PASSWORD="your-password"

npm run import:prep -- \
	--tracker "/home/dave/Downloads/Tracker - Jobs.csv" \
	--route-lists-dir "/home/dave/Downloads/route-lists" \
	--invoice-pdfs-dir "/home/dave/Downloads/invoice-pdfs" \
	--customer-id "YOUR_CUSTOMER_ID" \
	--mode apply \
	--confirm-apply \
	--auth-mode userPool \
	--outputs-path amplify_outputs.json

Example PDF-only rerun (no route/stop/invoice recalculation):

export IMPORT_PREP_USERNAME="[email protected]"
export IMPORT_PREP_PASSWORD="your-password"

npm run import:prep -- \
	--tracker "/home/dave/Downloads/Tracker - Jobs.csv" \
	--invoice-pdfs-dir "/home/dave/Downloads/invoice-pdfs" \
	--customer-id "YOUR_CUSTOMER_ID" \
	--mode pdf-only \
	--confirm-apply \
	--auth-mode userPool \
	--outputs-path amplify_outputs.json

Optional auth flags:

--auth-mode userPool|iam
--username "[email protected]"
--password "your-password"

Notes:

• The script matches route-list files by route code in the filename, such as W23-26-001 - Route List - Route.csv.
• The tracker export uses the second tab in the workbook, which should be the Jobs sheet.
• If a route-list file is missing, the bundle still generates and adds a warning for that route.
• If --invoice-pdfs-dir is provided, the importer matches PDFs by invoice number (for example INV-001.pdf) and uploads them to invoices/{invoiceId}.pdf, then saves pdfS3Key on the invoice record.
• PDF upload requires a signed-in Cognito user in operator or administrator group with current storage write permissions deployed.
• Apply mode upserts routes, stops, invoices, and a legacy line item for each invoice when the imported totals are available.
• pdf-only mode only uploads matched invoice PDFs and updates pdfS3Key on existing invoices.
• Apply mode requires --confirm-apply so writes cannot happen accidentally.
• In an interactive terminal, apply mode also asks for a final yes confirmation before writing.
• The current importer defaults stop service types to delivery.
• Apply mode now defaults to --auth-mode userPool and requires a signed-in Cognito operator/administrator account.
• If you see No federated jwt, you are using IAM/federated auth without valid identity credentials; switch to --auth-mode userPool and provide IMPORT_PREP_USERNAME / IMPORT_PREP_PASSWORD.
• Apply mode copies viewerSubs onto every Route/Stop/Invoice/LineItem it writes, read from the target Customer record (never recomputed here — it's kept in sync elsewhere whenever CustomerUser membership changes). Without this, imported records are invisible in the customer portal, since those models use ownersDefinedIn('viewerSubs') authorization with no customerId fallback. If a customer's viewerSubs is empty at import time (no CustomerUser linked yet), re-run apply after linking a user to backfill it.
• Apply mode also sets Invoice.gstAmount (10% of totalAmount) when the customer's gstExclusive flag is set.
• Newly imported stops don't include GPS coordinates — see Geocode Backfill below to populate / so they render on route maps.

Geocode Backfill

Route/Stop maps (RouteStopsMap) only render stops that already have latitude/longitude. Legacy tracker imports don't set those fields, so newly imported stops (and any older stop created before geocoding existed) are silently omitted from maps until backfilled.

Use scripts/backfill-geocodes.js to geocode every stop for a customer that's missing coordinates, using the Google Geocoding REST API directly (server-side — this script doesn't run in a browser, so it can't use the Maps JS SDK path that lib/googleMaps.ts uses in the app itself).

export IMPORT_PREP_USERNAME="[email protected]"
export IMPORT_PREP_PASSWORD="your-password"
export GOOGLE_MAPS_API_KEY="your-server-side-key"

npm run backfill:geocodes -- \
	--customer-id "YOUR_CUSTOMER_ID" \
	--outputs-path amplify_outputs.json \
	--mode dry-run

Re-run with --mode apply --confirm-apply to write latitude, longitude, and formattedAddress back to each Stop.

Notes:

• Requires GOOGLE_MAPS_API_KEY (or NEXT_PUBLIC_GOOGLE_MAPS_API_KEY as a fallback) in the environment.
• The key must not have an HTTP referrer restriction. NEXT_PUBLIC_GOOGLE_MAPS_API_KEY is normally referrer-restricted for browser use (Maps JS SDK), which the Geocoding REST API rejects outright (API keys with referer restrictions cannot be used with this API). Use a separate key restricted by IP or API instead, set as GOOGLE_MAPS_API_KEY.
• By default only stops missing latitude/longitude are geocoded; pass --force to re-geocode stops that already have coordinates.
• --delay-ms (default 200) throttles requests between stops to stay under Google's per-second quota; --limit caps how many stops are processed in one run.
• Same --auth-mode/--outputs-path/--username/--password conventions as import-prep.js.

Payout Period Backfill

Payouts imported before import:prep wrote a period carry a routeId but no periodStartDate/periodEndDate. scripts/backfill-payout-periods.js sets both to the UTC date of the linked Route's actualEndTime. It never overwrites a period that is already set, and lists (without touching) any payout whose Route is missing or has no end time. The dry run also lists still-pending payouts, so check those are really unpaid. Needs an administrator login and refuses non-development APIs without --allow-non-development.

node scripts/backfill-payout-periods.js --outputs-path amplify_outputs.json                      # dry run
node scripts/backfill-payout-periods.js --mode apply --confirm-apply --outputs-path amplify_outputs.json

Deployment

Recommended

./deploy-to-uat.sh

Amplify Console

1. Connect repository anodyne74/amplify-null-device.
2. Choose your target branch.
3. Ensure required environment variables are set.
4. Deploy.

Build/Deploy Pipeline Notes

• Amplify backend build uses npx ampx pipeline-deploy --app-id "$AWS_APP_ID" --branch "$AWS_BRANCH".
• Frontend artifacts are served from .next (not out).

Project Structure

amplify/
	auth/resource.ts
	data/resource.ts
	storage/resource.ts
	backend.ts

app/
	page.tsx                      # branded login + role routing
	layout.tsx                    # Authenticator.Provider wrapper
	administrator/
		dashboard/
		routes/
		invoices/
		customers/
		users/
		settings/
	operator/
		dashboard/
		routes/
		settings/
	customer/
		dashboard/
		routes/
		invoices/
		settings/
	api/admin/send-invoice-email/route.ts

lib/
scripts/
amplify.yml

Troubleshooting

Symptom	Likely Cause	Action
Auth not configured	Placeholder/missing amplify_outputs.json or env vars	Run npm run generate:config locally and verify Amplify env vars
Invoice email fails	SES sender not verified or missing config	Verify SES identity and SES_SENDER_EMAIL
Build artifact errors in Amplify	Wrong output directory	Confirm Amplify base directory is .next

Contribution

See CONTRIBUTING.md for contribution and PR guidance.