Directory Layout

Related documents

• Development Process Guide

Table of contents

• Project root directory layout
• The source/ directory
  • The source/app/ directory
  • The source/airportData/ directory
  • The source/image/ directory
  • The source/service/ directory
  • The source/cdv/ directory
• The build/ directory
• The doc/ directory

Project root directory layout

The project root contains the following files and directories:

• app.mk
  The sub-makefile for the aircraft apps. The main Makefile invokes it once per app.
• build/
  Created by the Makefiles for app images, lint results, and documentation. See The build/ directory.
• codex/
  Tools and working files for auditing POH revisions against an app's data and procedure text. A separate NodeJS package that is not part of the app build.
• digitized/
  Performance graphs and tables digitized from POH scans with the POH Performance Digitizer, as .ppdig files in a directory per app.
• doc/
  The documentation source. See The doc/ directory.
• Example1.mk, Radar.mk, Testapp.mk
  Sub-makefiles for the apps that app.mk doesn't cover.
• lintTemplate.html
  The page make serve shows in place of an app while lint reports errors.
• localServer/
  Created by make serve: the development server's index page, a symbolic link to each app's web image, the PHP router that stands in for the production .htaccess rewrites, and the server-side saved-input, log, and trouble-report files. See Testing and debugging apps.
• Makefile
  The main Makefile. See Building apps.
• node_modules/
  NodeJS modules installed by npm install.
• package.json, package-lock.json
  The npm package files. They record the dependencies of the build scripts.
• source/
  The main source directory. See The source/ directory.
• tmp/
  Scratch output from the codex/ audit tools. Not used by the build.
• tools/
  The NodeJS and Python scripts used by the build. See Scripts Reference. It also holds the digitizer/ web app and, under upgradeToV5/, the harnesses that compared the V5 apps against V4 during the upgrade.
• version5.bbprojectd/
  A BBEdit project for the source.

The source/ directory

The source/ directory contains the following directories:

• source/airportData/
  Content for building the airport database. See The source/airportData/ directory.
• source/app/
  The client source code for all apps and the common infrastructure. See The source/app/ directory.
• source/cdv/
  Content for creating Cordova images for each app. See The source/cdv/ directory.
• source/image/
  Content for building the graphics for each app. See The source/image/ directory.
• source/service/
  The server-side services. See The source/service/ directory.

The source/app/ directory

The source/app/ directory contains the following directories:

• source/app/<appId>/
  The source code for the <typeName> app. For most POH Performance apps, the app's full name is "<typeName> Performance". The aircraft apps are Baron, Bonanza, C172, C182, C310, Kodiak, PA28, and TBM.
• source/app/common/
  The source code for the common infrastructure and utilities.
• source/app/Example1/
  A minimal example app: an index.html, a service worker, and a buildStamp/ with app.js, one page, and an image. A starting point for a new app.
• source/app/Radar/
  The Radar app. It has no aircraft data and no self-test suite, so it has its own Radar.mk.
• source/app/Testapp/
  The source code for the Testapp.

The source/app/common/ directory

This directory contains the source code for the common infrastructure and utilities. It contains the following files and directories:

• source/app/common/aero/
  Common files related to aeronautical functions: aircraft types and options, performance tables, airports, weather, wind, and weight and balance.

• source/app/common/mvcs/
  The MVCS infrastructure code. See the MVCS Overview.

• source/app/common/option/
  Optional modules. These must be explicitly imported as required. These include

  • speech.js
    An interface module to DOM speech function. See the speech Reference.
  • svgDraw.js
    An SVG drawing package module. See the SVG Drawing Module Reference.
  • told.js
    The flight planning results (TOLD) email text, composed from the pages' renderTold() methods. See the TOLD Reference.
  • units.js
    A units conversion module. See the Units Module Reference.
  • unitTest.js
    A built-in unit test module. See the unitTest Reference.

