CCM-1234: Update Readme

README.md

@@ -1,116 +1,261 @@
-# NHS Notify Template Management (WebUI) Repository
+# NHS Notify – Template Management Web UI
 
-## 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
+## Overview
 
-- 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:
+This project is **not just a frontend app** it’s a full stack application that depends on:
+
+- AWS infrastructure (via Terraform)
+- Backend services (lambdas)
+- Shared platform components
+
+Local development requires provisioning real cloud resources inside of sandbox environments. Each dev can provision their own sandbox environment and point a locally running instance of the Next.js app the provisioned environment.
+
+## Project Structure
+
+```shell
+├── frontend - Contains the main web UI application (Next.js)
+├── infrastructure - Serverless backend functions
+├── lambdas - Terraform infrastructure definitions
+├── packages - Shared code across workspaces
+├── scripts - Utility scripts used by the repo
+├── tests - Higher-level E2E, component and contract tests
+└── utils - General-purpose helpers not tied to a specific workspace
+```
+
+- 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 repo
+- 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
+git config --global user.email "firstname.lastname@nhs.net"
+```
+
+You must also enable commit signing (required for commits).
+
+Helpful guide:
+<https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits>
+
+---
+
+### 3. Install tooling (asdf)
 
 ```shell
-  asdf install
+asdf plugin add nodejs
+asdf plugin add direnv
+asdf plugin add terraform
+asdf plugin add gitleaks
+asdf plugin add pre-commit
+
+asdf install
 ```
 
-- Now you can run the command below to install the packages in the project:
+---
+
+### 4. Install dependencies
 
 ```shell
-  npm install
+npm install
 ```
 
-### Environment Variables and .env.template
+## 🔐 AWS Setup
 
-This repository provides a `.env.template` file at the root. This file contains example environment variables required for local development and deployment.
+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.
 
-**How to use:**
+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.
 
-1. Copy `.env.template` to a new file named `.env` in the same directory:
+### Install AWS CLI
 
-   ```shell
-   cp .env.template .env
-   ```
+```shell
+asdf plugin add awscli
+asdf install awscli
+```
 
-2. Open `.env` and update the values as needed for your environment. For example, set your GitHub personal access token and username:
+### Configure credentials
 
-   - `GITHUB_TOKEN` – Your GitHub Personal Access Token with packages:read permissions.
-   - `GITHUB_ACTOR` – Your GitHub username associated with the token
+```shell
+aws configure
+```
+
+Or via SSO:
 
-3. Save the file. The application and scripts will now use these environment variables.
+```shell
+aws configure sso
+```
 
-**Tip:**
+Make sure a default profile is setup.
 
-- Keep `.env` files out of version control. The `.env.template` is provided as a reference for required variables.
+```shell
+export AWS_DEFAULT_PROFILE={PROFILE_NAME_YOU_SETUP}
+```
 
-### Running the project locally
+## Running Locally
 
-1. To create a Terraform backend sandbox, run:
+### 1. Create root .env
 
-   ```shell
-   npm run create-backend-sandbox <environment-name>
-   ```
+```shell
+cp .env.template .env
+```
 
-2. Then in a separate terminal, run the app locally:
+Update required values:
 
-   ```shell
-   npm run dev
-   ```
+- **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)
 
-3. Open your browser and go to `localhost:3000` to view the app.
+---
 
-4. To destroy a Terraform backend sandbox, run:
+### 2. Generate frontend .env file
 
-   ```shell
-   npm run destroy-backend-sandbox <environment-name>
-   ```
+```shell
+npm run create-env-file
+```
 
-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
+---
 
-### Other commands
+### 3 Setup a sandbox environment
 
-- Unit test `npm run test:unit`
-- Accessibility test `npm run test:accessibility`
+#### 3.1 Use someone else's
 
-You can find more commands in the `package.json` file
+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
 
-### Running Team and IAM Web Auth projects locally
+#### 3.2 Or provision your own
 
-Read more in the [README.md](./local/README.md).
+```shell
+npm run create-backend-sandbox -- {YOUR_SHORTCODE_HERE}
+```
 
-### Project structure
+This step will provision infrastructure and deploy any backend services required by the frontend.
 
-- 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`
+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 arg but devs typically use their HSCIC account shortcode so resources belonging to their environment can be easily identified.
 
-### Shared Terraform Modules
+#### 3.3 Seed clients and a user
 
-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:
+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.
 
-```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 sandbox-auth -- {EMAIL} {PASSWORD}
 ```
+
+```shell
+npm run create-amplify-outputs
+```
+
+---
+
+### 4. Start the app
+
+Start the Next.js dev server.
+
+```shell
+npm run dev
+```
+
+Alternatively, use the following command to use an optimised production build of the frontend.
+
+```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` arg 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 sanbodx environment
+- Valid `sandbox_tf_outputs.json` file at the repo 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",