{"id":20029475,"url":"https://github.com/truevault-safe/truevault-react-js-sample-app","last_synced_at":"2026-03-02T08:02:29.987Z","repository":{"id":22037178,"uuid":"93584464","full_name":"truevault-safe/truevault-react-js-sample-app","owner":"truevault-safe","description":"A React Sample Application that integrates with TrueVault for HIPAA Compliance","archived":false,"fork":false,"pushed_at":"2023-01-24T19:03:41.000Z","size":4094,"stargazers_count":28,"open_issues_count":32,"forks_count":19,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-05-05T03:35:16.788Z","etag":null,"topics":["react","sample-app","sample-code","truevault"],"latest_commit_sha":null,"homepage":"https://www.truevault.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/truevault-safe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-06-07T02:38:00.000Z","updated_at":"2023-10-19T01:42:46.000Z","dependencies_parsed_at":"2023-02-14T00:45:27.912Z","dependency_job_id":null,"html_url":"https://github.com/truevault-safe/truevault-react-js-sample-app","commit_stats":null,"previous_names":["truevault-safe/truevault-react-js-sample-app"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/truevault-safe/truevault-react-js-sample-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truevault-safe%2Ftruevault-react-js-sample-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truevault-safe%2Ftruevault-react-js-sample-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truevault-safe%2Ftruevault-react-js-sample-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truevault-safe%2Ftruevault-react-js-sample-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/truevault-safe","download_url":"https://codeload.github.com/truevault-safe/truevault-react-js-sample-app/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truevault-safe%2Ftruevault-react-js-sample-app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29995910,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["react","sample-app","sample-code","truevault"],"created_at":"2024-11-13T09:20:22.655Z","updated_at":"2026-03-02T08:02:24.964Z","avatar_url":"https://github.com/truevault-safe.png","language":"JavaScript","readme":"# TrueVault React Sample App\n\nThis is a sample app demonstrating how to build a collaborative diagnosis tool with TrueVault. There are three high-level components to keep in mind: \n\n1. The front-end JS App, which uses React \u0026 Redux. The code is in the `src` directory. \n1. A custom backend server, written in Node. The code for this is in the `server` directory.\n1. TrueVault. You can see interactions with TrueVault by looking for usages of the functions in the `tv.js` file.\n\nThis application has these three components to demonstrate the most common real-world use of TrueVault. All Personally Identifiable Information (PII) is stored in TrueVault, and only de-identified metadata is stored in the custom (less secure) server environment. This shows the \"fast path\" to HIPAA compliance, since the de-identified data can be stored and processed by non-compliant infrastructure.\n\n## Table of Contents\n\n  * [Overview](#overview)\n  * [Running the App](#running-the-app)\n    * [Pre-reqs](#running-the-app)\n    * [Postgres Database Setup](#posgres-database-setup)\n    * [Run App Setup Script](#run-app-setup-script)\n    * [Run Node Server](#run-node-server)\n    * [Run Client Server](#run-client-server)\n  * [Sample App Walkthrough](#sample-app-walkthrough)\n  * [Architecture](#architecture)\n    * [Data bifurcation](#data-bifurcation)\n    * [Groups](#groups)\n    * [Creating a case](#creating-a-case)\n    * [Retrieving a case](#retrieving-a-case)\n    * [Reviewing and approving a case](#reviewing-and-approving-a-case)\n  * [Exploring The Code](#exploring-the-code)\n  * [Questions](#questions)\n  * [Issues](#issues)\n  * [License](#license)\n\n## Overview\nTo run this app, you will need to create a TrueVault trial account for the sample app to interact with live. You will also need to run a Postgres database locally and run a setup script that populates data in TrueVault and Postgres. Finally you will need to run the Node app and React app servers locally using the config file generated by the setup script.\n\nOnce you can run the sample app locally, we recommend exploring the UI to get a feel for the sample product, then peeking at the source to see how TrueVault fits in. \n\n## Running the App\n\n*Note:* This app has only been tested using the latest version of Chrome.\n\n### Pre-reqs\n1. Install [yarn](https://yarnpkg.com). On OSX you can run `brew install yarn`\n1. Install [Docker Compose](https://docs.docker.com/compose/install/).\n1. Create a [trial TrueVault account](https://console.truevault.com/register) and find two UUIDs: Account Id and Admin API Key. The **Account ID** is shown here: https://console.truevault.com/account, and the **Admin API Key** can be generated by:\n    1. Create a new user (https://console.truevault.com/users) and copy the User ID.\n    1. Go to the `FULL_ADMIN` group (https://console.truevault.com/groups), click \"Add\" next to Users, and paste in the User's UUID.\n    1. Return to the User's view, and re-assign the API Key for that user. That UUID is the **Admin API Key** you'll need below for the app setup script.\n1. Create a [trial SendGrid account](https://app.sendgrid.com/signup) if you don't have one, and follow their [instructions](https://sendgrid.com/docs/Classroom/Send/How_Emails_Are_Sent/api_keys.html) for creating your **SendGrid API Key**. Make sure it has the *Mail Send* and *Full Access Template Engine* permissions.\n\n### Postgres Database Setup\n1. Change into the server directory: `cd server`\n1. Start Postgres: `docker-compose up -d`\n1. Set up the database: `./setup-dev-db.sh`\n    1. If needed, customize which `psql` to use by setting the `PSQL` variable, e.g. `PSQL=psql92`.\n1. Change back to the root directory for the next steps: `cd ..`\n\n### Run App Setup Script\n1. Install dependencies for client code: `yarn`\n1. Install dependencies for server code: `cd server \u0026\u0026 yarn \u0026\u0026 cd ..`\n1. Configure your TV account and generate a new `.env` file by running:\n\n        yarn tv-account-setup -- --account-id [Account ID] --admin-api-key [Admin API Key] --sendgrid-api-key [SendGrid API Key] --generate-dummy-data | tee output.txt\n\n   * See [Pre-reqs](#pre-reqs) for details on where the command line arguments come from.\n1. **Important!** Keep track of the output of the setup script, it shows generated login credentials for Admin and Doctor Users as well as IDs of resources created. You can reference `output.txt` for user credentials as you progress through the walkthrough (if you kept the `| tee...` clause above.)\n\n### Run Node Server\n1. Change into the server directory: `cd server`\n1. Run the node server: `node index.js`. \n    * You'll need to `Ctrl-C` and re-run whenever you change the source.\n    * The client server will automatically proxy all API requests to the Node server component. Unfortunately, this proxy functionality relies on a hard-coded URL in the top-level `package.json`. This means that the Node server must run on port 3001.\n\n### Run Client Server\n1. Create a new tab or window in the root directory.\n1. Run `yarn start` to launch the development server. This command should automatically open a new tab or window in your default web browser. This tab will automatically refresh whenever you make changes to source code.\n    * Each time the setup script is run, you will need to stop the client server with `Ctrl-C` and rerun `yarn start` in order for the new `.env` config file to take effect.\n\n\n## Sample App Walkthrough\nNow that you have it running, you can use the output of the tv-account-setup script to log in and poke around. We highly recommend exploring the sample app by going through the [Sample App Walkthrough](WALKTHROUGH.md). We take an in-depth look at each view of the sample app and explain architectural decisions and how TrueVault secures the application along the way.\n\n## Architecture\n\n### Data bifurcation\n\nThe application stores patient cases, which contain personally identifiable information (PII) and unprotected metadata such as the current case status and associated user ID. PII is stored in TrueVault, and unprotected metadata is stored by the Node server:\n\n\u003cimg src=\"CaseDiagram.png\"\u003e\n\nSplitting the data allows us to store PII in TrueVault and everything else in the Node server. The PII enjoys access controls and transparent audit logging, while the metadata enjoys the convenience of a traditional relational store. Conceptually, this is similar to storing credit card numbers in Stripe or encryption keys in an HSM.\n\nEach case consists of two documents in TrueVault: one to store the patient's information, and one to store the diagnosis.\nThis division allows creating groups that allow doctors to view the entire case, but only update the diagnosis.\n\n### Groups\n\nThe application uses declarative [TrueVault Groups](https://docs.truevault.com/groups) to restrict access to PII, and\nimperative code in the server component to enforce workflow business rules.\n\nEach case has two groups: a read group, and a reviewer group. The read group allows members to view the case's 2 documents, and the reviewer group allows members to update the diagnosis document.\n\n### Creating a case\n\nCreating a single case involves creating the two TrueVault documents, the two TrueVault groups, and, a row in Postgres. The flow looks like this:\n\n1. Create the case document\n1. Create the diagnosis document\n1. Create the read group\n1. Create the reviewer group\n1. Create the metadata object in Node server\n\n### Retrieving a case\n\nLoading a case happens in roughly the opposite order:\n\n1. Load the case metadata from Node server, which provides the case and diagnosis TrueVault document IDs\n1. Load the case document\n1. Load the diagnosis document\n1. Combine all 3 results into a single object\n\n### Reviewing and approving a case\n\nSince the business logic around approving/reviewing a case is clearer to express via imperative code than declarative CRUD permissions, it's expressed in the server. Approving/reviewing a case invokes the following flow:\n\n\u003cimg src=\"ApproveCaseDiagram.png\"\u003e\n\n## Exploring the Code\nNow that you have it running, and understand the architecture, it's time to dive into the source. You can breeze through the small NodeJS server by looking at `server/index.js`. Read the comments at the top, and take a minute to get acquainted. Don't linger long, all the good stuff is in the client code. \n\nIf you're familiar with React/Redux, this application should be easy to explore. If you're not, dive right into the `src/actions.js` file. That file shows all the interesting architectural decisions, where we decide to send PII to TrueVault and de-identified information to our NodeJS server. This keeps us compliant, but let's us use server-side code for flexible analytics and business rule enforcement. From the `actions.js` source, you can trace the flow of logic in the application. Search for usages of actions in that file to see how the UI triggers server interaction. Drill down through methods you see used in these actions to see how we actually interact with TrueVault.\n\n## Questions\n\nIf you would like to learn more about how to build your project using TrueVault, please contact us at help@truevault.com or ask a question on [StackOverflow](https://stackoverflow.com/questions/tagged/truevault) with the tag `truevault`.\n\n## Issues\n\nIs part of the sample app confusing, broken, or incomplete? Let us know! We hope this is an easy to understand codebase and an easy to use app. If we've missed anything, file a GitHub issue or a PR and we'll take a look.\n\n## License\n\nThis sample app is released under the [BSD 3-Clause License](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftruevault-safe%2Ftruevault-react-js-sample-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftruevault-safe%2Ftruevault-react-js-sample-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftruevault-safe%2Ftruevault-react-js-sample-app/lists"}