SafetyWare API

This repository contains the API of the SafetyWare application. The frontend is in another repository.

Architecture

The following informal diagram shows data flow and the relationship between the API and other components.

Quickstart

Follow these steps if you need to run the API without making code changes.

1. Install Docker Desktop.
2. Run the API.

   docker compose up --build
   

3. Navigate to http://localhost:3001/playground.

Execute a GraphQL query

The API exposes all operations through GraphQL. A web interface is included for testing queries.

1. Start the API as described in the 'Quickstart' section.
2. Load sample data as described later in this document (optional).
3. Navigate to http://localhost:3001/playground.
4. Execute the following example query.

   {
     companies {
       id
       name
       people {
         id
         name
         locationReadings {
           timestamp
           coordinates
         }
       }
     }
   }
   

Develop

This section describes how to make code changes.

Install tools

1. Install Docker Desktop.
2. Install Rust Programming Language.

Configure CLion (optional)

CLion is the recommended IDE. CLI commands are also supported.

1. Open this repository in CLion.
2. Install required plugins when prompted.
3. Confirm the "Start containers" configuration is able to run.
4. Configure CLion to use Rustfmt.
   1. Press Ctrl + Shift + A to search actions.
   2. Search "Rustfmt" and open the first result.
   3. Enable "Use Rustfmt instead of built-in formatter" and "Run rustfmt on Save".

Run in CLion

1. Execute the "Run" configuration. Docker containers are started automatically.
2. Navigate to http://localhost:3001.
3. Stop the Docker containers in the Services tab before leaving.

Run with CLI

1. Start the Docker containers once per sitting.

   docker compose up -d --build mongo
   

2. Set environmental variables.

   $env:SW_DB_URI="mongodb://localhost:42781"
   $env:SW_PRIVATE_KEY="secret"
   $env:RUST_LOG="info"
   $env:RUST_BACKTRACE="1"
   

3. Build and run.

   cargo run -p api
   

4. Navigate to http://localhost:3001.
5. Stop the Docker containers before leaving.

   docker compose down
   

Test

1. Run the tests.

   .\script\Test.ps1
   

Sample data

This section describes how to load and save sample data. PowerShell Core is required.

Load sample data

1. Load sample data. Your existing database contents will be dropped.

   .\script\LoadSampleData.ps1 sample-data.gz
   

Save sample data

1. Save database contents as sample data.

   .\script\SaveSampleData.ps1 sample-data.gz
   

Deploy

This section describes how to deploy the API to the cloud.

Install tools

1. Install Azure CLI.
2. Install Azure Functions Core Tools.
3. Install Docker Desktop.
4. Install MongoDB CLI for Cloud.
5. Install PowerShell Core (not preinstalled PowerShell).
6. Install Rust Programming Language.

Sign up for cloud providers

1. Create a Microsoft Azure account.
2. Create a MongoDB Atlas account.

Configure CLI tools

1. Connect the Azure CLI to your Azure account.

   az login
   

2. Connect the MongoDB Cloud CLI to your MongoDB Atlas account.

   mongocli config
   

Publish the API

1. Publish the API to the specified environment. It will be publicly accessible.

   .\script\Publish.ps1 -Org cap -App sw -Env dev
   

   • You can pick something other than dev as the environment name, such as your name, to avoid name conflicts.

Unpublish the API

1. Unpublish the API and delete all cloud resources.

   .\script\Unpublish.ps1 -Org cap -App sw -Env dev
   

Generate GraphQL documentation

SpectaQL is used to automatically generate GraphQL documentation. The generated documentation is saved in the repository. It should not be edited manually.

1. Install NodeJS.
2. Install SpectaQL.

   npm install -g spectaql@0.12
   

3. Start the API locally.
4. Navigate to the doc directory.

   cd doc
   

5. Generate documentation.

   npx spectaql config.yml
   

6. Navigate to /doc/ to see documentation.

Create an admin user

When the application starts for the first time, there may be no users. An admin user is required to create other users through the API. The first admin user can be created manually. By default, accounts have no password.

1. Insert a temporary account into the database using MongoDB Shell.

   db.user_account.insertOne({
     _id: 'tempAdmin',
     name: '',
     access: 'admin',
     title: '',
     email: '',
     phone: '',
     company_id: '',
   })
   

2. Login with the temporary account using the GraphQL interface at /playground. Take note of the returned bearer token.

   mutation {
     login(userAccountId: "tempAdmin", password: "")
   }
   

3. In the HTTP headers tab at the bottom of the page, set the HTTP authorization header to the bearer token.

   {"Authorization": "Bearer {token}"}
   

4. Create a genuine admin account. Take note of the returned user account ID.

   mutation {
     createUserAccount(input: {
       name: "User A",
       access: ADMIN,
       title: "Chief Observer",
       email: "user.a@example.com",
       phone: "(111) 111-1111",
       companyId: ""
     }) {
       id
       name
     }
   }
   

5. Set a password for the new admin account.

   mutation {
     setUserAccountPassword(
       userAccountId: "{user account ID}",
       password: "{password}"
     )
   }
   

6. Delete the temporary admin account.

   mutation {
     deleteUserAccount(id: "tempAdmin")
   }