ZHU Controller Toolkit

Unified front-end shell for Houston ARTCC controller utilities.

Current tools are registered in a single data file and rendered as launch cards:

• TFMS
• Alias Guide (migrated internal route)
• ADAR Routes
• Route Validator
• Split Map
• RVM Reference

Getting Started

Run the development server:

npm run dev

Then open http://localhost:3000.

Project Structure

• data/tools.json: tool registry (add/edit tools here)
• app/page.js: homepage entry
• components/toolkit-home.js: tool launcher grid UI
• app/tools/[id]/page.js: per-tool detail pages
• app/tools/alias-guide/page.js: migrated Alias Guide tool
• components/alias-guide-page.js: refactored Alias UI (sidebar nav, search, cards)
• data/alias-guide.json: normalized Alias data model used by the app
• data/alias-guide-markup.html: imported source markup from legacy Alias Guide
• scripts/convert-alias-markup.mjs: converter from legacy markup to normalized JSON
• app/tools/route-validator/page.js: Route Validator page entry
• components/route-validator-page.js: Route Validator UI + matching/status logic
• app/tools/route-validator/styles.css: Route Validator-specific styling
• data/zhu-routing-rules.json: preferred route rules used by Route Validator
• lib/tools.js: helpers for loading tool data
• app/globals.css: shared theme tokens and utility classes
• reference/: source/reference docs used during development (not runtime)

Adding a Tool

Add a new object to data/tools.json with:

• id
• name
• description
• url
• liveUrl
• category
• status
• icon
• tags

The homepage and /tools/[id] route will automatically include it.

Alias Data Workflow

The Alias Guide now renders from data/alias-guide.json.

If you update legacy source HTML in data/alias-guide-markup.html, regenerate JSON with:

npm run alias:convert

To normalize long generated IDs into readable slug-based IDs:

node scripts/normalize-alias-ids.mjs

Alias Module Notes

• In data/alias-guide.json, most content fields store both:
  • html: rendered UI content (supports formatting tags)
  • text: plain-text content used for search/filter
• Keep html and text semantically aligned when editing content.
• Alias sections now use one shared layout:
  • section header + intro (optional)
  • standardized reference tables
  • row-level Link button to copy direct hash links
• Section-specific table label mapping lives in:
  • components/alias-guide-page.js -> SECTION_TABLE_CONFIG
• Hash permalink format:
  • /tools/alias-guide#<entry-id>
  • example: /tools/alias-guide#alias

Route Validator Workflow

Route Validator renders from data/zhu-routing-rules.json and compares filed routes for departures against matching alias rules.

Runtime Data Sources

• VATSIM traffic feed: https://data.vatsim.net/v3/vatsim-data.json
• D-ATIS feeds:
  • https://atis.info/api/KIAH
  • https://atis.info/api/KHOU
  • https://atis.info/api/KDFW
  • https://atis.info/api/KDAL
  • https://atis.info/api/KATL
• Refresh intervals:
  • traffic: every 60 seconds
  • D-ATIS: every 30 minutes

Fallback/Test Data

• Static sample pilots/prefiles are defined in components/route-validator-page.js:
  • STATIC_CONNECTED_PILOTS
  • STATIC_PREFILES
• If live traffic fetch fails, static samples are used automatically.
• D-ATIS remains live unless that feed fails.

TFMS Notes

• TFMS currently shows:
  • Specialty Summary
  • Online Positions (enroute + TRACON status)
• Split Summary is intentionally hidden for now and can be re-enabled later.

Route Validator Statuses

Current status labels:

• CHECK ROUTE
• FLOW
• ALTITUDE
• REVISION
• VALID
• NO RULE

Default status sort priority:

1. CHECK ROUTE
2. FLOW
3. ALTITUDE
4. REVISION
5. VALID
6. NO RULE

COPY ROUTE action appears only for:

• CHECK ROUTE
• FLOW
• REVISION

Flow Logic Notes

• Destination flow checks are parsed from D-ATIS for KIAH, KHOU, KDFW, KDAL, KATL.
• KIAH no-rule SID flow checks currently include:
  • BNDTO# => West
  • PITZZ# => East
  • MMUGS# => West
  • GUMBY# => East

Reference Documents

• Development references live under reference/.
• FAA aircraft type designator source currently tracked:
  • reference/2024-04-29_FAA_Order_JO_7360.1J_Aircraft_Type_Designators--post.pdf
• See reference/README.md for usage notes.

Validate

npm run lint
npm run build

Theme Modes

The app supports Light, Dark, and System mode via Auto / ☀ / ☾ controls placed in tool/page headers. Preference is saved in localStorage (theme-mode).

GitHub Pages Deployment

This project is configured for static export + GitHub Pages.

Important files:

• next.config.mjs (output: "export")
• public/CNAME (toolkit.houston.center)
• .github/workflows/deploy-pages.yml

Required one-time GitHub settings:

1. In your repo, go to Settings > Pages.
2. Under Source, select GitHub Actions.
3. In your DNS provider, set toolkit.houston.center to GitHub Pages (CNAME target per GitHub docs).

After that, pushes to main will build and deploy automatically.

Notes for PowerShell

If your machine blocks npm/npx PowerShell scripts, use:

• npm.cmd run dev
• npm.cmd run lint
• npm.cmd run build