Show a user's avatar on the public profile (#333)

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> for assistance with diagram creation and documentation prose updates.

.claude/skills/doc-drift-pipeline/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: doc-drift-pipeline
+description: Checks whether recent changes under tooling/pipeline/ have made docs/pipeline/ stale. Use when the user asks to check for doc drift on the pipeline, before committing changes to tooling/pipeline, or when asked "does this need a doc update" for the C++ seed-data pipeline.
+---
+
+# Doc Drift Check — Pipeline
+
+Given a diff scoped to `tooling/pipeline/` (uncommitted changes, a range of
+commits, or a specific PR), determine whether it invalidates any factual
+claim in `docs/pipeline/`.
+
+## Steps
+
+1. Run `git diff -- tooling/pipeline/` (or
+   `git diff <base>...<head> -- tooling/pipeline/` if a range is given) to
+   see what changed. If the diff also touches `web/**`, note that it's out of
+   scope here — use the `doc-drift-web` skill for that half.
+2. Based on which files changed, identify the relevant doc(s):
+   - `tooling/pipeline/src/**`, `includes/**` (implemented behavior) →
+     `docs/pipeline/README.md`, `docs/pipeline/diagrams/current/*.mmd`
+     (activity, class)
+   - Work that's scaffolded/flagged but not wired into the default run path
+     (roadmap-only) → `docs/pipeline/ROADMAP.md`,
+     `docs/pipeline/diagrams/planned/*.mmd` — do not touch `current/` for
+     planned work that hasn't landed
+   - Changes to pipeline bias/hallucination handling, model prompts, sampling
+     logic, or known-limitation workarounds →
+     `docs/pipeline/ETHICS-AND-KNOWN-ISSUES.md`
+   - `tooling/pipeline/runpod/Dockerfile`, build/run scripts →
+     `docs/pipeline/README.md` (setup/usage sections)
+   - `docs/pipeline/french-cities.example` — check it still matches the input
+     schema the pipeline actually reads
+   - A new file added under `docs/pipeline/**` → also check `docs/index.md`
+     and `mkdocs.yml` nav are updated to reference it
+3. Read the relevant doc section(s) and check each specific factual claim
+   (tables, "currently X", "not yet implemented", roadmap checkboxes) against
+   the diff. For diagrams, this means reading the `.mmd` source (not just the
+   wrapping `.md`) and checking nodes/edges/labels against the diff — a
+   pipeline stage or control-flow change can invalidate a diagram without
+   touching any prose.
+4. When a diff adds real behavior that was previously only in
+   `diagrams/planned/`, check whether that planned diagram/roadmap entry
+   should now move to `current/`/README rather than just adding a duplicate
+   claim in both places.
+5. Report only what's actually stale — do not rewrite unrelated prose, do not
+   invent claims not grounded in the diff.
+6. If nothing is affected, say so plainly and make no edits.
+7. For confirmed drift, propose the exact edit (old text → new text, or the
+   changed `.mmd` node/edge) rather than committing directly, unless
+   explicitly told to apply it. Flag `.mmd` changes separately since they may
+   need a re-render (`docs/rendered-diagrams/pipeline/**`) via
+   `docs/makefile`.

