Update readme

Author: ShaynaCummings

README.md

@@ -12,6 +12,26 @@ of children eligible for [Summer EBT](https://www.fns.usda.gov/summer/sunbucks)
 - Changing mailing address on file
 - Requesting a replacement EBT card
 
+## Technology Stack overview
+
+**Backend**
+
+- Language/framework: [C# with .NET 10](https://dotnet.microsoft.com/en-us/languages/csharp)
+- Key libraries: [ASP.NET Core](https://dotnet.microsoft.com/en-us/apps/aspnet), [Serilog](https://serilog.net/), [Managed Extensibility Framework (MEF)](https://learn.microsoft.com/en-us/dotnet/standard/mef/), [EntityFramework (EF) Core](https://learn.microsoft.com/en-us/ef/core/)
+- Package manager: [NuGet](https://www.nuget.org/)
+
+**Frontend**
+
+- Language/framework: [NextJS 16](https://nextjs.org/) with TypeScript
+- Key libraries: next, react, [i18next](https://www.i18next.com/), react-i18next, tanstack/react-query, zod
+- Package manager: [pnpm](https://pnpm.io/)
+- Design system: [USWDS](https://designsystem.digital.gov/), with design tokens specified for each state
+
+**Infrastructure**
+
+- Infrastructure as Code using OpenTofu (Terraform) - see [tofu](./tofu/)
+- Docker with [docker-compose](https://docs.docker.com/compose/) for local development
+
 ## Local Environment Set Up 🧰
 
 > **Note:** The following steps assume you are working on macOS. Steps may differ if you are working on a different operating system.
@@ -25,64 +45,70 @@ of children eligible for [Summer EBT](https://www.fns.usda.gov/summer/sunbucks)
 
 ### 2. Clone repositories
 
-Clone this repository on your local machine, alongside the [state connector repository](https://github.com/codeforamerica/sebt-self-service-portal-state-connector/) and any revelant state backend connector(s) - for example [DC](https://github.com/codeforamerica/sebt-self-service-portal-dc-connector) or [Colorado](https://github.com/codeforamerica/sebt-self-service-portal-co-connector) - as siblings (within the same parent folder)
+Clone this repository on your local machine, alongside the [state connector repository](https://github.com/codeforamerica/sebt-self-service-portal-state-connector/) and any revelant state backend connector(s) - for example, [Colorado](https://github.com/codeforamerica/sebt-self-service-portal-co-connector) - as siblings (within the same parent folder). Note that you will need to build and set up all repos as part of your local env setup.
 
   ```bash
   git clone git@github.com:codeforamerica/sebt-self-service-portal.git
+
   git clone git@github.com:codeforamerica/sebt-self-service-portal-state-connector.git
 
   # Colorado:
   git clone git@github.com:codeforamerica/sebt-self-service-portal-co-connector.git
-
-  # Washington, DC:
-  git clone git@github.com:codeforamerica/sebt-self-service-portal-dc-connector.git
 
   ```
 
-### 3. Create local environment variables
+### 3. Configure local environment
 
-`.env` files are used in this project to set environment variables (eg, database configs). This is a preferred pattern for [12-factor Apps](https://www.12factor.net/config). You'll want to create '.env' files in your local environment, based on the example file.
+`.env` files are used in this project to set environment variables (eg, database configs). This is a preferred pattern for [12-factor Apps](https://www.12factor.net/config). They are also set to fallback to a generic default. You'll need to create `.env` files for your local environment, based on the example file.
 
-From the root of this repository, run:
+To create your local .env file with configurations for the database and API, run this command in the root of the repo:
 
 ```bash
 cp .env.example .env
 ```
 
-You'll also want do the same from within /src/SEBT.Portal.Web:
+You'll want do the same from within `/src/SEBT.Portal.Web`:
 
 ```bash
 cp .env.example .env.local
 ```
 
-###  4. Install dependencies
+You'll also need an API `appsettings` file for your local machine with certain values set (see [state specific configuration](#state-specific-configuration) below):
+
+```bash
+cd src/SEBT.Portal.Api
+cp appsettings.Development.example.json appsettings.Development.json 
+```
+
+### 4. Install dependencies
+
+Front end
+
+- To install all javascript package dependencies, run `pnpm install` from the root of this repository.
+- You can learn more about the front end in the [SEBT.Portal.Web README](./src/SEBT.Portal.Web/README.md)
+
+Back end
 
-- To install all javascript package dependencies, run `pnpm install` from the root of this repository
-- dotnet tool install --global dotnet-ef
 - .NET tools are CLI utilities installed and managed using [NuGet](https://www.nuget.org/). Currently, we are using the
-  [`nuget-license`](https://www.nuget.org/packages/nuget-license) tool for auditing backend dependency license.  Needed tools are defined in the tools 
-manifest in `.config/dotnet-tools.json`. To install .NET tools, run `dotnet tool restore` from each solution root (ie, each top-level directory containing a `.sln` or `.slnx` file):
+  [`nuget-license`](https://www.nuget.org/packages/nuget-license) tool for auditing backend dependency license.  Needed tools are defined in the tools manifest in `.config/dotnet-tools.json`. To install .NET tools, run `dotnet tool restore` from each solution root (ie, each top-level directory containing a `.sln` or `.slnx` file):
   - /src/SEBT.Portal.Infrastructure
   - /src/SEBT.Portal.Api
 
-- The first time you start up the application, you'll also want to run `dotnet build` from within the root of each repository
+- You'll also want to run `dotnet build` from within the root of each repository before starting up the app for the first time.
 
 ### 5. Start Services 💻
 
-Make sure the docker daemon is running and you are logged in via your dockerhub account.
+Make sure Docker is installed and the docker daemon is running. When the database spins up locally, all migrations will be run and db seeded automatically (see [database setup](#database-setup) section below).
 
 ```bash
-docker compose up -d # Start MSSQL Database and Mailpit
+docker compose up -d  # Start all docker containers, including MSSQL Database and Mailpit for testing
 ```
 
-
 ```bash
-pnpm dev              # Start both API and frontend
+pnpm dev              # Script to start both API (ie, `dotnet watch`) and frontend (ie, `next dev`)
 ```
 
-
-To open the app, navigate to https://localhost:3000
-
+To open the app, navigate to <https://localhost:3000>
 
 ## Development
 
@@ -104,7 +130,7 @@ docker compose down -v
 
 ### Mailpit (Local Email Testing)
 
-Mailpit captures all outgoing emails in development. Access the web UI at http://localhost:8025
+[Mailpit](https://mailpit.axllent.org/) captures all outgoing emails in local development. Once the Mailpit docker container is running on your machine, you can access its UI in your browser at <http://localhost:8025>
 
 ### Local Build & Test (Debug mode)
 
@@ -182,11 +208,27 @@ Only include sections you want to override; other settings fall back to `appsett
 
 ### OIDC support
 
-States can use an external OpenID Connect (OIDC) provider for sign-in. Code exchange and id_token validation run in the Next.js server; the .NET API performs "complete-login" (validates a short-lived callback token and returns a portal JWT that includes IdP claims such as phone and name).
+States can use an external [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works/) provider for sign-in. Code exchange and id_token validation run in the Next.js server; the .NET API performs "complete-login" (validates a short-lived callback token and returns a portal JWT that includes IdP claims such as phone and name).
+
+For a deployment that uses OIDC, in `.env.local` under `SEBT.Portal.Web`, set:
 
-For a deployment that uses OIDC, set in **Next.js** `.env.local`: `OIDC_DISCOVERY_ENDPOINT`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_REDIRECT_URI`, `OIDC_COMPLETE_LOGIN_SIGNING_KEY` (at least 32 characters). Set the **same** value for `OIDC_COMPLETE_LOGIN_SIGNING_KEY` in the API as `Oidc:CompleteLoginSigningKey`. In the API, set `Oidc:DiscoveryEndpoint`, `Oidc:ClientId`, `Oidc:CallbackRedirectUri`, and optionally `Oidc:LanguageParam`. The API serves public config via `GET /api/auth/oidc/{stateCode}/config`.
+- `OIDC_DISCOVERY_ENDPOINT`
+- `OIDC_CLIENT_ID`
+- `OIDC_CLIENT_SECRET`
+- `OIDC_REDIRECT_URI`
+- `OIDC_COMPLETE_LOGIN_SIGNING_KEY` (at least 32 characters)
 
-See `src/SEBT.Portal.Api/appsettings.Development.example.json` and [ADR-0008](docs/adr/0008-oidc-mycolorado-authentication-and-state-auth-context.md) for the design.
+In `appsettings` under `SEBT.Portal.Api`, set:
+
+- `Oidc:CompleteLoginSigningKey` (same value as `OIDC_COMPLETE_LOGIN_SIGNING_KEY`)
+- `Oidc:DiscoveryEndpoint`
+- `Oidc:ClientId`
+- `Oidc:CallbackRedirectUri`
+- `Oidc:LanguageParam` (optional)
+
+The API serves public config via `GET /api/auth/oidc/{stateCode}/config`.
+
+See `appsettings.Development.example.json` and [ADR-0008](docs/adr/0008-oidc-mycolorado-authentication-and-state-auth-context.md).
 
 ### ID Proofing Requirements
 
@@ -212,14 +254,9 @@ The application uses Microsoft SQL Server as its database.  This is propped up v
 
 #### Configuration
 
-Database configuration is managed through environment variables. Copy `.env.example` to `.env` and customize as needed (this is a preferred pattern for [12-factor Apps](https://www.12factor.net/config)).  They are also set to fallback to a generic default. 
-
-```bash
-cp .env.example .env
-```
-
-Available environment variables:
+Configuration is managed through environment variables.
 
+Available environment variables for `.env` in the respository root:
 **Database (for Docker Compose):**
 
 - `MSSQL_SA_PASSWORD` - SQL Server SA password
@@ -233,20 +270,17 @@ Available environment variables:
 - `JWTSETTINGS__SECRETKEY` - Secret key for JWT token signing. Must be at least 32 characters.
 - `IDENTIFIERHASHER__SECRETKEY` - Secret key for HMAC-SHA256 hashing of Household Identifiers as needed. Must be at least 32 characters.
 
-**OIDC (state IdP sign-in)**  
-Set `OIDC_DISCOVERY_ENDPOINT`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_REDIRECT_URI`, and `OIDC_COMPLETE_LOGIN_SIGNING_KEY` in Next.js `.env.local`. In the API, set `Oidc:CompleteLoginSigningKey` (same value), `Oidc:DiscoveryEndpoint`, `Oidc:ClientId`, and `Oidc:CallbackRedirectUri`. See `appsettings.Development.example.json` and [ADR-0008](docs/adr/0008-oidc-mycolorado-authentication-and-state-auth-context.md).
-
 ### Database Migrations
 
-The application uses [Entity Framework Core migrations](https://learn.microsoft.com/en-us/ef/core/managing-schemas/migrations/?tabs=dotnet-core-cli) to manage database schema changes.
+The application uses [EF, or Entity Framework Core migrations](https://learn.microsoft.com/en-us/ef/core/managing-schemas/migrations/?tabs=dotnet-core-cli) to manage database schema changes.
 
 #### Automatic Migrations
 
 **Migrations run automatically on application startup.** When the API starts, it checks for pending migrations and applies them automatically. This ensures the database schema is always up-to-date.
 
 #### Manual Migration Commands
 
-While migrations run automatically, you can also manage them manually:
+While migrations run automatically, you can also manage them manually by installing `ef` on your local machine:
 
 **List all migrations:**
 
@@ -298,7 +332,7 @@ The database is automatically seeded with test users when running in the **Devel
 - Application startup (when migrations are applied)
 - `DbContext.EnsureCreated()` calls
 
-The automatic seeding uses EF Core's `UseSeeding` mechanism under the hood.  See https://learn.microsoft.com/en-us/ef/core/modeling/data-seeding
+The automatic seeding uses EF Core's `UseSeeding` mechanism under the hood.  See <https://learn.microsoft.com/en-us/ef/core/modeling/data-seeding>
 
 To help test different workflows and users in different states, the seeder will create the following users unless instructed otherwise:
 
@@ -334,6 +368,11 @@ Alternatively, I'd highly recommend a tool like [LINQPad](https://www.linqpad.ne
 
 More documentation can be found in the [docs](./docs) folder.
 
+See also:
+
+- [README for SEBT.Portal.Web (front end)](./src/SEBT.Portal.Web/README.md)
+- [README for Figma design token scripts](./src/SEBT.Portal.Web/design/scripts/README.md)
+
 We use [Lightweight Architecture Decision Records](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
 for tracking architectural decisions, using [adr tools](https://github.com/npryce/adr-tools) to
 store them in source control. These can be found in the [docs/adr](./docs/adr) folder.