# Blueprint Workspace

This repository is a Yarn workspace blueprint with a NestJS backend, Angular frontend, and a small local package blueprint.

## Architecture

- `apps/backend`: NestJS backend using Prisma and GraphQL code-first.
- `apps/frontend`: Angular frontend using Apollo Angular and GraphQL Code Generator.
- `packages/hello-world`: local workspace package blueprint.
- `experiments/trpc`: archived tRPC experiment. It is not active app wiring.

The backend exposes REST smoke-test endpoints and a minimal GraphQL health query. The frontend uses the generated Angular Apollo `HealthGQL` service as a smoke test.

## Setup

Install dependencies from the repo root:

```sh
yarn install
```

Create backend environment configuration with at least:

```sh
cp apps/backend/.env.example apps/backend/.env
```

Then edit `apps/backend/.env` if your database URL or JWT settings differ:

```sh
DATABASE_URL=postgres://postgres:postgres@db:5432/app
TEST_DATABASE_URL=postgres://postgres:postgres@db:5432/app_test
JWT_SECRET=replace-with-at-least-32-characters
JWT_EXPIRES_IN=7d
```

`JWT_SECRET` must be at least 32 characters. `JWT_EXPIRES_IN` is configurable
and defaults to `7d` when omitted. Backend startup intentionally fails fast
when required environment values are missing or invalid.

`DATABASE_URL` uses the docker-compose service host `db:5432` inside the
devcontainer. Host-side tools should connect to `localhost:35432`. Backend e2e
tests are destructive and require a test-scoped database such as `app_test`;
without `TEST_DATABASE_URL`, the e2e suite safe-skips with an explicit warning.

Check backend env parity without printing secrets:

```sh
yarn env:check
```

Run the backend:

```sh
yarn dev:backend
```

Run the frontend:

```sh
yarn dev:frontend
```

Generate frontend GraphQL types and Apollo services:

```sh
yarn codegen
```

Build the backend:

```sh
yarn build:backend
```

Build the frontend:

```sh
yarn build:frontend
```

Run a real local runtime smoke check:

```sh
yarn smoke:runtime
```

The runtime smoke command starts the backend and frontend dev servers, verifies REST health, frontend HTTP, GraphQL users, create-user, login, and current-user with JWT, then deletes the smoke user it created. It requires the same `apps/backend/.env` values as the backend dev server and expects ports `3720` and `4220` to be free.

## GraphQL Schema And Codegen

The backend is configured with NestJS GraphQL code-first. `apps/backend/src/schema.gql` is generated by backend app startup/tests from the resolver/type decorators.

The root `codegen.yml` uses:

- Schema: `apps/backend/src/schema.gql`
- Documents: `apps/frontend/src/app/core/graphql/operations/**/*.graphql`
- Output: `apps/frontend/src/app/core/graphql/generated/graphql.ts`

When backend GraphQL types or frontend operations change, initialize the backend app so `schema.gql` is current, then run `yarn codegen`.

## Auth Smoke Users

The auth foundation keeps local email/password login intentionally minimal. Passwords are hashed before storage, JWT payloads contain only user id, email, and role, and the frontend stores the access token in local storage for scaffold/dev smoke testing only. Production hardening still needs refresh-token strategy, token revocation, secure cookie/session decisions, rate limiting, real registration/account flows, and forgot-password/account recovery.

## Frontend PWA Metadata

The Angular frontend includes a minimal web app manifest and replaceable
Blueprint placeholder icons under `apps/frontend/public`. This lets supported
mobile browsers add the app to the home screen while preserving normal browser
usage.

Service worker caching is intentionally not enabled yet. The current local/dev
workflow depends on frequent rebuilds and Dev Console updates, so manifest-only
PWA metadata avoids stale UI during development. Replace the placeholder icons
by updating `apps/frontend/public/icons/blueprint-icon.svg` and regenerating
the PNG sizes referenced by `apps/frontend/public/manifest.webmanifest`.

The frontend `Create smoke user` action creates a `smoke-` user with the displayed development-only smoke password and pre-fills the login panel so the create-user, login, current-user, and logout flow can be tested manually.

Backend e2e users use the `e2e-` email prefix, and frontend smoke users use the `smoke-` prefix. To remove those development records:

```sh
yarn cleanup:smoke-users
```

The cleanup command only targets users whose email starts with `e2e-`, `smoke-`, or `smoke-manual-`. Tests and AI manual smoke checks should use unique emails with one of those prefixes and should not delete non-prefixed users.

## Chunk-Based AI Workflow

AI-assisted migration work should be done in explicit chunks. Each chunk should stay inside its stated scope and avoid unrelated cleanup. Application source, dependencies, backend schema, frontend UI, Prisma models, and archived experiments should only change when the chunk explicitly asks for those changes.

For each chunk, run the requested verification commands and summarize the result with `git status` and `git diff --stat`.