.claude/skills/doc-drift-web/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: doc-drift-web
+description: Checks whether recent changes under web/ have made docs/web/ stale. Use when the user asks to check for doc drift on the web app, before committing changes to web/backend or web/frontend, or when asked "does this need a doc update" for web/API/frontend work.
+---
+
+# Doc Drift Check — Web
+
+Given a diff scoped to `web/` (uncommitted changes, a range of commits, or a
+specific PR), determine whether it invalidates any factual claim in
+`docs/web/`.
+
+## Steps
+
+1. Run `git diff -- web/` (or `git diff <base>...<head> -- web/` if a range is
+   given) to see what changed. If the diff also touches `tooling/pipeline/**`,
+   note that it's out of scope here — use the `doc-drift-pipeline` skill for
+   that half.
+2. Based on which files changed, identify the relevant doc(s):
+   - `web/backend/API/**`, `Features.*/**` (general) → `docs/web/architecture.md`
+   - `web/backend/Features/Features.Users/**/Authentication/**`,
+     identity/token code (`ITokenService`, `RefreshToken*`, `ConfirmEmail*`,
+     login/registration handlers) → `docs/web/token-validation.md`,
+     `docs/web/diagrams/auth/*.mmd` (pick the matching flow: login,
+     registration, refresh-token, confirm-user, delete-account,
+     update-email/password/profile/username, resend-confirmation,
+     error-handling)
+   - `web/backend/Database/**` (entities, `Database.Migrations/scripts/**`) →
+     `docs/web/database.md`, `docs/web/diagrams/database-schema/*.mmd` (pick
+     the matching schema: beer, brewery, identity, location, media)
+   - Host wiring / DI registration (`API/**Program.cs`,
+     `Database.Seed/**Program.cs`) → `docs/web/diagrams/vertical-slice/host-wiring.mmd`
+   - New project references between `Features.*`/`Shared.*`/`Domain.*`
+     projects (new `.csproj` `<ProjectReference>`) →
+     `docs/web/diagrams/vertical-slice/project-references.mmd`
+   - `web/backend/Dockerfile*`, `web/frontend/Dockerfile*`, compose/deploy
+     config → `docs/web/docker.md`, `docs/web/diagrams/deployment/*.mmd`
+     (dev, test, minimal, db-only, prod), `docs/web/diagrams/deployment.md`
+   - `web/.env.example`, `web/.env.test`, appsettings → `docs/web/environment-variables.md`
+   - `web/backend/API/API.Specs/**`, test infra/fixtures → `docs/web/testing.md`
+   - New backend project setup, dev tooling → `docs/web/getting-started.md`
+   - `web/frontend/**` → `docs/web/architecture.md` (Frontend architecture section)
+   - A new file added under `docs/web/**` → also check `docs/index.md` and
+     `mkdocs.yml` nav are updated to reference it
+3. Read the relevant doc section(s) and check each specific factual claim
+   (tables, "currently X", "not yet implemented", roadmap checkboxes) against
+   the diff. For diagrams, this means reading the `.mmd` source (not just the
+   wrapping `.md`) and checking nodes/edges/labels against the diff — a
+   schema or flow change can invalidate a diagram without touching any prose.
+4. Report only what's actually stale — do not rewrite unrelated prose, do not
+   invent claims not grounded in the diff.
+5. If nothing is affected, say so plainly and make no edits.
+6. For confirmed drift, propose the exact edit (old text → new text, or the
+   changed `.mmd` node/edge) rather than committing directly, unless
+   explicitly told to apply it. Flag `.mmd` changes separately since they may
+   need a re-render (`docs/rendered-diagrams/web/**`) via `docs/makefile`.

.config/dotnet-tools.json

@@ -1,13 +0,0 @@
-{
-  "version": 1,
-  "isRoot": true,
-  "tools": {
-    "csharpier": {
-      "version": "1.2.1",
-      "commands": [
-        "csharpier"
-      ],
-      "rollForward": false
-    }
-  }
-}

.gitattributes

