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
Metadata
In the root directory, we have several metadata files. These are further organized by technology or purpose.
For Humans
-
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.
-
USAGE.md describes how to install, configure, and use the project from a sysadmin's point
of view.
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
code analysis.
-
.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
-
.babelrc configures the Babel JavaScript compiler
-
tsconfig.json configures the TypeScript compiler
-
webpack.config.js configures the WebPack JavaScript uglifier, optimizer, and packer
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
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)
-
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
of this.
-
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.
Other directories
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
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 you regular file system. This is done so that the
database
settings and records exist between runs.