OED 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
In the root directory, OED has several metadata files. These are further organized by technology or purpose.
- 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
- 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
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
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
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
- 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
- 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.
All backend code is stored in
src/server/, except for the executable server, which is
Beneath that, there are several folders:
- data/ functions to generate test data (not used directly by the application but for
- middleware/ middleware for dealing with web requests.
- migrations/ contains SQL files that are used to upgrade between database versions.
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.
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 are stored in
The scripts are as follows:
- checkHeader.sh verifies that all source files have the MPLv2 legal header. It is run in
- 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.
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.
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.