@@ -0,0 +1 @@
+archive/** linguist-vendored

.github/ISSUE_TEMPLATE/feature_request.md

@@ -7,6 +7,7 @@ assignees: []
 ---
 
 ## User Story
+
 **As a** (who wants to accomplish something)  
 **I want to** (what they want to accomplish)  
 **So that** (why they want to accomplish that thing)
@@ -15,29 +16,18 @@ assignees: []
 
 ### Scenario 1
 
-
-Given ...
-When ...
-Then ...
-
+Given ... When ... Then ...
 
 ### Scenario 2
 
-
-Given ...
-When ...
-Then ...
-
+Given ... When ... Then ...
 
 ### Scenario 3
 
-
-Given ...
-When ...
-Then ...
-
+Given ... When ... Then ...
 
 ## Subtasks
+
 - [ ] Task 1
 - [ ] Task 2
-- [ ] Task 3
+- [ ] Task 3

.github/pull_request_template.md

@@ -0,0 +1,101 @@
+## Summary
+
+<!--
+State WHAT is changing and WHY, in two to five sentences.
+A reader should understand the change without opening the diff.
+Describe the problem first, then the outcome.
+-->
+
+## Type of change
+
+<!-- Tick the one option that best describes this PR. -->
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor (no change in behaviour)
+- [ ] Performance improvement
+- [ ] Documentation
+- [ ] Tests only
+- [ ] Build, CI or dependency update
+- [ ] Other (please specify):
+
+## Related issues
+
+<!--
+Link the issue(s) this PR relates to. Use one keyword per issue so that each is closed on merge:
+
+  Fixes #123
+  Fixes #124, fixes #125
+  Fixes owner/other-repo#456
+
+Closing keywords only take effect when the PR targets the repository's default branch.
+Use "Related to #123" if the PR should not close the issue.
+If there is no issue, write "N/A" and explain the motivation in the Summary.
+-->
+
+## Approach and context
+
+<!--
+Explain how the change works and why this approach was chosen.
+Include, where relevant:
+  - The decisions you made that are not obvious from the code.
+  - Alternatives you considered and why you rejected them.
+  - Known limitations or shortcomings, and any planned follow-up work.
+  - Background such as benchmark results or design documents.
+
+Summarise the key points of any external link. Links may be inaccessible to future readers.
+-->
+
+## How this was tested
+
+<!--
+Describe what you ran and what you observed. Be specific, and state only what you actually did.
+For example: the automated tests added or changed, manual steps and their outcome,
+environments or platforms covered, and anything you were unable to test.
+For a bug fix, note the test that fails without the fix.
+-->
+
+## Compatibility and risk
+
+- [ ] This change is backwards compatible.
+- [ ] This change is **breaking** (complete the details below).
+- [ ] This change deprecates existing behaviour (complete the details below).
+
+<!--
+If breaking or deprecating, describe: what changes, who is affected,
+and the migration path or recommended alternative.
+Also note any deployment, configuration, data migration or rollback considerations.
+-->
+
+## User-facing change
+
+<!--
+Does this PR change behaviour that users, operators or API consumers will notice?
+If not, write "None".
+If so, write one or two sentences suitable for release notes, in plain language and from the
+user's point of view. If users must take action when upgrading, state clearly that action is required.
+-->
+
+```release-note
+
+```
+
+## Notes for reviewers
+
+<!--
+Help reviewers focus. For example:
+  - Where to start, or a suggested order in which to read the files.
+  - Areas where you would particularly value scrutiny, or where you are uncertain.
+  - How any mechanical, generated or bulk changes were produced (for example a search-and-replace
+    or a code generator), so that reviewers can reproduce the steps.
+  - Screenshots or recordings for visual changes (include before and after where useful).
+-->
+
+## Checklist
+- [ ] The PR has a single, focused purpose and contains no unrelated changes.
+- [ ] The title is a clear, imperative summary of the change (for example, "Add retry to payment client").
+- [ ] I have added or updated tests that cover this change.
+- [ ] The build succeeds and the tests pass locally.
+- [ ] The code follows the existing patterns and style of this repository.
+- [ ] I have updated documentation, changelogs or API references where required.
+- [ ] I have reviewed my own diff, and this description reflects the final state of the change.

.github/workflows/deploy-docs.yml

@@ -0,0 +1,51 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+      - docs
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/deploy-docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pip install mkdocs mkdocs-material mkdocs-glightbox mkdocs-panzoom-plugin mkdocs-minify-plugin
+
+      - name: Build site
+        run: mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "site"
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/tests.yml

@@ -0,0 +1,61 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  containerized-tests:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Generate test environment file
+        run: ./generate-env.sh .env.test
+
+      - name: Build test images
+        run:
+          docker compose --env-file .env.test -f docker-compose.test.yaml build
+
+      - name: Run tests
+        run: |
+          docker compose --env-file .env.test -f docker-compose.test.yaml up -d
+          docker compose --env-file .env.test -f docker-compose.test.yaml wait api.specs unit.tests frontend.tests || true
+
+      - name: Check test container exit codes
+        if: always()
+        run: |
+          status=0
+          for name in test-env-database-migrations test-env-database-seed test-env-api-specs test-env-unit-tests test-env-frontend-tests; do
+            code="$(docker inspect -f '{{.State.ExitCode}}' "$name" 2>/dev/null || echo 1)"
+            echo "$name exited with $code"
+            if [ "$code" != "0" ]; then
+              status=1
+            fi
+          done
+          exit $status
+
+      - name: Show service logs on failure
+        if: failure()
+        run:
+          docker compose --env-file .env.test -f docker-compose.test.yaml logs
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: web/test-results
+
+      - name: Tear down
+        if: always()
+        run:
+          docker compose --env-file .env.test -f docker-compose.test.yaml down
+          -v

.gitignore

@@ -1,5 +1,5 @@
 # See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
-
+scratchpad.txt
 # dependencies
 /node_modules
 /.pnp
@@ -15,6 +15,15 @@
 # production
 /build
 
+# project-specific build artifacts
+/web/frontend/build/
+/web/frontend/storybook-static/
+/web/frontend/.react-router/
+/web/frontend/playwright-report/
+/web/frontend/test-results/
+/test-results/
+/docs/rendered-diagrams/
+
 # misc
 .DS_Store
 *.pem
@@ -42,6 +51,9 @@ next-env.d.ts
 
 # vscode
 .vscode
+.idea/
+*.swp
+*.swo
 
 /cloudinary-images
 
@@ -487,3 +499,11 @@ FodyWeavers.xsd
 .env.dev
 .env.test
 .env.prod
+
+*storybook.log
+storybook-static
+web/test-results/frontend/vitest-storybook.xml
+web/test-results/frontend/playwright-storybook.xml
+
+# mkdocs build output
+/site

README.md

@@ -1,278 +1,182 @@
 # The Biergarten App
 
-A social platform for craft beer enthusiasts to discover breweries, share reviews, and
-connect with fellow beer lovers.
+The Biergarten App is a full-stack directory and discovery platform for
+breweries. It provides:
 
-**Documentation**
+- JWT-based user authentication, with email confirmation and refresh-token
+  reissue
+- A searchable database of brewery locations
+- An offline data-generation pipeline that uses large language models (LLMs)
+  via Llama.cpp and Wikipedia to synthesize realistic seed data
 
-- [Getting Started](docs/getting-started.md) - Setup and installation
-- [Architecture](docs/architecture.md) - System design and patterns
-- [Database](docs/database.md) - Schema and stored procedures
-- [Docker Guide](docs/docker.md) - Container deployment
-- [Testing](docs/testing.md) - Test strategy and commands
-- [Environment Variables](docs/environment-variables.md) - Configuration reference
+The repository is organized into:
 
-**Diagrams**
+- A .NET backend (Web API + database migrations/seed) under `web/backend/`
+- A server-rendered React website (React Router + Vite) under `web/frontend/`
+- A C++20 data-generation CLI under `tooling/pipeline/`
 
-- [Architecture](docs/diagrams/pdf/architecture.pdf) - Layered architecture
-- [Deployment](docs/diagrams/pdf/deployment.pdf) - Docker topology
-- [Authentication Flow](docs/diagrams/pdf/authentication-flow.pdf) - Auth sequence
-- [Database Schema](docs/diagrams/pdf/database-schema.pdf) - Entity relationships
+Specialized documentation (setup, architecture, docker, testing, diagrams, and
+pipeline notes) lives under `docs/`.
 
-## Project Status
+## Documentation
 
-**Active Development** - Transitioning from full-stack Next.js to multi-project monorepo
+Website + backend (active stack):
 
-- Core authentication and user management APIs
-- Database schema with migrations and seeding
-- Layered architecture (Domain, Service, Infrastructure, Repository, API)
-- Comprehensive test suite (unit + integration)
-- Frontend integration with .NET API (in progress)
-- Migration from Next.js serverless functions
+- [Getting Started](docs/web/getting-started.md)
+- [Architecture](docs/web/architecture.md)
+- [Database](docs/web/database.md)
+- [Docker Guide](docs/web/docker.md)
+- [Testing](docs/web/testing.md)
+- [Environment Variables](docs/web/environment-variables.md)
+- [Token Validation](docs/web/token-validation.md)
 
----
+Data generation pipeline (C++):
 
-## Tech Stack
+- [Pipeline README](docs/pipeline/README.md)
+- [Ethics & Known Issues](docs/pipeline/ETHICS-AND-KNOWN-ISSUES.md)
 
-**Backend**: .NET 10, ASP.NET Core, SQL Server 2022, DbUp **Frontend**: Next.js 14+,
-TypeScript, TailwindCSS **Testing**: xUnit, Reqnroll (BDD), FluentAssertions, Moq
-**Infrastructure**: Docker, Docker Compose **Security**: Argon2id password hashing, JWT
-(HS256)
+## Current status
 
----
+Active areas in the repository:
 
-## Quick Start
+- .NET 10 backend (vertical-slice architecture with MediatR) + SQL Server
+- React 19 website (React Router 8 + Vite)
+- Shared Biergarten theme system + Storybook coverage
+- Auth flows and account/email integration (local Mailpit in dev compose)
+- Photo upload to S3-compatible object storage (local SeaweedFS in dev compose)
+- Data generation pipeline with C++ and Llama.cpp
 
-### Prerequisites
+Archived/reference areas:
 
-- [.NET SDK 10+](https://dotnet.microsoft.com/download)
-- [Docker Desktop](https://www.docker.com/products/docker-desktop)
-- [Node.js 18+](https://nodejs.org/) (for frontend)
+- `archive/next-js-web-app/` contains an older Next.js frontend retained for
+  reference
 
-### Start Development Environment
+## Tech stack
+
+- **Backend**: .NET 10, ASP.NET Core, SQL Server 2022, DbUp
+- **Frontend**: React 19, React Router 8, Vite 7, Tailwind CSS 4, DaisyUI 5,
+  Leaflet/React Leaflet (brewery maps)
+- **UI Documentation**: Storybook 10, Vitest browser mode, Playwright
+- **Testing**: xUnit, Reqnroll (BDD), FluentAssertions, Moq
+- **Infrastructure**: Docker, Docker Compose
+- **Security**: Argon2id password hashing, JSON Web Tokens (JWT) for
+  access/refresh/confirmation
+- **Data Pipeline**: C++20, CMake, Boost, libcurl, SQLite, llama.cpp
+
+## Requirements
+
+- .NET SDK 10 or later
+- Node.js 22 or later
+- Docker Desktop, or an equivalent Docker Engine setup
+
+See [Getting Started](docs/web/getting-started.md) for the full
+prerequisite list, including the pipeline's C++ toolchain.
+
+## Quick start
+
+For full setup details, use [Getting Started](docs/web/getting-started.md).
+This section is the shortest path to a working dev environment.
+
+### Full stack (Docker)
 
 ```bash
-# Clone repository
 git clone https://github.com/aaronpo97/the-biergarten-app
 cd the-biergarten-app
 
-# Configure environment
-cp .env.example .env.dev
-
-# Start all services
-docker compose -f docker-compose.dev.yaml up -d
-
-# View logs
-docker compose -f docker-compose.dev.yaml logs -f
+cd web && ./generate-env.sh .env.dev && cd ..
+docker compose --env-file web/.env.dev -f web/docker-compose.dev.yaml up --build -d
 ```
 
-**Access**:
+`generate-env.sh` copies `.env.example` and replaces the secret-bearing values
+with freshly randomized ones; a plain `cp` leaves placeholder secrets in
+place. See [Environment Variables](docs/web/environment-variables.md#generating-an-env-file)
+for details.
 
-- API: http://localhost:8080/swagger
-- Health: http://localhost:8080/health
+Access:
 
-### Run Tests
+- Website: http://localhost:3000
+- API Swagger: http://localhost:8080/swagger
+- Health Check: http://localhost:8080/health
+- Mailpit UI (dev SMTP): http://localhost:8025
+- SeaweedFS S3 API (dev object storage): http://localhost:8333
+
+### Frontend (Node, outside Docker)
 
 ```bash
-docker compose -f docker-compose.test.yaml up --abort-on-container-exit
+cd web/frontend
+npm install
+API_BASE_URL=http://localhost:8080 SESSION_SECRET=dev-secret-change-me npm run dev
 ```
 
-Results are in `./test-results/`
+Optional frontend tools:
 
----
-
-## Repository Structure
-
-```
-src/Core/                          # Backend (.NET)
-├── API/
-│   ├── API.Core/                 # ASP.NET Core Web API
-│   └── API.Specs/                # Integration tests (Reqnroll)
-├── Database/
-│   ├── Database.Migrations/      # DbUp migrations
-│   └── Database.Seed/            # Data seeding
-├── Domain.Entities/              # Domain models
-├── Infrastructure/               # Cross-cutting concerns
-│   ├── Infrastructure.Jwt/
-│   ├── Infrastructure.PasswordHashing/
-│   ├── Infrastructure.Email/
-│   ├── Infrastructure.Repository/
-│   └── Infrastructure.Repository.Tests/
-└── Service/                      # Business logic
-    ├── Service.Auth/
-    ├── Service.Auth.Tests/
-    └── Service.UserManagement/
-
-Website/                          # Frontend (Next.js)
-docs/                             # Documentation
-docs/diagrams/                    # PlantUML diagrams
+```bash
+cd web/frontend
+npm run storybook
+npm run test:storybook
+npm run test:storybook:playwright
 ```
 
----
+## Repository structure
 
-## Key Features
+```text
+web/
+  backend/          .NET API: API.Core (host), Features.* (vertical slices),
+                     Shared.*, Domain.*, Infrastructure.*, Database.* projects
+  frontend/         React Router website + Storybook + Playwright/Vitest
 
-### Implemented
+tooling/
+  pipeline/         C++20 seed-data generation CLI (CMake)
 
-- User registration and authentication
-- JWT token-based auth
-- Argon2id password hashing
-- SQL Server with stored procedures
-- Database migrations (DbUp)
-- Docker containerization
-- Comprehensive test suite
-- Swagger/OpenAPI documentation
-- Health checks
-
-### Planned
-
-- [ ] Brewery discovery and management
-- [ ] Beer reviews and ratings
-- [ ] Social following/followers
-- [ ] Geospatial brewery search
-- [ ] Image upload (Cloudinary)
-- [ ] Email notifications
-- [ ] OAuth integration
-
----
-
-## Architecture Highlights
-
-### Layered Architecture
+docs/
+  web/              Architecture, setup, docker, testing, diagrams
+  pipeline/         Pipeline docs, ethics notes, diagrams
 
+archive/
+  next-js-web-app/  Older Next.js frontend (reference only)
 ```
-API Layer (Controllers)
-    │
-Service Layer (Business Logic)
-    │
-Infrastructure Layer (Repositories, JWT, Email)
-    │
-Domain Layer (Entities)
-    │
-Database (SQL Server + Stored Procedures)
-```
-
-### SQL-First Approach
-
-- All queries via stored procedures
-- No ORM (no Entity Framework)
-- Version-controlled schema
-
-### Security
-
-- **Password Hashing**: Argon2id (64MB memory, 4 iterations)
-- **JWT Tokens**: HS256 with configurable expiration
-- **Credential Rotation**: Built-in password change support
-
-See [Architecture Guide](docs/architecture.md) for details.
-
----
 
 ## Testing
 
-The project includes three test suites:
-
-| Suite                  | Type        | Framework      | Purpose                |
-| ---------------------- | ----------- | -------------- | ---------------------- |
-| **API.Specs**          | Integration | Reqnroll (BDD) | End-to-end API testing |
-| **Repository.Tests**   | Unit        | xUnit          | Data access layer      |
-| **Service.Auth.Tests** | Unit        | xUnit + Moq    | Business logic         |
-
-**Run All Tests**:
+Create a test environment file, then run the full test stack (backend and
+frontend) with Docker:
 
 ```bash
-docker compose -f docker-compose.test.yaml up --abort-on-container-exit
+cd web && ./generate-env.sh .env.test && cd ..
+docker compose --env-file web/.env.test -f web/docker-compose.test.yaml up --abort-on-container-exit
 ```
 
-**Run Individual Test Suite**:
-
-```bash
-cd src/Core
-dotnet test API/API.Specs/API.Specs.csproj
-dotnet test Infrastructure/Infrastructure.Repository.Tests/Infrastructure.Repository.Tests.csproj
-dotnet test Service/Service.Auth.Tests/Service.Auth.Tests.csproj
-```
-
-See [Testing Guide](docs/testing.md) for more information.
-
----
-
-## Docker Environments
-
-The project uses three Docker Compose configurations:
-
-| File                         | Purpose       | Features                                          |
-| ---------------------------- | ------------- | ------------------------------------------------- |
-| **docker-compose.dev.yaml**  | Development   | Persistent data, hot reload, Swagger UI           |
-| **docker-compose.test.yaml** | CI/CD Testing | Isolated DB, auto-exit, test results export       |
-| **docker-compose.prod.yaml** | Production    | Optimized builds, health checks, restart policies |
-
-**Common Commands**:
-
-```bash
-# Development
-docker compose -f docker-compose.dev.yaml up -d
-docker compose -f docker-compose.dev.yaml logs -f api.core
-docker compose -f docker-compose.dev.yaml down -v
-
-# Testing
-docker compose -f docker-compose.test.yaml up --abort-on-container-exit
-docker compose -f docker-compose.test.yaml down -v
-
-# Build
-docker compose -f docker-compose.dev.yaml build
-docker compose -f docker-compose.dev.yaml build --no-cache
-```
-
-See [Docker Guide](docs/docker.md) for troubleshooting and advanced usage.
-
----
+The same command runs in CI via
+[`.github/workflows/tests.yml`](.github/workflows/tests.yml) on every push
+and pull request to `main`. See [Testing](docs/web/testing.md) for the
+full command list.
 
 ## Configuration
 
-### Required Environment Variables
+Common active variables:
 
-**Backend** (`.env.dev`):
+- Backend/Docker: `DB_SERVER`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`,
+  `ACCESS_TOKEN_SECRET`, `REFRESH_TOKEN_SECRET`, `CONFIRMATION_TOKEN_SECRET`,
+  `WEBSITE_BASE_URL`
+- Frontend runtime: `API_BASE_URL`, `SESSION_SECRET`, `NODE_ENV`
 
-```bash
-DB_SERVER=sqlserver,1433
-DB_NAME=Biergarten
-DB_USER=sa
-DB_PASSWORD=YourStrong!Passw0rd
-JWT_SECRET=<min-32-chars>
-```
-
-**Frontend** (`.env.local`):
-
-```bash
-BASE_URL=http://localhost:3000
-NODE_ENV=development
-CONFIRMATION_TOKEN_SECRET=<generated>
-RESET_PASSWORD_TOKEN_SECRET=<generated>
-SESSION_SECRET=<generated>
-# + External services (Cloudinary, Mapbox, SparkPost)
-```
-
-See [Environment Variables Guide](docs/environment-variables.md) for complete reference.
-
----
+See [Environment Variables](docs/web/environment-variables.md) for details.
 
 ## Contributing
 
 1. Fork the repository
 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
 3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-### Development Workflow
-
-1. Start development environment: `docker compose -f docker-compose.dev.yaml up -d`
-2. Make changes to code
-3. Run tests: `docker compose -f docker-compose.test.yaml up --abort-on-container-exit`
-4. Rebuild if needed: `docker compose -f docker-compose.dev.yaml up -d --build api.core`
+4. Run the checks in [Testing](docs/web/testing.md) (backend tests,
+   `npm run lint`, `npm run typecheck`)
+5. Push to the branch (`git push origin feature/amazing-feature`)
+6. Open a Pull Request
 
 ## Support
 
-- **Documentation**: [docs/](docs/)
-- **Architecture**: See [Architecture Guide](docs/architecture.md)
+Report bugs and request features via
+[GitHub Issues](https://github.com/aaronpo97/the-biergarten-app/issues).
+
+## License
+
+GPL-3.0. See [LICENSE.md](LICENSE.md).