CCM-1234: Update Readme

README.md

@@ -1,116 +1,259 @@
 # NHS Notify Template Management (WebUI) Repository
 
-## Setting up locally
+This repository contains the **Template Management Web UI** for NHS Notify.
 
-### Git
+It provides an interface for:
 
-- Make sure you have GitHub access with the right permissions
-- Setup git locally on your machine
-- Set your local git email as you `*@nhs.net` email `e.g. git config --global user.email "firstname.lastname1@nhs.net"`
-- Setup commit signing (this is required before you can commit any code to the repository). This is a very good resource to help Mac users `https://gist.github.com/troyfontaine/18c9146295168ee9ca2b30c00bd1b41e`
-- Pull the repository here `git@github.com:NHSDigital/nhs-notify-web-template-management.git`
+- Creating and managing message templates (NHS App messages, email, SMS and letters)
+- Configuring routing rules for message delivery
+- Previewing and submitting templates into the wider Notify platform
 
-### Development and Tools
+This project is **not just a frontend app** it’s a full stack application that depends on:
 
-- Install `asdf` [HERE](https://asdf-vm.com/guide/getting-started.html#_2-download-asdf). We use this tool to manage the required version for packages (this can be found in the `.tool-versions` file at the root of the project) on the project. You can use other tools usch as `brew`, `apt`, etc, but you will be risking having different package versions to other developers.
-- Then you need to install the following plugins:
+- AWS infrastructure (via Terraform)
+- Backend services (lambdas)
+- Shared platform components
+
+Local development requires provisioning real cloud resources inside of sandbox environments. Each developer can provision their own sandbox environment and point a locally running instance of the Next.js app the provisioned environment.
+
+## Project Structure
+
+- frontend - Contains the main web UI application (Next.js)
+- lambdas - Serverless backend functions
+- infrastructure - Terraform infrastructure definitions
+- packages - Shared code across workspaces
+- scripts - Utility scripts used by the repository
+- tests - Higher-level E2E, component and contract tests
+- utils - General-purpose helpers not tied to a specific workspace
+
+## Prerequisites
+
+Before getting started, you should have:
+
+### Access & Accounts
+
+- Github access to this repository
+- AWS account access (with permissions to provision infrastructure OR someone has provisioned resources on your behalf)
+- NHS email configured for git (`*@nhs.net`)
+- Be a member of the [NHS Digital](https://github.com/NHSDigital) Github organisation
+
+### Installed Tools
+
+We standardise tooling using `asdf`:
+
+- [asdf](https://asdf-vm.com/)
+- Node.js (via asdf)
+- Terraform (via asdf)
+- AWS CLI
+- Git
+
+## Setup
+
+### 1. Clone the repository
 
 ```shell
-  asdf plugin add nodejs
-  asdf plugin add direnv
-  asdf plugin add terraform
-  asdf plugin add gitleaks
-  asdf plugin add pre-commit
+git clone git@github.com:NHSDigital/nhs-notify-web-template-management.git
+cd nhs-notify-web-template-management
 ```
 
-- Now you can install the tools, and they will be runnable from within the `nhs-notify-web-template-management` directory:
+---
+
+### 2. Configure Git
 
 ```shell
-  asdf install
+git config --global user.email "firstname.lastname@nhs.net"
 ```
 
-- Now you can run the command below to install the packages in the project:
+You must also enable commit signing (required for commits).
+
+Helpful guide:
+<https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits>
+
+#### 2.1 Githooks
+
+Run the following command to setup a pre-commit git hook that performs several linting and validation checks before any changes are committed. The same steps will be run in the CI pipeline when you open a pull request.
 
 ```shell
-  npm install
+make githooks-config
 ```
 
-### Environment Variables and .env.template
+---
 
-This repository provides a `.env.template` file at the root. This file contains example environment variables required for local development and deployment.
+### 3. Install tooling (asdf)
 
-**How to use:**
+```shell
+asdf plugin add nodejs
+asdf plugin add direnv
+asdf plugin add terraform
+asdf plugin add gitleaks
+asdf plugin add pre-commit
 
-1. Copy `.env.template` to a new file named `.env` in the same directory:
+asdf install
+```
 
-   ```shell
-   cp .env.template .env
-   ```
+---
 
-2. Open `.env` and update the values as needed for your environment. For example, set your GitHub personal access token and username:
+### 4. Install dependencies
 
-   - `GITHUB_TOKEN` – Your GitHub Personal Access Token with packages:read permissions.
-   - `GITHUB_ACTOR` – Your GitHub username associated with the token
+```shell
+npm install
+```
 
-3. Save the file. The application and scripts will now use these environment variables.
+## AWS Setup
 
-**Tip:**
+To run the project e2e you will need to provision resources in an AWS sandbox environment. Alternatively, someone else in the team can do this for you and this step can be skipped.
 
-- Keep `.env` files out of version control. The `.env.template` is provided as a reference for required variables.
+Similarly, to run playwright tests locally you will need permissions to access the infrastructure you're pointing to so that test data can be automatically seeded. If this is not configured properly then tests will fail during their
+setup phase.
 
-### Running the project locally
+### Install AWS CLI
 
-1. To create a Terraform backend sandbox, run:
+```shell
+asdf plugin add awscli
+asdf install awscli
+```
 
-   ```shell
-   npm run create-backend-sandbox <environment-name>
-   ```
+### Configure credentials
 
-2. Then in a separate terminal, run the app locally:
+Configure access to the AWS template management dev account
 
-   ```shell
-   npm run dev
-   ```
+```shell
+aws configure
+```
+
+Or via SSO:
+
+```shell
+aws configure sso
+```
 
-3. Open your browser and go to `localhost:3000` to view the app.
+Make sure a default profile is setup.
 
-4. To destroy a Terraform backend sandbox, run:
+```shell
+export AWS_DEFAULT_PROFILE={PROFILE_NAME_YOU_SETUP}
+```
+
+## Running Locally
+
+### 1. Create root .env
+
+```shell
+cp .env.template .env
+```
 
-   ```shell
-   npm run destroy-backend-sandbox <environment-name>
-   ```
+Update required values:
 
-5. (Optional) Create a `.env` file at `frontend/.env` and add `INCLUDE_AUTH_PAGES=true` to include the local auth pages when doing a production Next build
+- **GITHUB_TOKEN**: This is a Github Personal Access Token with packages:read permissions and configured access to the NHS Digital Github organisation. (Only needed if provisioning sandbox infrastructure)
 
-### Other commands
+---
 
-- Unit test `npm run test:unit`
-- Accessibility test `npm run test:accessibility`
+### 2. Generate frontend .env file
 
-You can find more commands in the `package.json` file
+```shell
+npm run create-env-file
+```
 
-### Running Team and IAM Web Auth projects locally
+---
 
-Read more in the [README.md](./local/README.md).
+### 3 Setup a sandbox environment
 
-### Project structure
+#### 3.1 Use an existing output
 
-- components `./src/components`
-- pages `./src/app`
-- SCSS Styles `./src/styles`
-- App contents `./src/content
-- Unit tests (Components) `./src/__tests__/components`
-- Unit tests (Pages) `./src/__tests__/pages`
-- Utilities functions `./src/utils`
-- Types `./src/types`
+If someone else has provisioned a sandbox environment for you and setup the clients and user login then you just need the output file `sandbox_tf_outputs.json`. Copy this to the root of the repo and run the command
 
-### Shared Terraform Modules
+```shell
+npm run create-amplify-outputs
+```
 
-Before you setup modules for this repository and find that there might be modules that can be reused elsewhere, please do check out `https://github.com/NHSDigital/nhs-notify-shared-modules/`. If you find that the modules are shareable, you should set them up there as a separate PR and get that merged in and potentially tag the commit after testing it, so that it can be a stable release that can be used across all repos on Notify should others find the need to re-use that new module. You can simply point to the reference in your module call as below:
+#### 3.2 Or provision your own
 
-```hcl
-module "amp_branch" {
-  source = "git::https://github.com/NHSDigital/nhs-notify-shared-modules.git//infrastructure/modules/amp_branch?ref=v1.0.0"
-  ...
-}
+```shell
+npm run create-backend-sandbox -- {YOUR_SHORTCODE_HERE}
 ```
+
+This step will provision infrastructure and deploy any backend services required by the frontend.
+
+Each sandbox environment should have a unique identifier to differentiate their provisioned resources under the same AWS account. Any short string of text can be passed in as an argument but devs typically use their HSCIC account shortcode so resources belonging to their environment can be easily identified.
+
+#### 3.3 Seed clients and a user
+
+Running this will seed clients into SSM and create a user within Cognito with the email and password provided so that you can log into the frontend once it's running.
+
+```shell
+npm run sandbox-auth -- {EMAIL} {PASSWORD}
+```
+
+---
+
+### 4. Start the app
+
+Start the Next.js development server.
+
+```shell
+npm run dev
+```
+
+Alternatively, use the following command to use an optimised production build of the frontend. (useful for running playwright tests)
+
+```shell
+npm run build --workspace frontend && npm run start --workspace frontend
+```
+
+---
+
+### 5. Destroy sandbox (Optional)
+
+```shell
+npm run destroy-backend-sandbox -- {YOUR_SHORTCODE_HERE}
+```
+
+## Running Tests
+
+### Unit Tests
+
+```shell
+npm run test:unit
+```
+
+Use the `--u` argument to update snapshots after an intentional implementation change.
+
+```shell
+npm run test:unit -- --u
+```
+
+### Playwright
+
+All playwright tests are in the directory `/tests/test-team`
+
+Assuming the following prerequisites are met
+
+- Provisioned sandbox environment
+- Valid `sandbox_tf_outputs.json` file at the repository root
+- Local AWS credentials configured with default profile
+
+Test suites can be run with the following commands. This will run each test suite using the CLI.
+
+```shell
+npm run test:accessibility
+npm run test:api
+npm run test:backend
+npm run test:component
+npm run test:e2e
+npm run test:routing-component
+```
+
+Alternatively, use the Playwright UI to run tests using the command
+
+```shell
+npx playwright test --ui -c {CONFIG}
+```
+
+Configs for each test suite can be found under `/tests/test-team/config`.
+
+Example: Run Playwright UI for e2e tests
+
+```shell
+npx playwright test --ui -c config/e2e/e2e.config.ts
+```
+
+These commands will automatically build and run an optimised production version of the frontend if there isn't one already running.

package.json

@@ -47,6 +47,7 @@
     "build": "npm run create-env-file && npm run build --workspace frontend",
     "create-amplify-outputs": "tsx ./scripts/create-amplify-outputs.ts",
     "create-backend-sandbox": "./scripts/create_backend_sandbox.sh",
+    "sandbox-auth": "./scripts/sandbox_auth.sh",
     "create-env-file": "tsx ./scripts/create-env-file.ts",
     "destroy-backend-sandbox": "./scripts/destroy_backend_sandbox.sh",
     "dev": "npm run dev --workspace frontend --if-present",

scripts/config/vale/styles/config/vocabularies/words/accept.txt

@@ -1,14 +1,19 @@
+asdf
 Bitwarden
 bot
 Cognito
+Configs
 Cyber
 Dependabot
+dev
+devs
 draw.io
 drawio
 endcapture
 endfor
 endraw
 Git[Hh]ub
+Githooks
 GitHub
 Gitleaks
 Grype
@@ -21,10 +26,14 @@ onboarding
 Podman
 Python
 rawContent
+repo
 sed
+Serverless
+shortcode
 Syft
 Terraform
 toolchain
 Trufflehog
+utils
 [Vv]alidators
 Zod