2021 Call for Code Awards: Live from New York, with SNL’s Colin Jost! Learn more

Truth Loop: Increase your legal awareness

Currently, concerned and impacted citizens don’t have a straightforward way of knowing what or how policies, regulations, and legislation (referred to in this tutorial as either Legislative Artifacts or PR&L) impact them or what they can do in response.

The main idea behind this solution is to provide a platform that is capable of storing curated PR&L information, as determined by the community it serves. The goal is to provide a mobile-friendly way for users to examine that PR&L, increasing their legal awareness, and allowing them to communicate their reactions and thoughts through the recording of video testimonials to be shared with the community and the people responsible for the creation of the PR&L.

With this solution, you should be able to:

  • Readily understand the PR&L language and intent without being a legal expert
  • Sort or filter the PR&L efficiently
  • Digest an understandable summary of PR&L
  • Explore related or supporting information, advocacy groups, and other PR&L
  • Make a determination of whether the PR&L will have an impact on you
  • Communicate the potential effects of the PR&L on your life, family, or community to the author or sponsor of the legislation
  • Share your stories and experiences with fellow residents and policy makers
  • See what other people in the community are saying
  • Get an idea of the general sentiments people have expressed about the PR&L
  • Develop a dialogue between residents, PR&L authors, and sponsors

Learning objectives

The goals of this tutorial are for you to learn about how a community could deploy the solution to spread legal awareness, and for you to become familiar with the technologies involved. Once you have explored the initial implementation, you should also be equipped to consider if and how you would like to be further involved in contributing to this open source solution.


The following prerequisites are required to follow or run this solution:

Estimated time

It should take you approximately 30 minutes to complete this tutorial.

Architecture diagram

Architecture diagram

This solution combines the use of a media server (currently IBM® Watson Media) and data storage to hold the curated legislative artifacts, and the meta-data to link these together.

  1. The user launches the web app (on either a mobile or laptop/desktop device) and can view the range of curated legislative artifacts that have been created. The Vue app retrieves these by sending a REST request to the API server, which extracts them from the SQL database.
  2. The user can post their own (video) story that might support or challenge the legislated artifacts, which are uploaded to the API server, which then directs these to the Watson Media services. The API server also stores a reference to the video location in the respective legislative artifact in the SQL database.
  3. The user can view video stories by other peoples, which are retrieved by sending a REST request to the API server, which, after looking up the ID of the video in the SQL database, extracts them from Watson Media services.


  1. Provision a Postgres instance on IBM Cloud.
  2. If you want to use the video services, provision an instance of Watson Media.
  3. Configure and run the server.
  4. Configure and run the client application.

Provision a PostgreSQL instance

The server requires an RDMS server and currently only supports PostgreSQL. You can deploy this in IBM Cloud by logging in to IBM Cloud and provisioning a PostgreSQL instance. Note that this requires a paid plan. However, if you have just signed up for a new IBM Cloud account, you received cloud credits, which would cover this for a significant time.

  1. Choose your databases for the Postgres plan. You should choose an appropriate region and give the service a name. You can leave the other settings with their defaults. Click Create.
  2. After your Postgres instance has been created, you must create a service credential that the API server can use to communicate with. By selecting your running Postgres instance, you can choose Service credentials from the left menu. Create a new service credential and give it a name (it doesn’t matter what you call it).
  3. After the service credential is created, you can display the credentials by selecting View service credentials. Copy the credential so that you are ready to paste parts of it into the environment file of the API server in Step 3.

Alternatively, you could deploy your own PostgreSQL instance locally or in a remote virtual machine or container. In this case, ensure that you obtain the equivalent credentials to those described above for Step 3.

Set up an instance of Watson Media

Log in to IBM Cloud, and provision a Watson Media instance.

  1. Provision an instance of Watson Media. You can use the 30-day free-trial to start.
  2. After your Watson Media instance has started, go to API/SDK access under Integration & Apps in the left menu.
  3. Create a new credential. You must enter an Application Name (you can chose anything) and a Redirect URL. This URL must be the prefix of the url you will be running the server on, for example, <http://localhost>. Note the client id and client secret because you need these in Step 3.
  4. Generate a device username and password to be used by your server by going to Device passwords in the same API/SDK access menu. Give your device any name you choose, then click Create password. Note the username and password that are generated because you will also need these in Step 3.

