Code Organization

The OED code base is organized into directories. Understanding the structure of this layout can help in working on the code.

The project is organized into a number of subdirectories. The primary division is among:

• Metadata, configs, and deployment information
• Frontend code
• Backend code
• Common code
• Other directories

Metadata

In the root directory, OED has several metadata files. These are further organized by technology or purpose.

For Humans

• CODE_OF_CONDUCT describes conduct expectations and how to report any concerns.
• CONTRIBUTING.md provides information on contributing to OED.
• License.txt describes the legal aspect of the project. OED is licensed under the Mozilla Public License version 2.0.
• README.md is an overview of the project, displayed on the GitHub front page for the project.
• Security.md describes how to report security concerns to OED.
• Support.md describes where to get information on support related to OED.
• USAGE.md describes how to install, configure, and use the project from a sysadmin's point of view.

For Development Tools

• .devcontainer/ has files to set up the Visual Studio Code container.
• .github/ ISSUE_TEMPLATE/ has GitHub issue template, workflows/ has two .yml files for GitHub Actions: one for CI and one for static and dependabot.yml controls GitHub automated pull requests.
• .vscode/ contains (currently nonworking) instructions to run OED within Visual Studio Code.
• .dockerignore defines files that Docker ignores.
• .editorconfig conveys some of our basic style rules to most common code editors.
• .eslintignore defines files to include in ESLint checking.
• .eslintrc.json defines the ESLint rules
• .gitattributes informs Git about how to properly show diffs for our files.
• .gitignore informs the Git Version Control System about files that it should not track.
• client.js does database setup for GitHub Action CI.
• tslint.json configures the TSLint code quality tool and style checker

For Code Transformers

• babel.config.json configures the Babel JavaScript compiler
• webpack.config.js configures the WebPack JavaScript uglifier, optimizer, and packer

For Dependency Management Tools

• .npmrc tells node package versions to allow on install
• docker-compose.yml specifies how to collect the database and web/vsc Docker containers together into a working deployment
• the containers/ directory contains everything needed to build the Docker containers with subdirectories for the database and web (along with proxy if needed).
• .dockerignore tells the Docker containerization engine which files to ignore
• package.json specifies direct dependencies and some package metadata
• package-lock.json specifies working direct and transitive dependencies used on the last build committed

Frontend Code

All frontend code is stored in src/client/app/. This is the code that actually runs in the user's web browser. See the technologies page for a diagram showing how this code is transpiled and minified prior to delivery.

This code is contained in several directories:

• actions/ are the messages that components send to reducers to change the application state.
• components/ are the React.js components which generate HTML that is displayed on the page. Components can be combined and composed to create the UI that is displayed to the user.
• containers/ connect the React.js components to the application state (managed by Redux) through props and dispatched actions.
• reducers/ accept messages sent by components and change the global application state accordingly.
• style/ CSS files for the website.
• translations/ defines the strings used to make OED multilingual.
• types/ define the datatypes used throughout the frontend.
• utils/ defines functions used across the application and some APIs.

Backend Code

All backend code is stored in src/server/, except for the executable server, which is src/bin/www/.

Beneath that, there are several folders:

• data/ functions to generate test data (not used directly by the application but for testing).
• middleware/ middleware for dealing with web requests.
• migrations/ contains SQL files that are used to upgrade between database versions.
• models/ contains classes which connect JavaScript code to the database so that routes can actually interact with data.
• routes/ contains functions defining the actual URLs that the server provides, which is how the frontend interacts with the server.
• services/ contains scripts used by developers and administrators to modify the data in ways that are inaccessible through the web interface.
• sql/ contains the database queries used by models to talk to the PostgreSQL database.
• test/ contains the test code run for validation of OED.
• utils/ contains utility functions and constants.

Common Code

All common code is stored in src/common/. This code defines data types which are in shared use between the client and the server.

Scripts

Scripts are stored in src/scripts/.

The scripts are as follows:

• checkHeader.sh verifies that all source files have the MPLv2 legal header. It is run in CI.
• checkMeters.sh verifies if a file of IP addresses has meters that respond. Used for testing meters or before input of meters into OED. Mostly targets MAMAC meters that are web based.
• checkTypescript.sh verifies that there are no untyped JavaScript files in the client tree. It is run in CI.
• devcheck.sh runs all the checks (header, typescript, types and lint) in one easy step.
• devstart.sh starts both the webserver and Webpack, in dev mode (watches files and shows interactive). This isn not normally used to start OED for developers.
• installOED.sh sets up OED, either for development or production, creating the database schema and installing dependencies. This is often run using docker compose up or some variant of this. It should be automatically run inside toe VSC container.
• oed.service is a sample systemd unit file which allows Linux system administrators to start OED on startup.
• refreshReadingViewsCron.bash is a script meant to be run at regular intervals (for instance, with cron) which updates the daily view table that is needed to graph OED data.
• refreshDailyReadingViewsCron.bash is a script meant to be run at regular intervals (for instance, with cron) which updates the hourly view table that is needed to graph OED data.
• sendLogEmailCron.bash is a script meant to be run at regular intervals (for instance, with cron) which sends an email with information from OED logging since the last time this ran.
• updateEgaugeMetersOEDCron.bash is a script meant to be run at regular intervals (for instance, with cron) which updates eGauge-brand meters.
• updateMamacMetersOEDCron.bash is a script meant to be run at regular intervals (for instance, with cron) which updates Mamac-brand pull-type meters.
• updateOED.sh To be run after pulling the latest version from Git. Grabs new dependencies and migrates the database.

Other directories

One will see other directories in the OED code base after install and work with OED. These are not normally changed by someone. A few noticeable ones are:

• node_modules/ is created during the npm install process and contains information on all node packages used.
• postgres-data/ is created during the PostgreSQL install process and contains the information about the database and all records stored. It is the one set of files that exist between runs of the Docker container and are linked from the Docker container to the regular file system. This is done so that the database settings and records exist between runs.