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
- Deployment and Analysis Scripts
In the root directory, we have several metadata files. These are further organized by technology or purpose.
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
USAGE.md describes how to install, configure, and use the project from a sysadmin's point
For Development Tools
- client.js does database setup for GitHub Action CI.
.editorconfig conveys some of our basic style rules to most common code editors.
- .github/workflows/ has two .yml files for GitHub Actions: one for CI and one for static
.gitignore informs the Git Version Control System about files that it should not track.
.gitattributes informs Git about how to properly show diffs for our files.
.travis.yml configures the Travis Continuous Integration service. We are now using GitHub
Actions for CI but this file is left.
tslint.json configures the TSLint code quality tool and style checker
For Code Transformers
tsconfig.json configures the TypeScript compiler
For Dependency Management Tools
.npmrc specifies default dependency management behavior for the Node.js Package Manager
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
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
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 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.
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
installOED.sh sets up OED, either for development for production, creating the database
schema and installing dependencies. This is often run using
docker compose up or some variant
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.
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.
You will see other directories in the OED code base as you 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
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 you regular file system. This is done so that the
settings and records exist between runs.