Configure and run the server

To set up and launch the server application:

  1. Go to the server directory of the cloned repo.
  2. Copy the .env.example file, and create a new file named .env.
  3. If your PostgreSQL server uses SSL (like IBM Cloud), then create a file to hold the SSL certificate. For the IBM Cloud version of PostgreSQL, it is shown in the certificate: certificate_base64 attribute of the service credential that you obtained in Step 1. Copy the raw contents of this attribute into the file that you created.
  4. Update the newly created .env file, and update the DB_HOST, DB_USERNAME, DB_PASSWORD, DB_PORT, and DB_DATABASE_NAME with the values from credential that you obtained when you created the database instance in Step 1. If you created a certificate file in the previous action, then also update the DB_CERTFILE with the location of this file (relative to the server directory).
  5. Update the CMS_USERNAME, CMS_PASSWORD, CLIENT_ID, and CLIENT_SECRET with the values from creating your instance of Watson Media in Step 2.
  6. Prepare to initialize the database with the correct tables. Scripts are provided that do this using the psql cli, which we recommend that you install. For example, on macOS you can do this with the brew command: brew install libpq. You might also like to link the psql command to your local bin directory with brew: link --force libpq.
  7. To install the tables, you can use the ./psql_create_tables.sh script.
  8. If you would like to install sample data into the database for testing, then use the ./psql_refresh_sample_data.sh script.
  9. To actually run the server, from a terminal, in the server directory of the cloned repo:
    1. Install the dependencies using the npm install command.
    2. Launch the server application locally or deploy to IBM Cloud:
      • To run locally:
        1. Start the application by using the npm start command.
        2. The server can be accessed at the address given, typically, <http://localhost:5000>.
      • To deploy to IBM Cloud in Cloud Foundry:
        1. Edit the name value in the manifest.yml file to be a unique application name (for example, my-legislative-server).
        2. Log in to your IBM Cloud account using the IBM Cloud CLI: ibmcloud login.
        3. Target a Cloud Foundry org and space: ibmcloud target --cf.
        4. Push the app to IBM Cloud: ibmcloud app push.
        5. The server can be accessed at the routes URL displayed in the output of the push command (for example, <my-legislative-server.eu-gb.mybluemix.net>).

After the server is running, you can test it by accessing the client, admin, and API user interfaces. If running locally, these URLs are:

For example, you can use the openAPI docs interface to explore and try out the API using the /api-docs endpoint, which should look something like the following image.


The admin UI provides web pages as a convenience for an administrator to manually list, add, edit, and delete PR&L and related information. All of these tasks can also be automated using the REST API.

After an administrator has added some PR&L and related information, you can try out the client UI. See the next section for more details about running the client separately as a developer.

Configure and run the client application in development mode

To configure and run the client application as a developer:

  1. Go to the client directory of the cloned repository.
  2. Copy the .env.example file to a new file named .env
  3. Edit the newly created .env file, and update the SERVER_URL with the URL to the server app launched in the previous step (for example, <http://localhost:5000>).
  4. From a terminal:

    1. Install the dependencies by using the npm install command.
    2. Run the development Vue server using the npm run serve command.
    3. After the development server is running, you should be able to access the client from the URL indicated (typically, http://localhost:8080/).
    4. If you are running a mobile simulator, you can also access the same url. For example, in the iOS simulator, the screen would look similar to the following image.

      Intro Screen

Using the client, you should be able to interact with the data stored in the server, as well as post new information. As you execute items in the client, you see the API commands that the server is responding to (by watching the console of the server). You can try driving the server manually through its admin UI or its openAPI interface (or by issuing the equivalent curl commands), perhaps developing your own ideas on different ways in which this data could be displayed.

Summary and further learning

You have explored this initial solution for providing legal awareness to communities. We welcome your further involvement. Become an active contributor to the Truth Loop solution GitHub repository (see the Contributing section in the README file) and help make a change.

As a developer, you can take a stand and apply your skills and ingenuity to make a difference. Learn how you can be a part of a motivated community of developers and supporters working to evolve the Call for Code for Racial Justice open source solutions.