Directory Structure

🇮🇱 עברית

Directory Structure

NavAid is still a static site with no build step. The docs/ directory is the deployed app, but the app source is grouped so the root stays small and easy to scan.

docs/ at a glance

docs/
├── index.html                 # Main app shell, SEO metadata, toolbar DOM
├── sw.js                      # Service worker, kept at root for scope
├── manifest.json              # PWA manifest
├── favicon.svg
├── robots.txt
├── sitemap.xml
├── BingSiteAuth.xml
├── en/
│   └── index.html             # Stable English redirect entry
├── he/
│   └── index.html             # Stable Hebrew redirect entry
├── app/
│   ├── core.js                # Globals, state, Leaflet map, geo helpers
│   ├── draw.js                # Canvas rendering
│   ├── interact.js            # Hit-testing, drag, inspector
│   ├── io.js                  # Save/load, flight plan, PNG/KML export
│   ├── ui.js                  # Toolbar wiring and boot
│   └── style.css              # App CSS
├── data/
│   ├── airfields.json
│   ├── comm-change.json
│   ├── leg-altitude.json
│   ├── nav-waypoints.json
│   ├── route-templates.json
│   └── vor.json
├── i18n/
│   ├── en/strings.js
│   └── he/strings.js
├── assets/
│   ├── icon-192.png
│   ├── icon-512.png
│   └── og-preview.jpg
├── byop/                      # Airport PDF charts, large and shared by previews
└── legacy/
    ├── build_map.py
    └── map.jpg

What stays at the root

Keep browser entry points and crawler/PWA files directly under docs/:

• index.html — app shell, canonical SEO metadata, and script tags.
• sw.js — root scope is intentional; moving it changes service-worker scope.
• manifest.json, favicon.svg, robots.txt, sitemap.xml, BingSiteAuth.xml.
• en/index.html and he/index.html — stable locale redirect pages.
• byop/ — large PDF chart bundle. Deploy keeps one copy at the production root and removes duplicate copies from staging and previews.

App code

All runtime JS and CSS lives in docs/app/.

Script order still matters because the app is plain global-scope JavaScript, not modules:

i18n/<lang>/strings.js
app/core.js
app/draw.js
app/interact.js
app/io.js
app/ui.js

When changing JavaScript, run node --check on every changed .js file before committing.

Data files

Runtime datasets live in docs/data/. App code should fetch them with paths relative to index.html, for example:

data/nav-waypoints.json?v=3
data/airfields.json?v=3
data/leg-altitude.json?v=1

Use this folder for JSON that the browser loads at runtime:

• nav-waypoints.json — CVFR reporting points.
• airfields.json — airfield metadata, runways, elevations, plates.
• comm-change.json — call-sign catalog and frequency-change points.
• leg-altitude.json — learned CVFR altitude pairs.
• route-templates.json — ready-made route definitions.
• vor.json — VOR/DME station data.

Locale files

Locale dictionaries live under docs/i18n/:

• docs/i18n/en/strings.js — English defaults.
• docs/i18n/he/strings.js — Hebrew overrides.

Add new UI strings to both files and keep string parity tests green.

Assets

Static images used by the app shell live in docs/assets/.

Use this folder for icons, Open Graph images, screenshots that are loaded by the app, or other small browser assets. Large aviation PDFs stay in docs/byop/.

Legacy files

docs/legacy/ contains files from the old static-map implementation. They are not part of the current Leaflet app and should not be used for new features.

Deploy compatibility

During the layout migration, .github/workflows/deploy.yml can rewrite cache-bust/version markers in both layouts:

• new layout: app/core.js, i18n/he/strings.js
• old layout: core.js, he/strings.js

This lets main, dev, and open PR previews coexist while branches move through the new structure.

Where to add new files

Need	Put it here
App JavaScript or CSS	docs/app/
Runtime JSON dataset	docs/data/
UI translations	docs/i18n/<lang>/strings.js
App images / social preview / icons	docs/assets/
Airport PDF charts	docs/byop/
Redirect-only locale entry page	docs/<lang>/index.html
Old reference artifact	docs/legacy/

See also Architecture, Deployment, and Contributing.