Code and documentation

Table of contents

How eRegulations works

Architecture

There are three primary parts to the eRegulations application: a parser that converts regulation text into data (regulations-parser), an API that hosts this data (regulations-core), and a webapp which uses the data from the API to construct beautiful and usable regulations (regulations-site).

One would typically run the parser against a regulation once (for each version) to populate the API with all the necessary data. regulations-site would then use regulations-core as necessary to display regulations.

Stack

regulations-parser is written in Python 2.7.

regulations-core is a Django and Haystack application.

The regulations-site front-end is a Backbone.js application using Browserify. We also use a Grunt-based build system with Mocha for unit testing. On the back-end, regulations-site is a Django application.

Repositories

There are many individual repositories that make up eRegulations. The project is divided into several components, and currently CFPB and 18F maintain two separate forks of regulations-parser, regulations-core, and regulations-site. 18F and CFPB plan to eventually merge these forks into shared components with maintenance shared between multiple agencies. 18F’s forks are hosted in the shared eRegs GitHub organization; for now, in most cases people interested in using eRegulations should use those repositories.

Tip: If you’d like to get an example eRegulations site set up to try it out, check out CFPB regulations-bootstrap to install a CFPB-centric version.

The main body of eRegulations (not agency-specific)

  • regulations-parser (Parse regulations)

    The parser effectively converts print-centric documents from the Federal Register, Government Printing Office, etc., pulls out semantic meaning from them (e.g. paragraph structures, citations, definitions), and writes those structures to a data store. The parser also contains tools to help developers debug this process.

  • regulations-core (Regulations API)

    The store for the parsed regulatory data.

  • regulations-site (Display the regulations)

    An intuitive, responsive UI for viewing the regulations. It combines all of the parsed data into an interface, providing in-line access to definitions, citations, external material and more. This is the primary use case for the regulatory data.

  • fr-notices (Edited source XML)

    Often, source files will need to be massaged and modified to fit the parser's limited understanding. This repository is a canonical source for these edits, across all agencies, so that developers remain in sync.

  • eregs.github.io (Documentation)

    The content for these HTML pages.

Agency-centric components

Consumer Financial Protection Bureau

  • regulations-parser (Parse regulations)

    The parser effectively converts print-centric documents from the Federal Register, Government Printing Office, etc., pulls out semantic meaning from them (e.g. paragraph structures, citations, definitions), and writes those structures to a data store. The parser also contains tools to help developers debug this process.

  • regulations-core (Regulations API)

    The store for the parsed regulatory data.

  • regulations-site (Display the regulations)

    An intuitive, responsive UI for viewing the regulations. It combines all of the parsed data into an interface, providing in-line access to definitions, citations, external material and more. This is the primary use case for the regulatory data.

  • regulations-bootstrap (Vagrant for quick setup)

    Vagrant files for quickly setting up a virtual machine in preparation for working with CFPB eRegs repositories.

  • regulations-schema (Regulation XML schema)

    An experimental XML schema for defining regulations. Regulations in this format could then be maintained by only editing a single XML file, rather than worrying about external sources of data. Currently, CFPB-centric.

  • regulations-xml-parser (Schema -> JSON for regulations)

    A companion to regulations-schema which takes XML following that schema and converts it into the format accepted by regulations-core.

  • regulations-stub (Parsed CFPB regulations)

    A cached set of CFPB regulations as JSON files, ready for importing into regulations-core.

Bureau of Alcohol, Tobacco, Firearms and Explosives

  • atf-eregs (ATF UI Elements)

    Static assets, deployment configuration, and UI plugins specific to ATF's instance of eRegulations.

Federal Election Commission

  • fec-eregs (FEC UI Elements)

    Static assets, deployment configuration, and UI plugins specific to FEC's instance of eRegulations.

Environmental Protection Agency

  • epa-notice (eManifest Pilot UI Elements)

    Pilot project highlighting eRegs' "Notice and Comment" feature. Includes static assets, deployment configuration, and UI plugins specific to EPA's eManifest ruling.

Open source and contributing

We invite contributions to any part of the application, from people inside and outside government. The project is in the public domain, and all contributions to it will be released as such. By submitting a pull request, you are agreeing to waive all rights to your contribution under the terms of the CC0 Public Domain Dedication.

If you contribute the open source work of others, please mark it clearly in your pull request.

Release policy

We follow semantic versioning and will cut releases once a quarter (if code has changed) or more frequently if downstream projects need them.