Skip to content

Commit 1f552f9

Browse files
committed
docs: update README.md with tool use disclaimer
1 parent 7395841 commit 1f552f9

File tree

1 file changed

+52
-39
lines changed

1 file changed

+52
-39
lines changed

README.md

Lines changed: 52 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -16,22 +16,22 @@ Everything is written in **TypeScript** and runs on **Node.js**.
1616
The frontend is **React** via **Next.js** and deployed in **Docker containers** on an **AWS Elastic
1717
Container Service** cluster.
1818

19-
The backend is an **Express** app deployed as an **AWS Lambda** function using **AWS Cloud Development Kit**. It connects to an **AWS DynamoDB** instance that is also configured through
19+
The backend is an **Express** app deployed as an **AWS Lambda** function using **AWS Cloud
20+
Development Kit**. It connects to an **AWS DynamoDB** instance that is also configured through
2021
**Terraform**.
2122

2223
The app uses **AWS Cognito** (through **AWS Amplify**) to handle authentication for registered
2324
users. Unregistered users are able to browse the site in guest mode without saving their data to the
2425
DynamoDB database.
2526

26-
We deploy using
27-
**[GitHub Actions ](https://github.com/newjersey/navigator.business.nj.gov/actions)** for
28-
CI/CD.
27+
We deploy using **[GitHub Actions](https://github.com/newjersey/navigator.business.nj.gov/actions)**
28+
for CI/CD.
2929

3030
## Development
3131

3232
You will need Node.js (with Yarn installed via `npm` or `corepack`) installed for primary
33-
development. Additionally, for running the server in local development mode, you will need
34-
Python (for the AWS CLI and some of our scripts) installed (details below).
33+
development. Additionally, for running the server in local development mode, you will need Python
34+
(for the AWS CLI and some of our scripts) installed (details below).
3535

3636
We recommend using WSL2 if developing on Windows.
3737

@@ -43,9 +43,11 @@ For pair programming, we recommend Visual Studio Code with the Live Share extens
4343
[nvm](https://github.com/nvm-sh/nvm#readme) for managing Node.js versions. If installing via
4444
package manager, we suggest installing `corepack` if available separately.)
4545
- [Docker](https://www.docker.com/) — required for running containers locally
46-
- **macOS:** We recommend using [Colima](https://github.com/abiosoft/colima) as your Docker runtime
46+
- **macOS:** We recommend using [Colima](https://github.com/abiosoft/colima) as your Docker
47+
runtime
4748
- **Recommended Colima Configuration:** aarch64, cpu: 8, memory: 16, disk: 256, runtime: docker
48-
- You can manually configure Colima with `colima start --edit` or the script `install.sh` will configure automatically.
49+
- You can manually configure Colima with `colima start --edit` or the script `install.sh` will
50+
configure automatically.
4951
- **Windows (WSL2):** Use Docker Desktop with WSL2 integration enabled
5052
- **Linux:** Use the native Docker Engine installation
5153
- [AWS CLI](https://aws.amazon.com/cli/)
@@ -67,8 +69,8 @@ You will then setup your AWS credentials:
6769
aws configure
6870
```
6971

70-
Clone the code and navigate to the root of this repository. There is an installation script that will
71-
install all required development tools, yarn packages, and execute a yarn build.
72+
Clone the code and navigate to the root of this repository. There is an installation script that
73+
will install all required development tools, yarn packages, and execute a yarn build.
7274

7375
```shell
7476
./scripts/install.sh
@@ -81,13 +83,17 @@ Before you can run locally, you will need to:
8183
- create a `./web/.env` that includes all the values laid out in the `./web/.env-template` file.
8284
- create a `./api/.env` that includes all the values laid out in the `./api/.env-template` file.
8385
- create a `.venv` virtual environment and install requirements if working on Python
84-
- _Note: The application does not need a venv. This step is only required to run Python helper scripts._
86+
- _Note: The application does not need a venv. This step is only required to run Python helper
87+
scripts._
88+
8589
```shell
8690
python3 -m venv .venv
8791
source .venv/bin/activate
8892
pip install -r requirements.txt
8993
```
94+
9095
- do an initial build (skip if you ran `install.sh`)
96+
9197
```shell
9298
yarn build
9399
```
@@ -142,33 +148,38 @@ yarn test:python
142148

143149
### Running locally
144150

145-
Before starting the app, make sure your Docker environment is running. This is required for DynamoDB Local.
151+
Before starting the app, make sure your Docker environment is running. This is required for DynamoDB
152+
Local.
146153

147-
_Note:_ If you ran the `install.sh` script, you should have Colima installed and running on your machine already. The script also sets Colima as a service for Homebrew to start on machine login.
154+
_Note:_ If you ran the `install.sh` script, you should have Colima installed and running on your
155+
machine already. The script also sets Colima as a service for Homebrew to start on machine login.
148156

149157
#### First-Time Setup
150158

151-
You will need to have all dependencies installed. If you haven't done so, you can install all required technologies by running `./scripts/install.sh` from the root directory.
159+
You will need to have all dependencies installed. If you haven't done so, you can install all
160+
required technologies by running `./scripts/install.sh` from the root directory.
152161

153162
1. Build the application
154163

155-
```shell
156-
yarn build # This happens in the install.sh script as well.
157-
```
164+
```shell
165+
yarn build # This happens in the install.sh script as well.
166+
```
158167

159168
2. Launch all the services
160169

161-
```shell
162-
yarn start:dev
163-
```
170+
```shell
171+
yarn start:dev
172+
```
164173

165-
3. Open the application in your browser. The frontend is available at [localhost:3000](http://localhost:3000)
174+
3. Open the application in your browser. The frontend is available at
175+
[localhost:3000](http://localhost:3000)
166176

167-
4. Terminate the application with `Ctrl+C`. A cleanup script will tear down the Docker processes. If you need to stop the Docker containers manually, run:
177+
4. Terminate the application with `Ctrl+C`. A cleanup script will tear down the Docker processes. If
178+
you need to stop the Docker containers manually, run:
168179

169-
```shell
170-
yarn services:down
171-
```
180+
```shell
181+
yarn services:down
182+
```
172183

173184
### Deploying
174185

@@ -178,8 +189,8 @@ Use `ship-it` to run prettier, linting, and tests before pushing:
178189
./scripts/ship-it.sh
179190
```
180191

181-
The GitHub CI/CD (which is configured in `.github/workflows`) will pick up the job and deploy
182-
to the development environment for commits to the main branch.
192+
The GitHub CI/CD (which is configured in `.github/workflows`) will pick up the job and deploy to the
193+
development environment for commits to the main branch.
183194

184195
## Frontend deep-dive
185196

@@ -201,8 +212,8 @@ line in `_app.tsx`).
201212
For Next.js, environment variables are inserted at build time. In `./web/next.config.js`, the
202213
environment variables that the code will have access to are set up for the Next.js framework by
203214
pulling them in from the `.env` file. This works because the system that is building the Next.js
204-
code (via GitHub Actions workflow) has access to these variables via environment variables set during that
205-
build step.
215+
code (via GitHub Actions workflow) has access to these variables via environment variables set
216+
during that build step.
206217

207218
**Important**: This means that any time you build the app, the system building it (your local
208219
terminal, for example) needs to have these environment variables set as well, or else they will not
@@ -253,14 +264,15 @@ make use of the `useUserData` wrapper around this hook.
253264

254265
## Backend deep-dive
255266

256-
The backend code lives in `./api`. It uses [AWS Cloud Development Kit (CDK)](https://docs.aws.amazon.com/cdk/v2/guide/home.html) for
257-
handling the integration with AWS Lambdas.
267+
The backend code lives in `./api`. It uses
268+
[AWS Cloud Development Kit (CDK)](https://docs.aws.amazon.com/cdk/v2/guide/home.html) for handling
269+
the integration with AWS Lambdas.
258270

259-
We use CDK to deploy the backend app. The backend app itself is defined in `api/src/functions/express/app.ts` and is mostly a regular Express app,
260-
except it wraps its export in `serverless-http` to become a handler. Locally, the Express app runs normally.
261-
API gateway routing is configured using AWS CDK in the `api/cdk/lib/apiStack.ts` file, which
262-
defines the config structure that proxies all routes through to be handled by the Express routing
263-
system.
271+
We use CDK to deploy the backend app. The backend app itself is defined in
272+
`api/src/functions/express/app.ts` and is mostly a regular Express app, except it wraps its export
273+
in `serverless-http` to become a handler. Locally, the Express app runs normally. API gateway
274+
routing is configured using AWS CDK in the `api/cdk/lib/apiStack.ts` file, which defines the config
275+
structure that proxies all routes through to be handled by the Express routing system.
264276

265277
The rest of the code is regular hexagonal Express structure. The `src/api` folder contains route
266278
definitions and depends on abstractions and types defined in `src/domain`. The `src/db` folder
@@ -354,10 +366,11 @@ Business.NJ.gov is an open source project that is meant to serve as a base for a
354366
to create an online resource for their own business community. You can find full license details at
355367
[Business.NJ.gov/license](https://business.nj.gov/license).
356368

357-
### Launch a copy of the website
369+
#### Disclaimer
358370

359-
We manage the website through Webflow. To launch your own copy of the site, visit the Webflow
360-
showcase and click "Open in Webflow": https://webflow.com/website/State-of-NJ-Business-One-Stop
371+
This project utilizes certain tools and technologies for development purposes. The inclusion of
372+
these tools does not imply endorsement or recommendation. Users are encouraged to evaluate the
373+
suitability of these tools for their own use.
361374

362375
### Repositories and code
363376

0 commit comments

Comments
 (0)