• source/app/common/page/
  App pages that are independent of the specific app or aircraft type. These are:

  • Checklist page
    Displays a checklist. The app must provide a separate Procedures page to select the checklist. See the Checklist Page Reference.
  • Hold entry page
    Displays an interactive hold entry computer. See the Hold Entry Page Reference.
  • People page
    A page that maintains a user-editable database of people and their weights. See the People Page Reference.
  • Ptable test page
    A developer page that graphs any performance table of any model and option, and the "Check aircraft data" self-test that checks every model's tables and option data. See the Ptable Test Page Reference.
  • Radar page
    The weather radar display used by the aircraft apps that have radar (the Radar app has its own variant). See the Radar Page Reference.
  • Risk page
    A Flight Risk Assessment Tool (FRAT) page. See the Risk Page Reference.
  • Settings page, and the settings cards in aeroSettingsCards.js
    An app settings page, including the hidden developer card. See the Standard Settings Page.
  • Terms of Use page
    A page that displays the POH Performance Terms of Use and records the users acknowledgment. See the Terms of Use Page Reference.
  • Test page
    A page that executes a self-test when opened and displays the results. See the Test Page Reference.
  • Trips page
    A page that maintains a user-editable database of trips. Each trip consists of the same settings recorded on the Quick Setup page. See the Trips Page Reference.

• source/app/common/script/
  Files that are included in the app as classic scripts rather than modules: the global utility functions (util.js, numUtil.js, objectUtil.js, domUtil.js) and device detection (localDevice.js). Each app's index.html lists them in <script> tags. The source/app/common/script/lib/ directory holds the external libraries included the same way, currently Modernizr and UAParser.

  The directory also includes polyfill.js, general polyfills for JavaScript features more recent than the Technology use criteria. No app currently loads it.

• source/app/common/eslint.config.mjs
  The eslint configuration used to lint the common code and every app.

The source/app/<appId>/ directory

The unique part of each app is in a directory under source/app/<appId>. Typically, the appId is the first word in the full app name. For example, 'C182' for the 'C182 Performance' app. This directory typically contains the following files and directories.

• buildStamp/
  This directory contains most of the app-specific code. The directory is called buildStamp because this name is replaced with a build timestamp in the web image to ensure that all the contained files and directories fetched by the client will be the versions for this build. See The Service Worker and caching. The directory typically contains the following:
  • buildStamp/aircraftData/
    The data and self-tests for each aircraft model and option, and typeData.js, which contains type-wide data. The options are in options.js.
  • buildStamp/icon/
    The app icons the PWA manifest refers to. Generated by make image and checked into git.
  • buildStamp/image/
    App images, such as the aircraft top view.
  • buildStamp/internalData/
    Built-in app databases, such as the airport database airportData.js. Generated by make db and checked into git.
  • buildStamp/page/
    App-specific pages, with their CSS.
  • buildStamp/app.js
    The app startup code. See App Startup.
  • buildStamp/manifest.json
    The PWA manifest file. See Web app manifests.
  • buildStamp/svFormat.js
    An optional file that contains state variable info object for state variables formats that are widely-used in the app.
• eslint.config.mjs
  A copy of the common eslint configuration. The build lints every app with the common configuration, so this copy is not used.
• externalData/
  Downloadable app databases that are not built into the app, such as the latest airport database update. The web build copies these to the app's root on the server, beside index.html, where the app fetches them. Because this data is not under buildStamp, the contents will be shared among all currently active app versions. Any data placed here must be backward compatible or have its own versioning convention. The current contents are:
  • externalData/airportData.json
    A downloadable version of the airport database in JSON format. This is only used to update the built-in version. See Airport database updates.
  • externalData/airportDataTimestamp.json
    The timestamp for airportData.json. The app fetches this file when the app is started or resumed after a long period of inactivity. If the timestamp is newer than the most recent update or built-in database, then the large airportData.json is fetched and the database is updated.
• icon/
  The favicon and the icons index.html refers to. Generated by make image and checked into git.
• index.html
  The index.html file for this app. The web build inserts the file manifest and the stylesheet links into a copy of it.
