OverviewDeveloper GuideAPI Reference

Getting Started

This guide walks you through setting up your local development environment and covers the most common developer workflows.

Prerequisites

  • Node.js 22+ (download)
  • pnpm package manager (npm i -g pnpm)
  • AWS CLI configured with access to the development account (856284715153)
  • AWS Profile set in .env via the AWS_PROFILE variable (typically srdev)

Initial Setup

  1. Clone the repository:

    git clone git@github.com:trilogy-group/wseng-monorepo-starter.git
cd wseng-monorepo-starter

  2. Install dependencies (from root):

    pnpm install

  3. Populate your .env from a deployed environment:

    # Sync from the integration environment
pnpm script update-env --env integration

# Or sync from a specific PR environment
pnpm script update-env --pr 20

    This reads CloudFormation stack outputs + Secrets Manager values and writes them into the root .env file. All workspaces (backend, frontend, infra) share this single .env.

Local Development — Full Stack

To run both frontend and backend locally:

Step 1: Configure .env for localhost

After running update-env, override these two variables in your .env:

ENVIRONMENT=localhost
API_BASE_URL=http://localhost:3001

Step 2: Start the backend 

cd backend/
pnpm run dev          # Starts on http://localhost:3001
# or
pnpm run dev:watch    # Starts with auto-reload on file changes

The backend dev server serves all API routes on port 3001, including Scalar docs at /docs/viewer and OpenAPI spec at /docs/openapi.json. It resolves AWS credentials from your AWS_PROFILE.

Step 3: Start the frontend 

cd frontend/
pnpm run dev          # Starts on http://localhost:3000

Step 4: Open the app

Navigate to: http://localhost:3000?setEnv=localhost

The ?setEnv=localhost query parameter tells the frontend to use http://localhost:3001 as the API backend. This setting is persisted in browser storage, so you only need the query parameter once.

Hot-Connecting to Remote Backends

You can run the frontend locally (pnpm run dev in frontend/) and point it at any deployed backend using the ?setEnv query parameter. No backend changes needed.

http://localhost:3000?setEnv=integration    # Points to integration backend
http://localhost:3000?setEnv=production     # Points to production backend
http://localhost:3000?setEnv=pr0020         # Points to a specific PR environment
http://localhost:3000?setEnv=localhost       # Switch back to local

The setting is persisted in browser storage. To switch, just navigate with a different ?setEnv value — the page reloads with the new config.

API Client Generation

The monorepo uses OpenAPI Generator (typescript-fetch) to produce a fully typed API client in shared/ts/api/generated/. This client is consumed by both the frontend (via @ws-mono/shared/api) and the API tests.

How to Regenerate

The generator fetches the OpenAPI spec from a running backend, so you need a backend available:

Option A: Regenerate from Local Backend (Recommended during development) 

# 1. Start your local backend (in a separate terminal)
cd backend/
pnpm run dev

# 2. From the repo root, regenerate the client
pnpm generate:api-client --local

The --local flag tells the generator to fetch the spec from http://localhost:3001/docs/openapi.json.

Option B: Regenerate from a Deployed Environment 

# Regenerate from integration environment
pnpm generate:api-client --url https://api-monorepo-integration.wseng.rp.devfactory.com/docs/openapi.json

# Or it uses API_BASE_URL from your .env by default
pnpm generate:api-client

Additional Flags 

pnpm generate:api-client --force       # Regenerate even if the spec hasn't changed
pnpm generate:api-client --keep-spec   # Keep the downloaded OpenAPI spec file for inspection
pnpm generate:api-client --skip-lint   # Skip post-generation linting (faster, useful in CI)

Typical Workflow: Add a Backend Endpoint and Use it in Frontend

  1. Add the route in the backend (e.g., backend/app/my-module/routers/my-module.router.ts)
  2. Start the local backend: cd backend && pnpm run dev
  3. Regenerate the client: pnpm generate:api-client --local (from root)
  4. Verify: Check shared/ts/api/generated/apis/ for the new API class
  5. Update the wrapper (if needed): Add the new API class to shared/ts/api/api-client.ts
  6. Use in frontend: Import via getApiClientService().getClient().myModule.myEndpoint()
  7. Commit both the backend changes and the regenerated client files

API Tests

The api-tests/ package contains auto-generated integration tests that run against a deployed backend. Tests validate that each endpoint returns successful responses with the expected schema.

Generated tests live in api-tests/generated/ (overwritten on regeneration). Put custom tests in api-tests/shared/ (committed) or api-tests/private/ (gitignored).

Prerequisites

Before running API tests, ensure:

  1. Your .env has API_BASE_URL pointing to the target backend
  2. Your .env has API_USERNAME and API_PASSWORD set (Cognito test user credentials)
  3. Your .env has USER_POOL_CLIENT_ID set

Running Tests 

cd api-tests/

# Run all tests
pnpm run test

# Run only generated tests
pnpm run test:generated

# Run only shared (hand-written) tests
pnpm run test:shared

Tests run sequentially (no concurrency) with a 30-second timeout. Authentication is handled automatically — the test setup fetches and caches a Cognito token before all tests.

Regenerating Tests

When backend endpoints change, regenerate both the API client and the test files:

# From the repo root — regenerates client first, then test files
pnpm generate:api-tests

This regenerates the API client first, then generates .test.ts and .fixture.ts files for each operation.

Testing Against Different Environments 

# Test against integration
pnpm script update-env --env integration
cd api-tests && pnpm run test

# Test against a PR environment
pnpm script update-env --pr 20
cd api-tests && pnpm run test

# Test against local backend
# (update .env: API_BASE_URL=http://localhost:3001)
cd api-tests && pnpm run test

Quality Checks

From the repo root:

pnpm run check   # Lint + type-check across all workspaces
pnpm run fix     # Auto-fix lint and formatting issues

From the backend directory:

cd backend/
pnpm run test         # Run unit tests once
pnpm run test:watch   # Run unit tests in watch mode

Troubleshooting

Login button doesn't work

  1. Open browser console — look for 🔧 Localhost configuration: log
  2. Verify USER_POOL_ID, USER_POOL_CLIENT_ID, USER_POOL_DOMAIN are set in .env
  3. Restart the Vite dev server after .env changes
  4. Navigate to http://localhost:3000?setEnv=localhost to force-reset

AWS credential errors

The backend dev server resolves credentials from AWS_PROFILE on startup and refreshes every 45 minutes. If your SAML session expires:

  1. Re-authenticate with saml2aws login
  2. Restart the backend dev server

Environment not found

If update-env fails, ensure:

  • The CloudFormation stack for the target environment exists
  • Your AWS profile has access to the correct account (856284715153)
  • Use --wait flag if the stack is still deploying: pnpm script update-env --env integration --wait