Duty Station Relocation

Overview

Duty Station Relocation is a public, open-source web application that helps U.S. Customs and Border Protection (CBP) job applicants explore potential CBP duty location assignments across the country. It provides a streamlined, responsive interface for browsing, searching, mapping, and comparing assignments across USBP, OFO (ports and field offices), and AMO.

Users can access external resources for housing, schools, crime rates, cost of living, weather, and other key relocation factors directly from each location detail page. No login is required and no personal user profiles are collected.

Live site: https://dutystation.us

Who is it for?

• Built for: U.S. Customs and Border Protection (CBP) and its prospective job applicants
• Primary Users: Individuals who have received job offers requiring relocation
• Secondary Users: CBP HR and recruiting teams supporting workforce mobility

Built by MetaPhase

This application was developed by MetaPhase using our internal OrangeAI accelerators to rapidly deliver government-grade generative AI solutions.

MetaPhase delivers mission-driven digital services to federal agencies, with a focus on human-centered design, emerging technology, and secure modern platforms.

This solution was developed as a free and open-source contribution to support public sector innovation.

Tech Stack

This application is built with:

• React
• TypeScript
• Vite
• Tailwind CSS
• shadcn/ui component library
• Supabase managed PostgreSQL (database, RLS, analytics events)
• OpenLayers for map rendering
• Vitest + Testing Library + axe for testing/accessibility checks

Architecture

• UI components read data through a typed repository layer: src/lib/data/stationRepository.ts
• Supabase is the primary data store when VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY are configured
• Local fallback dataset is used automatically in development when Supabase env vars are absent
• Database schema and RLS policies are versioned in supabase/migrations/
• Operational scripts for seeding and link auditing live in scripts/data/

Local Setup

To run this application locally:

Prerequisites

• Node.js and npm (recommended via nvm)

Steps

# Step 1: Clone the repository
git clone https://github.com/MetaPhase-Consulting/dutystation.git

# Step 2: Navigate into the project directory
cd dutystation

# Step 3: Install dependencies
npm install

# Step 4: Start the development server
npm run dev

The application will be available at http://localhost:5173.

If you need a fixed localhost/port for testing:

npm run dev:secure

This starts on http://localhost:8080.

Environment Variables

Copy .env.example to .env and provide values as needed:

cp .env.example .env

Frontend runtime keys:

• VITE_SUPABASE_URL
• VITE_SUPABASE_ANON_KEY

Script-only keys (never expose in frontend runtime):

• SUPABASE_URL
• SUPABASE_SERVICE_ROLE_KEY

Data Operations

• Export current station source to JSON:

npm run data:export

• Seed Supabase tables from current source:

SUPABASE_URL=... SUPABASE_SERVICE_ROLE_KEY=... npm run data:seed:supabase

• Run external link quality audit (writes JSON report):

npm run data:audit:links -- --out docs/progress/link-audit-latest.json

• Dry-run automated link remediation plan:

SUPABASE_URL=... SUPABASE_SERVICE_ROLE_KEY=... npm run data:remediate:links

• Apply link remediations to Supabase:

SUPABASE_URL=... SUPABASE_SERVICE_ROLE_KEY=... npm run data:remediate:links:apply

• Run link audit and sync status to Supabase:

SUPABASE_URL=... SUPABASE_SERVICE_ROLE_KEY=... npm run data:audit:links:sync

• Validate link quality gate from latest report:

npm run data:validate:link-audit -- --report docs/progress/link-audit-latest.json --maxUnknownRate 0.35

• Generate enriched stations from CBP CSV:

npm run data:enrich:csv -- --out supabase/seed/enriched_stations.json

• Generate and sync enriched stations to Supabase:

SUPABASE_URL=... SUPABASE_SERVICE_ROLE_KEY=... npm run data:enrich:csv:sync

Quality Checks

npm run lint
npm run test:run
npm run build
npm run audit:deps

CI/CD

GitHub Actions workflows:

• CI: lint, typecheck, tests, build, dependency audit
• Security: dependency audit and dependency review
• CD: deploy static build to GitHub Pages
• DB Migrations: push supabase/migrations to linked Supabase project
• Data Maintenance: scheduled link remediation + audit quality gate + CSV enrichment sync

Required repository secrets for full automation:

• VITE_SUPABASE_URL
• VITE_SUPABASE_ANON_KEY
• SUPABASE_URL
• SUPABASE_SERVICE_ROLE_KEY
• SUPABASE_PROJECT_REF
• SUPABASE_ACCESS_TOKEN

Program Documentation

• Roadmap: docs/plan/implementation-roadmap.md
• Requirements traceability: docs/requirements/traceability-matrix.md
• Progress log: docs/progress/status-log.md
• Architecture decisions: docs/architecture/adr-001-data-platform.md
• Engineering harness standard: docs/governance/engineering-harness-standard.md
• Release gates and SLO policy: docs/governance/release-gates-and-slos.md
• Link operations runbook: docs/operations/link-quality-runbook.md
• Accessibility/security checklist: docs/compliance/accessibility-security-checklist.md

Deployment

This project can be deployed to any modern frontend platform, including:

• Vercel
• Netlify
• GitHub Pages
• AWS Amplify / S3 / CloudFront (for federal use)

License

This project is licensed under the MIT License. You are free to use, modify, and distribute this software in accordance with the terms of that license.