• serviceWorker.js
  The Service Worker for this app. Every app's copy is the same apart from the app name. See The Service Worker and caching.

The app's .htaccess file is not here but in source/service/<appId>/.

The source/app/Testapp/ directory

The Testapp has the same layout as an aircraft app without the icons and service worker. Under buildStamp/ it has:

• aircraftData/
  A fixture aircraft type, mytype.js, with models and options that exercise the option machinery, and its procedures.
• page/
  The Testapp's pages: an aircraft page, a procedures page, a METAR test page, a popup test page, a visual test page for the common components, and the unit test page.
• test/
  The unit tests for the common infrastructure: state variables, performance tables, aircraft types and options, and SVG drawing. The unit test page runs them.

The source/airportData/ directory

This directory contains the inputs and outputs of make db. See Building the airport database.

• NFDC/APT_BASE.csv, NFDC/APT_RWY.csv, NFDC/APT_RWY_END.csv
  The FAA airport, runway, and runway end data of the current NASR cycle, downloaded by make db. The EFF_DATE column on every row is removed so that a cycle's diff shows only the data that changed.
• NFDC/EFF_DATE.txt, NFDC/APT_CSV_DATA_STRUCTURE.csv
  The effective date of the NFDC data and the FAA's description of the CSV columns.
• ourairportscom/airports.csv, ourairportscom/runways.csv
  Airport and runway data downloaded from ourairports.com by make db.
• stations.xml
  The weather station list downloaded from aviationweather.gov by make db.
• dbFlags/<appId>.txt
  The buildAirportDB.js flags for each app that has an airport database, such as its runway requirements.
• logs/<appId>_log.txt
  The database build log for each app. It explains why airports, runways, and codes were dropped.

The source/image/ directory

This directory contains the source files used to create images associated with each app. Each app has a separate directory named by the appId containing source files such as:

• The Android store feature-graphic
• The Android store icon
• The Apple app store store icon
• The aircraft top view image for the app icon and runway diagram.

The common/ directory holds the sources shared by all apps.

The source/service/ directory

This directory contains the server-side PHP files that implement each app's API. It contains a common/ directory with the service files, which are the same for all apps, and a directory for each app named by the appId that holds the app's .htaccess file. The .htaccess file rewrites the app's API requests to the common files and sets the POH_APP environment variable to the app's appId. The web build copies .htaccess to the app's root and the PHP files to its service/ directory.

The directory also holds the files make serve uses to run the services locally: localRouter.php, a PHP router that does what .htaccess does on the production server, localBsConfig.js, the browser-sync configuration, and localIndexTemplate.html, the template for the development server's index page.

The source/cdv/ directory

This directory contains the files needed to build Cordova native apps. Each app has a directory named by its appId that contains a Cordova config.xml, a res/ directory of native app image resources, and the logo image for the splash screens. The native apps themselves are built in the private release repository. See Native apps.

The build/ directory

The build directory contains the results of the build process. It contains the following directories:

• build/cdv/
  The Cordova source image for each app under a directory named by the appId. Each holds the app's config.xml, res/, and a www/ directory with the app.
• build/doc/
  The HTML files converted from the Markdown in the doc/ directory.
• build/lint/
  The eslint results for each JavaScript source file. This allows the build process to detect which files need to be linted without linting all files.
• build/web/
  The web server image for each app under a directory named by the appId. Each holds index.html, the service worker, .htaccess, the service/ PHP files, the externalData files, and the app itself under a directory named with the build timestamp.

The doc/ directory

This directory contains all the project documentation as Markdown files. make doc converts them to HTML in build/doc/. See Building the documentation.

• index.md
  The documentation's front page.
• history.md
  The history of the POH Performance apps.
• markdownStyle.css
  The stylesheet for the generated HTML.
• app/
  Guides to individual apps.
• dev/
  The development guides: this document, the Development Process Guide, the Scripts Reference, the Coding Style Guide, the User Interface Style Guide, and How to Use the POH Performance Digitizer.
• mvcs/
  The MVCS reference documents, and the generated mvcs_index.md that indexes them.