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

.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
@@ -16,12 +16,13 @@
 /build
 
 # project-specific build artifacts
-/src/Website/build/
-/src/Website/storybook-static/
-/src/Website/.react-router/
-/src/Website/playwright-report/
-/src/Website/test-results/
+/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
@@ -501,3 +502,8 @@ FodyWeavers.xsd
 
 *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,159 +1,182 @@
 # The Biergarten App
 
-The Biergarten App is a multi-project monorepo with a .NET backend and an active React
-Router frontend in `src/Website`. The current website focuses on account flows, theme
-switching, shared UI components, Storybook coverage, and integration with the API.
+The Biergarten App is a full-stack directory and discovery platform for
+breweries. It provides:
+
+- 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
+
+The repository is organized into:
+
+- 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/`
+
+Specialized documentation (setup, architecture, docker, testing, diagrams, and
+pipeline notes) lives under `docs/`.
 
 ## Documentation
 
-- [Getting Started](docs/getting-started.md) - Local setup for backend and active website
-- [Architecture](docs/architecture.md) - Current backend and frontend architecture
-- [Docker Guide](docs/docker.md) - Container-based backend development and testing
-- [Testing](docs/testing.md) - Backend and frontend test commands
-- [Environment Variables](docs/environment-variables.md) - Active configuration reference
-- [Token Validation](docs/token-validation.md) - JWT validation architecture
-- [Legacy Website Archive](docs/archive/legacy-website-v1.md) - Archived notes for the old Next.js frontend
+Website + backend (active stack):
 
-## Diagrams
+- [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)
 
-- [Architecture](docs/diagrams-out/architecture.svg) - Layered architecture
-- [Deployment](docs/diagrams-out/deployment.svg) - Docker topology
-- [Authentication Flow](docs/diagrams-out/authentication-flow.svg) - Auth sequence
-- [Database Schema](docs/diagrams-out/database-schema.svg) - Entity relationships
+Data generation pipeline (C++):
 
-## Current Status
+- [Pipeline README](docs/pipeline/README.md)
+- [Ethics & Known Issues](docs/pipeline/ETHICS-AND-KNOWN-ISSUES.md)
+
+## Current status
 
 Active areas in the repository:
 
-- .NET 10 backend with layered architecture and SQL Server
-- React Router 7 website in `src/Website`
-- Shared Biergarten theme system with a theme guide route
-- Storybook stories and browser-based checks for shared UI
-- Auth demo flows for home, login, register, dashboard, logout, and confirmation
-- Toast-based feedback for auth outcomes
+- .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
 
-Legacy area retained for reference:
+Archived/reference areas:
 
-- `src/Website-v1` contains the archived Next.js frontend and is no longer the active website
+- `archive/next-js-web-app/` contains an older Next.js frontend retained for
+  reference
 
-## Tech Stack
+## Tech stack
 
 - **Backend**: .NET 10, ASP.NET Core, SQL Server 2022, DbUp
-- **Frontend**: React 19, React Router 7, Vite 7, Tailwind CSS 4, DaisyUI 5
+- **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, JWT access/refresh/confirmation tokens
+- **Security**: Argon2id password hashing, JSON Web Tokens (JWT) for
+  access/refresh/confirmation
+- **Data Pipeline**: C++20, CMake, Boost, libcurl, SQLite, llama.cpp
 
-## Quick Start
+## Requirements
 
-### Backend
+- .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
 git clone https://github.com/aaronpo97/the-biergarten-app
 cd the-biergarten-app
-cp .env.example .env.dev
-docker compose -f docker-compose.dev.yaml up -d
+
+cd web && ./generate-env.sh .env.dev && cd ..
+docker compose --env-file web/.env.dev -f web/docker-compose.dev.yaml up --build -d
 ```
 
-Backend 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.
 
+Access:
+
+- 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
+### Frontend (Node, outside Docker)
 
 ```bash
-cd src/Website
+cd web/frontend
 npm install
-API_BASE_URL=http://localhost:8080 SESSION_SECRET=dev-secret npm run dev
+API_BASE_URL=http://localhost:8080 SESSION_SECRET=dev-secret-change-me npm run dev
 ```
 
 Optional frontend tools:
 
 ```bash
-cd src/Website
+cd web/frontend
 npm run storybook
 npm run test:storybook
 npm run test:storybook:playwright
 ```
 
-## Repository Structure
+## Repository structure
 
 ```text
-src/Core/          Backend projects (.NET)
-src/Website/       Active React Router frontend
-src/Website-v1/    Archived legacy Next.js frontend
-docs/              Active project documentation
-docs/archive/      Archived legacy documentation
+web/
+  backend/          .NET API: API.Core (host), Features.* (vertical slices),
+                     Shared.*, Domain.*, Infrastructure.*, Database.* projects
+  frontend/         React Router website + Storybook + Playwright/Vitest
+
+tooling/
+  pipeline/         C++20 seed-data generation CLI (CMake)
+
+docs/
+  web/              Architecture, setup, docker, testing, diagrams
+  pipeline/         Pipeline docs, ethics notes, diagrams
+
+archive/
+  next-js-web-app/  Older Next.js frontend (reference only)
 ```
 
-## Key Features
-
-Implemented today:
-
-- User registration and login against the API
-- JWT-based auth with access, refresh, and confirmation flows
-- SQL Server migrations and seed projects
-- Shared form components and auth screens
-- Theme switching with Lager, Stout, Cassis, and Weizen variants
-- Storybook documentation and automated story interaction tests
-- Toast feedback for auth-related outcomes
-
-Planned next:
-
-- Brewery discovery and management
-- Beer reviews and ratings
-- Social follow relationships
-- Geospatial brewery experiences
-- Additional frontend routes beyond the auth demo
-
 ## Testing
 
-Backend suites:
-
-- `API.Specs` - integration tests
-- `Infrastructure.Repository.Tests` - repository unit tests
-- `Service.Auth.Tests` - service unit tests
-
-Frontend suites:
-
-- Storybook interaction tests via Vitest
-- Storybook browser regression checks via Playwright
-
-Run all backend tests with Docker:
+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
 ```
 
-See [Testing](docs/testing.md) for the full command list.
+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
 
 Common active variables:
 
-- Backend: `DB_SERVER`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`, `ACCESS_TOKEN_SECRET`, `REFRESH_TOKEN_SECRET`, `CONFIRMATION_TOKEN_SECRET`
-- Frontend: `API_BASE_URL`, `SESSION_SECRET`, `NODE_ENV`
+- 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`
 
-See [Environment Variables](docs/environment-variables.md) for details.
+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).

archive/sql-stored-procs-functions/02-functions/UDF_GetCountryIdByCode.sql

@@ -1,11 +1,11 @@
-CREATE OR ALTER FUNCTION dbo.UDF_GetCountryIdByCode
-(
+CREATE OR ALTER FUNCTION dbo.UDF_GetCountryIdByCode(
     @CountryCode NVARCHAR(2)
 )
-RETURNS UNIQUEIDENTIFIER
+    RETURNS UNIQUEIDENTIFIER
 AS
 BEGIN
-    DECLARE @CountryId UNIQUEIDENTIFIER;
+    DECLARE
+        @CountryId UNIQUEIDENTIFIER;
 
     SELECT @CountryId = CountryID
     FROM dbo.Country

archive/sql-stored-procs-functions/02-functions/UDF_GetStateProvinceIdByCode.sql

@@ -1,11 +1,11 @@
-CREATE OR ALTER FUNCTION dbo.UDF_GetStateProvinceIdByCode
-(
+CREATE OR ALTER FUNCTION dbo.UDF_GetStateProvinceIdByCode(
     @StateProvinceCode NVARCHAR(6)
 )
-RETURNS UNIQUEIDENTIFIER
+    RETURNS UNIQUEIDENTIFIER
 AS
 BEGIN
-    DECLARE @StateProvinceId UNIQUEIDENTIFIER;
+    DECLARE
+        @StateProvinceId UNIQUEIDENTIFIER;
     SELECT @StateProvinceId = StateProvinceID
     FROM dbo.StateProvince
     WHERE ISO3166_2 = @StateProvinceCode;

archive/sql-stored-procs-functions/03-crud/01-UserAccount/USP_CreateUserAccount.sql

@@ -0,0 +1,31 @@
+CREATE OR ALTER PROCEDURE usp_CreateUserAccount(
+    @UserAccountId UNIQUEIDENTIFIER OUTPUT,
+    @Username VARCHAR(64),
+    @FirstName NVARCHAR(128),
+    @LastName NVARCHAR(128),
+    @DateOfBirth DATETIME,
+    @Email VARCHAR(128)
+)
+AS
+BEGIN
+    SET
+        NOCOUNT ON;
+
+    DECLARE
+        @Inserted TABLE
+                  (
+                      UserAccountID UNIQUEIDENTIFIER
+                  );
+
+    INSERT INTO UserAccount
+    (Username,
+     FirstName,
+     LastName,
+     DateOfBirth,
+     Email)
+    OUTPUT INSERTED.UserAccountID INTO @Inserted
+    VALUES (@Username, @FirstName, @LastName, @DateOfBirth, @Email);
+
+    SELECT @UserAccountId = UserAccountID
+    FROM @Inserted;
+END;

archive/sql-stored-procs-functions/03-crud/01-UserAccount/USP_DeleteUserAccount.sql

@@ -0,0 +1,20 @@
+CREATE OR ALTER PROCEDURE usp_DeleteUserAccount(
+    @UserAccountId UNIQUEIDENTIFIER
+)
+AS
+BEGIN
+    SET NOCOUNT ON
+
+    IF NOT EXISTS (SELECT 1 FROM UserAccount WHERE UserAccountId = @UserAccountId)
+        BEGIN
+            RAISERROR
+                ('UserAccount with the specified ID does not exist.', 16,
+                1);
+            ROLLBACK TRANSACTION
+            RETURN
+        END
+
+    DELETE
+    FROM UserAccount
+    WHERE UserAccountId = @UserAccountId;
+END;

archive/sql-stored-procs-functions/03-crud/01-UserAccount/USP_GetAllUserAccounts.sql

@@ -2,7 +2,6 @@ CREATE OR ALTER PROCEDURE usp_GetAllUserAccounts
 AS
 BEGIN
     SET NOCOUNT ON;
-
     SELECT UserAccountID,
            Username,
            FirstName,

archive/sql-stored-procs-functions/03-crud/01-UserAccount/USP_GetUserAccountByEmail.sql

@@ -3,7 +3,8 @@ CREATE OR ALTER PROCEDURE usp_GetUserAccountByEmail(
 )
 AS
 BEGIN
-    SET NOCOUNT ON;
+    SET
+        NOCOUNT ON;
 
     SELECT UserAccountID,
            Username,

archive/sql-stored-procs-functions/03-crud/01-UserAccount/USP_GetUserAccountById.sql

@@ -3,7 +3,8 @@ CREATE OR ALTER PROCEDURE USP_GetUserAccountById(
 )
 AS
 BEGIN
-    SET NOCOUNT ON;
+    SET
+        NOCOUNT ON;
 
     SELECT UserAccountID,
            Username,

archive/sql-stored-procs-functions/03-crud/01-UserAccount/USP_GetUserAccountByUsername.sql

@@ -3,7 +3,8 @@ CREATE OR ALTER PROCEDURE usp_GetUserAccountByUsername(
 )
 AS
 BEGIN
-    SET NOCOUNT ON;
+    SET
+        NOCOUNT ON;
 
     SELECT UserAccountID,
            Username,

archive/sql-stored-procs-functions/03-crud/01-UserAccount/USP_UpdateUserAccount.sql

@@ -19,7 +19,8 @@ BEGIN
         Email       = @Email
     WHERE UserAccountId = @UserAccountId;
 
-    IF @@ROWCOUNT = 0
+    IF
+        @@ROWCOUNT = 0
         BEGIN
             THROW
                 50001, 'UserAccount with the specified ID does not exist.', 1;

archive/sql-stored-procs-functions/03-crud/02-Auth/USP_GetUserCredentialByUserAccountId.sql

@@ -0,0 +1,18 @@
+CREATE OR ALTER PROCEDURE dbo.USP_GetActiveUserCredentialByUserAccountId(
+    @UserAccountId UNIQUEIDENTIFIER
+)
+AS
+BEGIN
+    SET
+        NOCOUNT ON;
+
+    SELECT UserCredentialId,
+           UserAccountId,
+           Hash,
+           IsRevoked,
+           CreatedAt,
+           RevokedAt
+    FROM dbo.UserCredential
+    WHERE UserAccountId = @UserAccountId
+      AND IsRevoked = 0;
+END;

archive/sql-stored-procs-functions/03-crud/02-Auth/USP_InvalidateUserCredential.sql

@@ -3,13 +3,17 @@ CREATE OR ALTER PROCEDURE dbo.USP_InvalidateUserCredential(
 )
 AS
 BEGIN
-    SET NOCOUNT ON;
-    SET XACT_ABORT ON;
+    SET
+        NOCOUNT ON;
+    SET
+        XACT_ABORT ON;
 
-    BEGIN TRANSACTION;
+    BEGIN
+        TRANSACTION;
 
     EXEC dbo.USP_GetUserAccountByID @UserAccountId = @UserAccountId_;
-    IF @@ROWCOUNT = 0
+    IF
+        @@ROWCOUNT = 0
         THROW 50001, 'User account not found', 1;
 
     -- invalidate all other credentials by setting them to revoked

archive/sql-stored-procs-functions/03-crud/02-Auth/USP_RegisterUser.sql

@@ -8,12 +8,16 @@ CREATE OR ALTER PROCEDURE dbo.USP_RegisterUser(
 )
 AS
 BEGIN
-    SET NOCOUNT ON;
-    SET XACT_ABORT ON;
+    SET
+        NOCOUNT ON;
+    SET
+        XACT_ABORT ON;
 
-    DECLARE @UserAccountId_ UNIQUEIDENTIFIER;
+    DECLARE
+        @UserAccountId_ UNIQUEIDENTIFIER;
 
-    BEGIN TRANSACTION;
+    BEGIN
+        TRANSACTION;
 
     EXEC usp_CreateUserAccount
          @UserAccountId = @UserAccountId_ OUTPUT,
@@ -23,18 +27,22 @@ BEGIN
          @DateOfBirth = @DateOfBirth,
          @Email = @Email;
 
-    IF @UserAccountId_ IS NULL
+    IF
+        @UserAccountId_ IS NULL
         BEGIN
-            THROW 50000, 'Failed to create user account.', 1;
+            THROW
+                50000, 'Failed to create user account.', 1;
         END
 
     INSERT INTO dbo.UserCredential
         (UserAccountId, Hash)
     VALUES (@UserAccountId_, @Hash);
 
-    IF @@ROWCOUNT = 0
+    IF
+        @@ROWCOUNT = 0
         BEGIN
-            THROW 50002, 'Failed to create user credential.', 1;
+            THROW
+                50002, 'Failed to create user credential.', 1;
         END
     COMMIT TRANSACTION;
 

archive/sql-stored-procs-functions/03-crud/02-Auth/USP_RotateUserCredential.sql

@@ -4,9 +4,12 @@ CREATE OR ALTER PROCEDURE dbo.USP_RotateUserCredential(
 )
 AS
 BEGIN
-    SET NOCOUNT ON;
-    SET XACT_ABORT ON;
-    BEGIN TRANSACTION;
+    SET
+        NOCOUNT ON;
+    SET
+        XACT_ABORT ON;
+    BEGIN
+        TRANSACTION;
 
     EXEC USP_GetUserAccountByID @UserAccountId = @UserAccountId_
 

archive/sql-stored-procs-functions/03-crud/03-UserVerification/USP_AddUserVerification.sql

@@ -2,16 +2,21 @@ CREATE OR ALTER PROCEDURE dbo.USP_CreateUserVerification @UserAccountID_ UNIQUEI
                                                          @VerificationDateTime DATETIME = NULL
 AS
 BEGIN
-    SET NOCOUNT ON;
-    SET XACT_ABORT ON;
+    SET
+        NOCOUNT ON;
+    SET
+        XACT_ABORT ON;
 
-    IF @VerificationDateTime IS NULL
+    IF
+        @VerificationDateTime IS NULL
         SET @VerificationDateTime = GETDATE();
 
-    BEGIN TRANSACTION;
+    BEGIN
+        TRANSACTION;
 
     EXEC USP_GetUserAccountByID @UserAccountId = @UserAccountID_;
-    IF @@ROWCOUNT = 0
+    IF
+        @@ROWCOUNT = 0
         THROW 50001, 'Could not find a user with that id', 1;
 
     INSERT INTO dbo.UserVerification

archive/sql-stored-procs-functions/03-crud/04-Location/USP_CreateCity.sql

@@ -0,0 +1,38 @@
+CREATE OR ALTER PROCEDURE dbo.USP_CreateCity(
+    @CityName NVARCHAR(100),
+    @StateProvinceCode NVARCHAR(6)
+)
+AS
+BEGIN
+    SET
+        NOCOUNT ON;
+    SET
+        XACT_ABORT ON;
+
+    BEGIN
+        TRANSACTION
+        DECLARE
+            @StateProvinceId UNIQUEIDENTIFIER = dbo.UDF_GetStateProvinceIdByCode(@StateProvinceCode);
+        IF
+            @StateProvinceId IS NULL
+            BEGIN
+                THROW
+                    50001, 'State/province does not exist', 1;
+            END
+
+        IF
+            EXISTS (SELECT 1
+                    FROM dbo.City
+                    WHERE CityName = @CityName
+                      AND StateProvinceID = @StateProvinceId)
+            BEGIN
+
+                THROW
+                    50002, 'City already exists.', 1;
+            END
+
+        INSERT INTO dbo.City
+            (StateProvinceID, CityName)
+        VALUES (@StateProvinceId, @CityName);
+    COMMIT TRANSACTION
+END;

archive/sql-stored-procs-functions/03-crud/04-Location/USP_CreateCountry.sql

@@ -4,18 +4,21 @@ CREATE OR ALTER PROCEDURE dbo.USP_CreateCountry(
 )
 AS
 BEGIN
-    SET NOCOUNT ON;
-    SET XACT_ABORT ON;
-    BEGIN TRANSACTION;
+    SET
+        NOCOUNT ON;
+    SET
+        XACT_ABORT ON;
+    BEGIN
+        TRANSACTION;
 
-    IF EXISTS (SELECT 1
-    FROM dbo.Country
-    WHERE ISO3166_1 = @ISO3166_1)
+    IF
+        EXISTS (SELECT 1
+                FROM dbo.Country
+                WHERE ISO3166_1 = @ISO3166_1)
         THROW 50001, 'Country already exists', 1;
 
     INSERT INTO dbo.Country
         (CountryName, ISO3166_1)
-    VALUES
-        (@CountryName, @ISO3166_1);
+    VALUES (@CountryName, @ISO3166_1);
     COMMIT TRANSACTION;
 END;

archive/sql-stored-procs-functions/03-crud/04-Location/USP_CreateStateProvince.sql

@@ -0,0 +1,32 @@
+CREATE OR ALTER PROCEDURE dbo.USP_CreateStateProvince(
+    @StateProvinceName NVARCHAR(100),
+    @ISO3166_2 NVARCHAR(6),
+    @CountryCode NVARCHAR(2)
+)
+AS
+BEGIN
+    SET
+        NOCOUNT ON;
+    SET
+        XACT_ABORT ON;
+
+    IF
+        EXISTS (SELECT 1
+                FROM dbo.StateProvince
+                WHERE ISO3166_2 = @ISO3166_2)
+        RETURN;
+
+    DECLARE
+        @CountryId UNIQUEIDENTIFIER = dbo.UDF_GetCountryIdByCode(@CountryCode);
+    IF
+        @CountryId IS NULL
+        BEGIN
+            THROW
+                50001, 'Country does not exist', 1;
+
+        END
+
+    INSERT INTO dbo.StateProvince
+        (StateProvinceName, ISO3166_2, CountryID)
+    VALUES (@StateProvinceName, @ISO3166_2, @CountryId);
+END;

archive/sql-stored-procs-functions/03-crud/05-Breweries/USP_CreateBrewery.sql

@@ -10,29 +10,38 @@ CREATE OR ALTER PROCEDURE dbo.USP_CreateBrewery(
 )
 AS
 BEGIN
-    SET NOCOUNT ON;
-    SET XACT_ABORT ON;
+    SET
+        NOCOUNT ON;
+    SET
+        XACT_ABORT ON;
 
-    IF @BreweryName IS NULL
+    IF
+        @BreweryName IS NULL
         THROW 50001, 'Brewery name cannot be null.', 1;
 
-    IF @Description IS NULL
+    IF
+        @Description IS NULL
         THROW 50002, 'Brewery description cannot be null.', 1;
 
-    IF NOT EXISTS (SELECT 1
-                   FROM dbo.UserAccount
-                   WHERE UserAccountID = @PostedByID)
+    IF
+        NOT EXISTS (SELECT 1
+                    FROM dbo.UserAccount
+                    WHERE UserAccountID = @PostedByID)
         THROW 50404, 'User not found.', 1;
 
-    IF NOT EXISTS (SELECT 1
-                   FROM dbo.City
-                   WHERE CityID = @CityID)
+    IF
+        NOT EXISTS (SELECT 1
+                    FROM dbo.City
+                    WHERE CityID = @CityID)
         THROW 50404, 'City not found.', 1;
 
-    DECLARE @NewBreweryID UNIQUEIDENTIFIER = NEWID();
-    DECLARE @NewBrewerLocationID UNIQUEIDENTIFIER = NEWID();
+    DECLARE
+        @NewBreweryID UNIQUEIDENTIFIER = NEWID();
+    DECLARE
+        @NewBrewerLocationID UNIQUEIDENTIFIER = NEWID();
 
-    BEGIN TRANSACTION;
+    BEGIN
+        TRANSACTION;
 
     INSERT INTO dbo.BreweryPost
         (BreweryPostID, BreweryName, Description, PostedByID)

archive/sql-stored-procs-functions/03-crud/05-Breweries/USP_DeleteBrewery.sql

@@ -0,0 +1,17 @@
+CREATE OR ALTER PROCEDURE dbo.USP_DeleteBrewery @BreweryPostID UNIQUEIDENTIFIER
+AS
+BEGIN
+    SET
+        NOCOUNT ON;
+
+    IF
+        NOT EXISTS (SELECT 1
+                    FROM dbo.BreweryPost
+                    WHERE BreweryPostID = @BreweryPostID)
+        THROW 50404, 'Brewery not found.', 1;
+
+    -- BreweryPostLocation and BreweryPostPhoto cascade-delete with their parent BreweryPost.
+    DELETE
+    FROM dbo.BreweryPost
+    WHERE BreweryPostID = @BreweryPostID;
+END

archive/sql-stored-procs-functions/03-crud/05-Breweries/USP_GetAllBreweries.sql

@@ -0,0 +1,28 @@
+CREATE OR ALTER PROCEDURE dbo.USP_GetAllBreweries(
+    @Limit INT = NULL,
+    @Offset INT = NULL
+)
+AS
+BEGIN
+    SET
+        NOCOUNT ON;
+
+    SELECT bp.BreweryPostID,
+           bp.PostedByID,
+           bp.BreweryName,
+           bp.Description,
+           bp.CreatedAt,
+           bp.UpdatedAt,
+           bp.Timer,
+           bpl.BreweryPostLocationID,
+           bpl.CityID,
+           bpl.AddressLine1,
+           bpl.AddressLine2,
+           bpl.PostalCode,
+           bpl.Coordinates
+    FROM dbo.BreweryPost bp
+             LEFT JOIN dbo.BreweryPostLocation bpl
+                       ON bp.BreweryPostID = bpl.BreweryPostID
+    ORDER BY bp.CreatedAt DESC
+    OFFSET ISNULL(@Offset, 0) ROWS FETCH NEXT ISNULL(@Limit, 2147483647) ROWS ONLY;
+END

archive/sql-stored-procs-functions/03-crud/05-Breweries/USP_UpdateBrewery.sql

@@ -0,0 +1,77 @@
+CREATE OR ALTER PROCEDURE dbo.USP_UpdateBrewery(
+    @BreweryPostID UNIQUEIDENTIFIER,
+    @BreweryName NVARCHAR(256),
+    @Description NVARCHAR(512),
+    @BreweryPostLocationID UNIQUEIDENTIFIER = NULL,
+    @CityID UNIQUEIDENTIFIER = NULL,
+    @AddressLine1 NVARCHAR(256) = NULL,
+    @AddressLine2 NVARCHAR(256) = NULL,
+    @PostalCode NVARCHAR(20) = NULL,
+    @Coordinates GEOGRAPHY = NULL
+)
+AS
+BEGIN
+    SET
+        NOCOUNT ON;
+    SET
+        XACT_ABORT ON;
+
+    IF
+        @BreweryName IS NULL
+        THROW 50001, 'Brewery name cannot be null.', 1;
+
+    IF
+        @Description IS NULL
+        THROW 50002, 'Brewery description cannot be null.', 1;
+
+    IF
+        NOT EXISTS (SELECT 1
+                    FROM dbo.BreweryPost
+                    WHERE BreweryPostID = @BreweryPostID)
+        THROW 50404, 'Brewery not found.', 1;
+
+    IF
+        @CityID IS NOT NULL AND NOT EXISTS (SELECT 1
+                                            FROM dbo.City
+                                            WHERE CityID = @CityID)
+        THROW 50404, 'City not found.', 1;
+
+    BEGIN
+        TRANSACTION;
+
+    UPDATE dbo.BreweryPost
+    SET BreweryName = @BreweryName,
+        Description = @Description,
+        UpdatedAt   = GETDATE()
+    WHERE BreweryPostID = @BreweryPostID;
+
+    IF
+        @CityID IS NULL
+        BEGIN
+            -- No location supplied: clear any existing location for this brewery.
+            DELETE
+            FROM dbo.BreweryPostLocation
+            WHERE BreweryPostID = @BreweryPostID;
+        END
+    ELSE
+        IF EXISTS (SELECT 1
+                   FROM dbo.BreweryPostLocation
+                   WHERE BreweryPostID = @BreweryPostID)
+            BEGIN
+                UPDATE dbo.BreweryPostLocation
+                SET CityID       = @CityID,
+                    AddressLine1 = @AddressLine1,
+                    AddressLine2 = @AddressLine2,
+                    PostalCode   = @PostalCode,
+                    Coordinates  = @Coordinates
+                WHERE BreweryPostID = @BreweryPostID;
+            END
+        ELSE
+            BEGIN
+                INSERT INTO dbo.BreweryPostLocation
+                (BreweryPostLocationID, BreweryPostID, CityID, AddressLine1, AddressLine2, PostalCode, Coordinates)
+                VALUES (ISNULL(@BreweryPostLocationID, NEWID()), @BreweryPostID, @CityID, @AddressLine1, @AddressLine2,
+                        @PostalCode, @Coordinates);
+            END
+    COMMIT TRANSACTION;
+END

docker-compose.prod.yaml

@@ -1,87 +0,0 @@
-services:
-  sqlserver:
-    env_file: ".env.prod"
-    image: mcr.microsoft.com/mssql/server:2022-latest
-    platform: linux/amd64
-    container_name: prod-env-sqlserver
-    environment:
-      ACCEPT_EULA: "Y"
-      SA_PASSWORD: "${DB_PASSWORD}"
-      MSSQL_PID: "Express"
-    volumes:
-      - sqlserverdata-prod:/var/opt/mssql
-    healthcheck:
-      test: ["CMD-SHELL", "/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P '${DB_PASSWORD}' -C -Q 'SELECT 1' || exit 1"]
-      interval: 10s
-      timeout: 5s
-      retries: 12
-      start_period: 30s
-    networks:
-      - prodnet
-
-  database.migrations:
-    env_file: ".env.prod"
-    image: database.migrations
-    container_name: prod-env-database-migrations
-    depends_on:
-      sqlserver:
-        condition: service_healthy
-    build:
-      context: ./src/Core/Database
-      dockerfile: Database.Migrations/Dockerfile
-      args:
-        BUILD_CONFIGURATION: Release
-        APP_UID: 1000
-    environment:
-      DOTNET_RUNNING_IN_CONTAINER: "true"
-      DB_SERVER: "${DB_SERVER}"
-      DB_NAME: "${DB_NAME}"
-      DB_USER: "${DB_USER}"
-      DB_PASSWORD: "${DB_PASSWORD}"
-    restart: "no"
-    networks:
-      - prodnet
-
-  api.core:
-    env_file: ".env.prod"
-    image: api.core
-    container_name: prod-env-api-core
-    depends_on:
-      sqlserver:
-        condition: service_healthy
-    build:
-      context: ./src/Core
-      dockerfile: API/API.Core/Dockerfile
-      args:
-        BUILD_CONFIGURATION: Release
-        APP_UID: 1000
-    ports:
-      - "8080:8080"
-      - "8081:8081"
-    environment:
-      ASPNETCORE_ENVIRONMENT: "Production"
-      ASPNETCORE_URLS: "http://0.0.0.0:8080"
-      DOTNET_RUNNING_IN_CONTAINER: "true"
-      DB_SERVER: "${DB_SERVER}"
-      DB_NAME: "${DB_NAME}"
-      DB_USER: "${DB_USER}"
-      DB_PASSWORD: "${DB_PASSWORD}"
-      ACCESS_TOKEN_SECRET: "${ACCESS_TOKEN_SECRET}"
-      REFRESH_TOKEN_SECRET: "${REFRESH_TOKEN_SECRET}"
-      CONFIRMATION_TOKEN_SECRET: "${CONFIRMATION_TOKEN_SECRET}"
-      WEBSITE_BASE_URL: "${WEBSITE_BASE_URL}"
-    restart: unless-stopped
-    networks:
-      - prodnet
-    volumes:
-      - nuget-cache-prod:/root/.nuget/packages
-
-volumes:
-  sqlserverdata-prod:
-    driver: local
-  nuget-cache-prod:
-    driver: local
-
-networks:
-  prodnet:
-    driver: bridge

docs/architecture.md

@@ -1,427 +0,0 @@
-# Architecture
-
-This document describes the active architecture of The Biergarten App.
-
-## High-Level Overview
-
-The Biergarten App is a monorepo with a clear split between the backend and the active
-website:
-
-- **Backend**: .NET 10 Web API with SQL Server and a layered architecture
-- **Frontend**: React 19 + React Router 7 website in `src/Website`
-- **Architecture Style**: Layered backend plus server-rendered React frontend
-
-The legacy Next.js frontend has been retained in `src/Website-v1` for reference only and is
-documented in [archive/legacy-website-v1.md](archive/legacy-website-v1.md).
-
-## Diagrams
-
-For visual representations, see:
-
-- [architecture.svg](diagrams-out/architecture.svg) - Layered architecture diagram
-- [deployment.svg](diagrams-out/deployment.svg) - Docker deployment diagram
-- [authentication-flow.svg](diagrams-out/authentication-flow.svg) - Authentication workflow
-- [database-schema.svg](diagrams-out/database-schema.svg) - Database relationships
-
-## Backend Architecture
-
-### Layered Architecture Pattern
-
-The backend follows a strict layered architecture:
-
-```
-┌─────────────────────────────────────┐
-│         API Layer (Controllers)     │
-│   - HTTP Endpoints                  │
-│   - Request/Response mapping        │
-│   - Swagger/OpenAPI                 │
-└─────────────────────────────────────┘
-                  ↓
-┌─────────────────────────────────────┐
-│      Service Layer (Business Logic) │
-│   - Authentication logic            │
-│   - User management                 │
-│   - Validation & orchestration      │
-└─────────────────────────────────────┘
-                  ↓
-┌─────────────────────────────────────┐
-│    Infrastructure Layer (Tools)     │
-│   - JWT token generation            │
-│   - Password hashing (Argon2id)     │
-│   - Email services                  │
-│   - Repository implementations      │
-└─────────────────────────────────────┘
-                  ↓
-┌─────────────────────────────────────┐
-│      Domain Layer (Entities)        │
-│   - UserAccount, UserCredential     │
-│   - Pure POCO classes               │
-│   - No external dependencies        │
-└─────────────────────────────────────┘
-                  ↓
-┌─────────────────────────────────────┐
-│      Database (SQL Server)          │
-│   - Stored procedures               │
-│   - Tables & constraints            │
-└─────────────────────────────────────┘
-```
-
-### Layer Responsibilities
-
-#### API Layer (`API.Core`)
-
-**Purpose**: HTTP interface and request handling
-
-**Components**:
-
-- Controllers (`AuthController`, `UserController`)
-- Middleware for error handling
-- Swagger/OpenAPI documentation
-- Health check endpoints
-
-**Dependencies**:
-
-- Service layer
-- ASP.NET Core framework
-
-**Rules**:
-
-- No business logic
-- Only request/response transformation
-- Delegates all work to Service layer
-
-#### Service Layer (`Service.Auth`, `Service.UserManagement`)
-
-**Purpose**: Business logic and orchestration
-
-**Components**:
-
-- Authentication services (login, registration)
-- User management services
-- Business rule validation
-- Transaction coordination
-
-**Dependencies**:
-
-- Infrastructure layer (repositories, JWT, password hashing)
-- Domain entities
-
-**Rules**:
-
-- Contains all business logic
-- Coordinates multiple infrastructure components
-- No direct database access (uses repositories)
-- Returns domain models, not DTOs
-
-#### Infrastructure Layer
-
-**Purpose**: Technical capabilities and external integrations
-
-**Components**:
-
-- **Infrastructure.Repository**: Data access via stored procedures
-- **Infrastructure.Jwt**: JWT token generation and validation
-- **Infrastructure.PasswordHashing**: Argon2id password hashing
-- **Infrastructure.Email**: Email sending capabilities
-- **Infrastructure.Email.Templates**: Email template rendering
-
-**Dependencies**:
-
-- Domain entities
-- External libraries (ADO.NET, JWT, Argon2, etc.)
-
-**Rules**:
-
-- Implements technical concerns
-- No business logic
-- Reusable across services
-
-#### Domain Layer (`Domain.Entities`)
-
-**Purpose**: Core business entities and models
-
-**Components**:
-
-- `UserAccount` - User profile data
-- `UserCredential` - Authentication credentials
-- `UserVerification` - Account verification state
-
-**Dependencies**:
-
-- None (pure domain)
-
-**Rules**:
-
-- Plain Old CLR Objects (POCOs)
-- No framework dependencies
-- No infrastructure references
-- Represents business concepts
-
-### Design Patterns
-
-#### Repository Pattern
-
-**Purpose**: Abstract database access behind interfaces
-
-**Implementation**:
-
-- `IAuthRepository` - Authentication queries
-- `IUserAccountRepository` - User account queries
-- `DefaultSqlConnectionFactory` - Connection management
-
-**Benefits**:
-
-- Testable (easy to mock)
-- SQL-first approach (stored procedures)
-- Centralized data access logic
-
-**Example**:
-
-```csharp
-public interface IAuthRepository
-{
-    Task<UserCredential> GetUserCredentialAsync(string username);
-    Task<int> CreateUserAccountAsync(UserAccount user, UserCredential credential);
-}
-```
-
-#### Dependency Injection
-
-**Purpose**: Loose coupling and testability
-
-**Configuration**: `Program.cs` registers all services
-
-**Lifetimes**:
-
-- Scoped: Repositories, Services (per request)
-- Singleton: Connection factories, JWT configuration
-- Transient: Utilities, helpers
-
-#### SQL-First Approach
-
-**Purpose**: Leverage database capabilities
-
-**Strategy**:
-
-- All queries via stored procedures
-- No ORM (Entity Framework not used)
-- Database handles complex logic
-- Application focuses on orchestration
-
-**Stored Procedure Examples**:
-
-- `USP_RegisterUser` - User registration
-- `USP_GetUserAccountByUsername` - User lookup
-- `USP_RotateUserCredential` - Password update
-
-## Frontend Architecture
-
-### Active Website (`src/Website`)
-
-The current website is a React Router 7 application with server-side rendering enabled.
-
-```text
-src/Website/
-├── app/
-│   ├── components/      Shared UI such as Navbar, FormField, SubmitButton, ToastProvider
-│   ├── lib/             Auth helpers, schemas, and theme metadata
-│   ├── routes/          Route modules for home, login, register, dashboard, confirm, theme
-│   ├── root.tsx         App shell and global providers
-│   └── app.css          Theme tokens and global styling
-├── .storybook/          Storybook config and preview setup
-├── stories/             Storybook stories for shared UI and themes
-├── tests/playwright/    Storybook Playwright coverage
-└── package.json         Frontend scripts and dependencies
-```
-
-### Frontend Responsibilities
-
-- Render the auth demo and theme guide routes
-- Manage cookie-backed website session state
-- Call the .NET API for login, registration, token refresh, and confirmation
-- Provide shared UI building blocks for forms, navigation, themes, and toasts
-- Supply Storybook documentation and browser-based component verification
-
-### Theme System
-
-The active website uses semantic DaisyUI theme tokens backed by four Biergarten themes:
-
-- Biergarten Lager
-- Biergarten Stout
-- Biergarten Cassis
-- Biergarten Weizen
-
-All component styling should prefer semantic tokens such as `primary`, `success`,
-`surface`, and `highlight` instead of hard-coded color values.
-
-### Legacy Frontend
-
-The previous Next.js frontend has been archived at `src/Website-v1`. Active product and
-engineering documentation should point to `src/Website`, while legacy notes live in
-[archive/legacy-website-v1.md](archive/legacy-website-v1.md).
-
-## Security Architecture
-
-### Authentication Flow
-
-1. **Registration**:
-   - User submits credentials
-   - Password hashed with Argon2id
-   - User account created
-   - JWT token issued
-
-2. **Login**:
-   - User submits credentials
-   - Password verified against hash
-   - JWT token issued
-   - Token stored client-side
-
-3. **API Requests**:
-   - Client sends JWT in Authorization header
-   - Middleware validates token
-   - Request proceeds if valid
-
-### Password Security
-
-**Algorithm**: Argon2id
-
-- Memory: 64MB
-- Iterations: 4
-- Parallelism: CPU core count
-- Salt: 128-bit (16 bytes)
-- Hash: 256-bit (32 bytes)
-
-### JWT Tokens
-
-**Algorithm**: HS256 (HMAC-SHA256)
-
-**Claims**:
-
-- `sub` - User ID
-- `unique_name` - Username
-- `jti` - Unique token ID
-- `iat` - Issued at timestamp
-- `exp` - Expiration timestamp
-
-**Configuration** (appsettings.json):
-
-```json
-{
-  "Jwt": {
-    "ExpirationMinutes": 60,
-    "Issuer": "biergarten-api",
-    "Audience": "biergarten-users"
-  }
-}
-```
-
-## Database Architecture
-
-### SQL-First Philosophy
-
-**Principles**:
-
-1. Database is source of truth
-2. Complex queries in stored procedures
-3. Database handles referential integrity
-4. Application orchestrates, database executes
-
-**Benefits**:
-
-- Performance optimization via execution plans
-- Centralized query logic
-- Version-controlled schema (migrations)
-- Easier query profiling and tuning
-
-### Migration Strategy
-
-**Tool**: DbUp
-
-**Process**:
-
-1. Write SQL migration script
-2. Embed in `Database.Migrations` project
-3. Run migrations on startup
-4. Idempotent and versioned
-
-**Migration Files**:
-
-```
-scripts/
-├── 001-CreateUserTables.sql
-├── 002-CreateLocationTables.sql
-├── 003-CreateBreweryTables.sql
-└── ...
-```
-
-### Data Seeding
-
-**Purpose**: Populate development/test databases
-
-**Implementation**: `Database.Seed` project
-
-**Seed Data**:
-
-- Countries, states/provinces, cities
-- Test user accounts
-- Sample breweries (future)
-
-## Deployment Architecture
-
-### Docker Containerization
-
-**Container Structure**:
-
-- `sqlserver` - SQL Server 2022
-- `database.migrations` - Schema migration runner
-- `database.seed` - Data seeder
-- `api.core` - ASP.NET Core Web API
-
-**Environments**:
-
-- Development (`docker-compose.dev.yaml`)
-- Testing (`docker-compose.test.yaml`)
-- Production (`docker-compose.prod.yaml`)
-
-For details, see [Docker Guide](docker.md).
-
-### Health Checks
-
-**SQL Server**: Validates database connectivity **API**: Checks service health and
-dependencies
-
-**Configuration**:
-
-```yaml
-healthcheck:
-  test: ["CMD-SHELL", "sqlcmd health check"]
-  interval: 10s
-  retries: 12
-  start_period: 30s
-```
-
-## Testing Architecture
-
-### Test Pyramid
-
-```
-    ┌──────────────┐
-    │  Integration │  ← API.Specs (Reqnroll)
-    │    Tests     │
-    ├──────────────┤
-    │  Unit Tests  │  ← Service.Auth.Tests
-    │   (Service)  │     Repository.Tests
-    ├──────────────┤
-    │  Unit Tests  │
-    │ (Repository) │
-    └──────────────┘
-```
-
-**Strategy**:
-
-- Many unit tests (fast, isolated)
-- Fewer integration tests (slower, e2e)
-- Mock external dependencies
-- Test database for integration tests
-
-For details, see [Testing Guide](testing.md).

docs/archive/legacy-website-v1.md

@@ -1,56 +0,0 @@
-# Legacy Website Archive (`src/Website-v1`)
-
-This archive captures high-level notes about the previous Biergarten frontend so active
-project documentation can focus on the current website in `src/Website`.
-
-## Status
-
-- `src/Website-v1` is retained for historical reference only
-- It is not the active frontend used by current setup, docs, or testing guidance
-- New product and engineering work should target `src/Website`
-
-## Legacy Stack Summary
-
-The archived frontend used a different application model from the current website:
-
-- Next.js 14
-- React 18
-- Prisma
-- Postgres / Neon-hosted database workflows
-- Next.js API routes and server-side controllers
-- Additional third-party integrations such as Cloudinary, Mapbox, and SparkPost
-
-## Why It Was Archived
-
-The active website moved to a React Router-based frontend that talks directly to the .NET
-API. As part of that shift, the main docs were updated to describe:
-
-- `src/Website` as the active frontend
-- React Router route modules and server rendering
-- Storybook-based component documentation and tests
-- Current frontend runtime variables: `API_BASE_URL`, `SESSION_SECRET`, and `NODE_ENV`
-
-## Legacy Documentation Topics Moved Out of Active Docs
-
-The following categories were removed from active documentation and intentionally archived:
-
-- Next.js application structure guidance
-- Prisma and Postgres frontend setup
-- Legacy frontend environment variables
-- External service setup that only applied to `src/Website-v1`
-- Old frontend local setup instructions
-
-## When To Use This Archive
-
-Use this file only if you need to:
-
-- inspect the historical frontend implementation
-- compare old flows against the current website
-- migrate or recover legacy logic from `src/Website-v1`
-
-For all active work, use:
-
-- [Getting Started](../getting-started.md)
-- [Architecture](../architecture.md)
-- [Environment Variables](../environment-variables.md)
-- [Testing](../testing.md)

docs/diagrams-src/architecture.puml

@@ -1,75 +0,0 @@
-@startuml architecture
-!theme plain
-skinparam backgroundColor #FFFFFF
-skinparam defaultFontName Arial
-skinparam packageStyle rectangle
-
-title The Biergarten App - Layered Architecture
-
-package "API Layer" #E3F2FD {
-  [API.Core\nASP.NET Core Web API] as API
-  note right of API
-    - Controllers (Auth, User)
-    - Swagger/OpenAPI
-    - Middleware
-    - Health Checks
-  end note
-}
-
-package "Service Layer" #F3E5F5 {
-  [Service.Auth] as AuthSvc
-  [Service.UserManagement] as UserSvc
-  note right of AuthSvc
-    - Business Logic
-    - Validation
-    - Orchestration
-  end note
-}
-
-package "Infrastructure Layer" #FFF3E0 {
-  [Infrastructure.Repository] as Repo
-  [Infrastructure.Jwt] as JWT
-  [Infrastructure.PasswordHashing] as PwdHash
-  [Infrastructure.Email] as Email
-}
-
-package "Domain Layer" #E8F5E9 {
-  [Domain.Entities] as Domain
-  note right of Domain
-    - UserAccount
-    - UserCredential
-    - UserVerification
-  end note
-}
-
-database "SQL Server" {
-  [Stored Procedures] as SP
-  [Tables] as Tables
-}
-
-' Relationships
-API --> AuthSvc
-API --> UserSvc
-
-AuthSvc --> Repo
-AuthSvc --> JWT
-AuthSvc --> PwdHash
-AuthSvc --> Email
-
-UserSvc --> Repo
-
-Repo --> SP
-Repo --> Domain
-SP --> Tables
-
-AuthSvc --> Domain
-UserSvc --> Domain
-
-' Notes
-note left of Repo
-  SQL-first approach
-  All queries via
-  stored procedures
-end note
-
-@enduml

docs/diagrams-src/authentication-flow.puml

@@ -1,298 +0,0 @@
-@startuml authentication-flow
-!theme plain
-skinparam backgroundColor #FFFFFF
-skinparam defaultFontName Arial
-skinparam sequenceMessageAlign center
-skinparam maxMessageSize 200
-
-title User Authentication Flow - Expanded
-
-actor User
-participant "API\nController" as API
-box "Service Layer" #LightBlue
-participant "RegisterService" as RegSvc
-participant "LoginService" as LoginSvc
-participant "TokenService" as TokenSvc
-participant "EmailService" as EmailSvc
-end box
-box "Infrastructure Layer" #LightGreen
-participant "Argon2\nInfrastructure" as Argon2
-participant "JWT\nInfrastructure" as JWT
-participant "Email\nProvider" as SMTP
-participant "Template\nProvider" as Template
-end box
-box "Repository Layer" #LightYellow
-participant "AuthRepository" as AuthRepo
-participant "UserAccount\nRepository" as UserRepo
-end box
-database "SQL Server\nStored Procedures" as DB
-
-== Registration Flow ==
-
-User -> API: POST /api/auth/register\n{username, firstName, lastName,\nemail, dateOfBirth, password}
-activate API
-
-note right of API
-  FluentValidation runs:
-  - Username: 3-64 chars, alphanumeric + [._-]
-  - Email: valid format, max 128 chars
-  - Password: min 8 chars, uppercase,\n    lowercase, number, special char
-  - DateOfBirth: must be 19+ years old
-end note
-
-API -> API: Validate request\n(FluentValidation)
-
-alt Validation fails
-  API -> User: 400 Bad Request\n{errors: {...}}
-else Validation succeeds
-  API -> RegSvc: RegisterAsync(userAccount, password)
-  activate RegSvc
-
-  RegSvc -> AuthRepo: GetUserByUsernameAsync(username)
-  activate AuthRepo
-  AuthRepo -> DB: EXEC usp_GetUserAccountByUsername
-  activate DB
-  DB --> AuthRepo: null (user doesn't exist)
-  deactivate DB
-  deactivate AuthRepo
-
-  RegSvc -> AuthRepo: GetUserByEmailAsync(email)
-  activate AuthRepo
-  AuthRepo -> DB: EXEC usp_GetUserAccountByEmail
-  activate DB
-  DB --> AuthRepo: null (email doesn't exist)
-  deactivate DB
-  deactivate AuthRepo
-
-  alt User/Email already exists
-    RegSvc -> API: throw ConflictException
-    API -> User: 409 Conflict\n"Username or email already exists"
-  else User doesn't exist
-
-    RegSvc -> Argon2: Hash(password)
-    activate Argon2
-    note right of Argon2
-      Argon2id parameters:
-      - Salt: 16 bytes (128-bit)
-      - Memory: 64MB
-      - Iterations: 4
-      - Parallelism: CPU count
-      - Hash output: 32 bytes
-    end note
-    Argon2 -> Argon2: Generate random salt\n(16 bytes)
-    Argon2 -> Argon2: Hash password with\nArgon2id algorithm
-    Argon2 --> RegSvc: "base64(salt):base64(hash)"
-    deactivate Argon2
-
-    RegSvc -> AuthRepo: RegisterUserAsync(\n  username, firstName, lastName,\n  email, dateOfBirth, hash)
-    activate AuthRepo
-
-    AuthRepo -> DB: EXEC USP_RegisterUser
-    activate DB
-    note right of DB
-      Transaction begins:
-      1. INSERT UserAccount
-      2. INSERT UserCredential
-         (with hashed password)
-      Transaction commits
-    end note
-    DB -> DB: BEGIN TRANSACTION
-    DB -> DB: INSERT INTO UserAccount\n(Username, FirstName, LastName,\nEmail, DateOfBirth)
-    DB -> DB: OUTPUT INSERTED.UserAccountID
-    DB -> DB: INSERT INTO UserCredential\n(UserAccountId, Hash)
-    DB -> DB: COMMIT TRANSACTION
-    DB --> AuthRepo: UserAccountId (GUID)
-    deactivate DB
-
-    AuthRepo --> RegSvc: UserAccount entity
-    deactivate AuthRepo
-
-    RegSvc -> TokenSvc: GenerateAccessToken(userAccount)
-    activate TokenSvc
-    TokenSvc -> JWT: GenerateJwt(userId, username, expiry)
-    activate JWT
-    note right of JWT
-      JWT Configuration:
-      - Algorithm: HS256
-      - Expires: 1 hour
-      - Claims:
-        * sub: userId
-        * unique_name: username
-        * jti: unique token ID
-    end note
-    JWT -> JWT: Create JWT with claims
-    JWT -> JWT: Sign with secret key
-    JWT --> TokenSvc: Access Token
-    deactivate JWT
-    TokenSvc --> RegSvc: Access Token
-    deactivate TokenSvc
-
-    RegSvc -> TokenSvc: GenerateRefreshToken(userAccount)
-    activate TokenSvc
-    TokenSvc -> JWT: GenerateJwt(userId, username, expiry)
-    activate JWT
-    note right of JWT
-      Refresh Token:
-      - Expires: 21 days
-      - Same structure as access token
-    end note
-    JWT --> TokenSvc: Refresh Token
-    deactivate JWT
-    TokenSvc --> RegSvc: Refresh Token
-    deactivate TokenSvc
-
-    RegSvc -> EmailSvc: SendRegistrationEmailAsync(\n  createdUser, confirmationToken)
-    activate EmailSvc
-
-    EmailSvc -> Template: RenderUserRegisteredEmailAsync(\n  firstName, confirmationLink)
-    activate Template
-    note right of Template
-      Razor Component:
-      - Header with branding
-      - Welcome message
-      - Confirmation button
-      - Footer
-    end note
-    Template -> Template: Render Razor component\nto HTML
-    Template --> EmailSvc: HTML email content
-    deactivate Template
-
-    EmailSvc -> SMTP: SendAsync(email, subject, body)
-    activate SMTP
-    note right of SMTP
-      SMTP Configuration:
-      - Host: from env (SMTP_HOST)
-      - Port: from env (SMTP_PORT)
-      - TLS: StartTLS
-      - Auth: username/password
-    end note
-    SMTP -> SMTP: Create MIME message
-    SMTP -> SMTP: Connect to SMTP server
-    SMTP -> SMTP: Authenticate
-    SMTP -> SMTP: Send email
-    SMTP -> SMTP: Disconnect
-    SMTP --> EmailSvc: Success / Failure
-    deactivate SMTP
-
-    alt Email sent successfully
-      EmailSvc --> RegSvc: emailSent = true
-    else Email failed
-      EmailSvc --> RegSvc: emailSent = false\n(error suppressed)
-    end
-    deactivate EmailSvc
-
-    RegSvc --> API: RegisterServiceReturn(\n  userAccount, accessToken,\n  refreshToken, emailSent)
-    deactivate RegSvc
-
-    API -> API: Create response body
-    API -> User: 201 Created\n{\n  message: "User registered successfully",\n  payload: {\n    userAccountId, username,\n    accessToken, refreshToken,\n    confirmationEmailSent\n  }\n}
-  end
-end
-deactivate API
-
-== Login Flow ==
-
-User -> API: POST /api/auth/login\n{username, password}
-activate API
-
-API -> API: Validate request\n(FluentValidation)
-
-alt Validation fails
-  API -> User: 400 Bad Request\n{errors: {...}}
-else Validation succeeds
-
-  API -> LoginSvc: LoginAsync(username, password)
-  activate LoginSvc
-
-  LoginSvc -> AuthRepo: GetUserByUsernameAsync(username)
-  activate AuthRepo
-  AuthRepo -> DB: EXEC usp_GetUserAccountByUsername
-  activate DB
-  DB -> DB: SELECT FROM UserAccount\nWHERE Username = @Username
-  DB --> AuthRepo: UserAccount entity
-  deactivate DB
-  deactivate AuthRepo
-
-  alt User not found
-    LoginSvc -> API: throw UnauthorizedException\n"Invalid username or password"
-    API -> User: 401 Unauthorized
-  else User found
-
-    LoginSvc -> AuthRepo: GetActiveCredentialByUserAccountIdAsync(userId)
-    activate AuthRepo
-    AuthRepo -> DB: EXEC USP_GetActiveUserCredentialByUserAccountId
-    activate DB
-    note right of DB
-      SELECT FROM UserCredential
-      WHERE UserAccountId = @UserAccountId
-        AND IsRevoked = 0
-    end note
-    DB --> AuthRepo: UserCredential entity
-    deactivate DB
-    deactivate AuthRepo
-
-    alt No active credential
-      LoginSvc -> API: throw UnauthorizedException
-      API -> User: 401 Unauthorized
-    else Active credential found
-
-      LoginSvc -> Argon2: Verify(password, storedHash)
-      activate Argon2
-      note right of Argon2
-        1. Split stored hash: "salt:hash"
-        2. Extract salt
-        3. Hash provided password\n   with same salt
-        4. Constant-time comparison
-      end note
-      Argon2 -> Argon2: Parse salt from stored hash
-      Argon2 -> Argon2: Hash provided password\nwith extracted salt
-      Argon2 -> Argon2: FixedTimeEquals(\n  computed, stored)
-      Argon2 --> LoginSvc: true/false
-      deactivate Argon2
-
-      alt Password invalid
-        LoginSvc -> API: throw UnauthorizedException
-        API -> User: 401 Unauthorized
-      else Password valid
-
-        LoginSvc -> TokenSvc: GenerateAccessToken(user)
-        activate TokenSvc
-        TokenSvc -> JWT: GenerateJwt(...)
-        activate JWT
-        JWT --> TokenSvc: Access Token
-        deactivate JWT
-        TokenSvc --> LoginSvc: Access Token
-        deactivate TokenSvc
-
-        LoginSvc -> TokenSvc: GenerateRefreshToken(user)
-        activate TokenSvc
-        TokenSvc -> JWT: GenerateJwt(...)
-        activate JWT
-        JWT --> TokenSvc: Refresh Token
-        deactivate JWT
-        TokenSvc --> LoginSvc: Refresh Token
-        deactivate TokenSvc
-
-        LoginSvc --> API: LoginServiceReturn(\n  userAccount, accessToken,\n  refreshToken)
-        deactivate LoginSvc
-
-        API -> User: 200 OK\n{\n  message: "Logged in successfully",\n  payload: {\n    userAccountId, username,\n    accessToken, refreshToken\n  }\n}
-      end
-    end
-  end
-end
-deactivate API
-
-== Error Handling (Global Exception Filter) ==
-
-note over API
-  GlobalExceptionFilter catches:
-  - ValidationException → 400 Bad Request
-  - ConflictException → 409 Conflict
-  - NotFoundException → 404 Not Found
-  - UnauthorizedException → 401 Unauthorized
-  - ForbiddenException → 403 Forbidden
-  - All others → 500 Internal Server Error
-end note
-
-@enduml

docs/diagrams-src/database-schema.puml

@@ -1,104 +0,0 @@
-@startuml database-schema
-!theme plain
-skinparam backgroundColor #FFFFFF
-skinparam defaultFontName Arial
-skinparam linetype ortho
-
-title Key Database Schema - User & Authentication
-
-entity "UserAccount" as User {
-  * UserAccountId: INT <<PK>>
-  --
-  * Username: NVARCHAR(30) <<UNIQUE>>
-  * Email: NVARCHAR(255) <<UNIQUE>>
-  * FirstName: NVARCHAR(50)
-  * LastName: NVARCHAR(50)
-  Bio: NVARCHAR(500)
-  CreatedAt: DATETIME2
-  UpdatedAt: DATETIME2
-  LastLoginAt: DATETIME2
-}
-
-entity "UserCredential" as Cred {
-  * UserCredentialId: INT <<PK>>
-  --
-  * UserAccountId: INT <<FK>>
-  * PasswordHash: VARBINARY(32)
-  * PasswordSalt: VARBINARY(16)
-  CredentialRotatedAt: DATETIME2
-  CredentialExpiresAt: DATETIME2
-  CredentialRevokedAt: DATETIME2
-  * IsActive: BIT
-  CreatedAt: DATETIME2
-}
-
-entity "UserVerification" as Verify {
-  * UserVerificationId: INT <<PK>>
-  --
-  * UserAccountId: INT <<FK>>
-  * IsVerified: BIT
-  VerifiedAt: DATETIME2
-  VerificationToken: NVARCHAR(255)
-  TokenExpiresAt: DATETIME2
-}
-
-entity "UserAvatar" as Avatar {
-  * UserAvatarId: INT <<PK>>
-  --
-  * UserAccountId: INT <<FK>>
-  PhotoId: INT <<FK>>
-  * IsActive: BIT
-  CreatedAt: DATETIME2
-}
-
-entity "UserFollow" as Follow {
-  * UserFollowId: INT <<PK>>
-  --
-  * FollowerUserId: INT <<FK>>
-  * FollowedUserId: INT <<FK>>
-  CreatedAt: DATETIME2
-}
-
-entity "Photo" as Photo {
-  * PhotoId: INT <<PK>>
-  --
-  * Url: NVARCHAR(500)
-  * CloudinaryPublicId: NVARCHAR(255)
-  Width: INT
-  Height: INT
-  Format: NVARCHAR(10)
-  CreatedAt: DATETIME2
-}
-
-' Relationships
-User ||--o{ Cred : "has"
-User ||--o| Verify : "has"
-User ||--o{ Avatar : "has"
-User ||--o{ Follow : "follows"
-User ||--o{ Follow : "followed by"
-Avatar }o--|| Photo : "refers to"
-
-note right of Cred
-  Password hashing:
-  - Algorithm: Argon2id
-  - Memory: 64MB
-  - Iterations: 4
-  - Salt: 128-bit
-  - Hash: 256-bit
-end note
-
-note right of Verify
-  Account verification
-  via email token
-  with expiry
-end note
-
-note bottom of User
-  Core stored procedures:
-  - USP_RegisterUser
-  - USP_GetUserAccountByUsername
-  - USP_RotateUserCredential
-  - USP_UpdateUserAccount
-end note
-
-@enduml

docs/diagrams-src/deployment.puml

@@ -1,227 +0,0 @@
-@startuml deployment
-!theme plain
-skinparam backgroundColor #FFFFFF
-skinparam defaultFontName Arial
-skinparam linetype ortho
-
-title Docker Deployment Architecture
-
-' External systems
-actor Developer
-cloud "Docker Host" as Host
-
-package "Development Environment\n(docker-compose.dev.yaml)" #E3F2FD {
-
-  node "SQL Server\n(mcr.microsoft.com/mssql/server:2022-latest)" as DevDB {
-    database "Biergarten\nDatabase" as DevDBInner {
-      portin "1433"
-    }
-    note right
-      Environment:
-      - ACCEPT_EULA=Y
-      - SA_PASSWORD=***
-      - MSSQL_PID=Developer
-
-      Volumes:
-      - biergarten-dev-data
-    end note
-  }
-
-  node "API Container\n(API.Core)" as DevAPI {
-    component "ASP.NET Core 10" as API1
-    portin "8080:8080 (HTTP)" as DevPort1
-    portin "8081:8081 (HTTPS)" as DevPort2
-
-    note right
-      Environment:
-      - ASPNETCORE_ENVIRONMENT=Development
-      - DB_SERVER=sql-server
-      - DB_NAME=Biergarten
-      - DB_USER/PASSWORD
-      - JWT_SECRET
-      - SMTP_* (10+ variables)
-
-      Health Check:
-      /health endpoint
-    end note
-  }
-
-  node "Migrations\n(run-once)" as DevMig {
-    component "Database.Migrations" as Mig1
-    note bottom
-      Runs: DbUp migrations
-      Environment:
-      - CLEAR_DATABASE=false
-      Depends on: sql-server
-    end note
-  }
-
-  node "Seed\n(run-once)" as DevSeed {
-    component "Database.Seed" as Seed1
-    note bottom
-      Creates:
-      - 100 test users
-      - Location data (US/CA/MX)
-      - test.user account
-      Depends on: migrations
-    end note
-  }
-
-}
-
-package "Test Environment\n(docker-compose.test.yaml)" #FFF3E0 {
-
-  node "SQL Server\n(isolated instance)" as TestDB {
-    database "Biergarten\nTest Database" as TestDBInner {
-      portin "1434"
-    }
-    note right
-      Fresh instance each run
-      CLEAR_DATABASE=true
-
-      Volumes:
-      - biergarten-test-data
-      (ephemeral)
-    end note
-  }
-
-  node "Migrations\n(test)" as TestMig {
-    component "Database.Migrations"
-  }
-
-  node "Seed\n(test)" as TestSeed {
-    component "Database.Seed"
-    note bottom
-      Minimal seed:
-      - test.user only
-      - Essential data
-    end note
-  }
-
-  node "API.Specs\n(Integration Tests)" as Specs {
-    component "Reqnroll + xUnit" as SpecsComp
-    note right
-      Tests:
-      - Registration flow
-      - Login flow
-      - Validation rules
-      - 404 handling
-
-      Uses: TestApiFactory
-      Mocks: Email services
-    end note
-  }
-
-  node "Infrastructure.Repository.Tests\n(Unit Tests)" as RepoTests {
-    component "xUnit + DbMocker" as RepoComp
-    note right
-      Tests:
-      - AuthRepository
-      - UserAccountRepository
-      - SQL command building
-
-      Uses: Mock connections
-      No real database needed
-    end note
-  }
-
-  node "Service.Auth.Tests\n(Unit Tests)" as SvcTests {
-    component "xUnit + Moq" as SvcComp
-    note right
-      Tests:
-      - RegisterService
-      - LoginService
-      - Token generation
-
-      Uses: Mocked dependencies
-      No database or infrastructure
-    end note
-  }
-
-}
-
-folder "test-results/\n(mounted volume)" as Results {
-  file "api-specs/\n  results.trx" as Result1
-  file "repository-tests/\n  results.trx" as Result2
-  file "service-auth-tests/\n  results.trx" as Result3
-
-  note bottom
-    TRX format
-    Readable by:
-    - Visual Studio
-    - Azure DevOps
-    - GitHub Actions
-  end note
-}
-
-' External access
-Developer --> Host : docker compose up
-Host --> DevAPI : http://localhost:8080
-
-' Development dependencies
-DevMig --> DevDB : 1. Run migrations
-DevSeed --> DevDB : 2. Seed data
-DevAPI --> DevDB : 3. Connect & serve
-DevMig .up.> DevDB : depends_on
-DevSeed .up.> DevMig : depends_on
-DevAPI .up.> DevSeed : depends_on
-
-' Test dependencies
-TestMig --> TestDB : 1. Migrate
-TestSeed --> TestDB : 2. Seed
-Specs --> TestDB : 3. Integration test
-RepoTests ..> TestDB : Mock (no connection)
-SvcTests ..> TestDB : Mock (no connection)
-
-TestMig .up.> TestDB : depends_on
-TestSeed .up.> TestMig : depends_on
-Specs .up.> TestSeed : depends_on
-
-' Test results export
-Specs --> Results : Export TRX
-RepoTests --> Results : Export TRX
-SvcTests --> Results : Export TRX
-
-' Network notes
-note bottom of DevDB
-  <b>Dev Network (bridge: biergarten-dev)</b>
-  Internal DNS:
-  - sql-server (resolves to SQL container)
-  - api (resolves to API container)
-end note
-
-note bottom of TestDB
-  <b>Test Network (bridge: biergarten-test)</b>
-  All test components isolated
-end note
-
-' Startup sequence notes
-note top of DevMig
-  Startup Order:
-  1. SQL Server (health check)
-  2. Migrations (run-once)
-  3. Seed (run-once)
-  4. API (long-running)
-end note
-
-note top of Specs
-  Test Execution:
-  All tests run in parallel
-  Results aggregated
-end note
-
-' Production note
-note as ProductionNote
-  <b>Production Deployment (not shown):</b>
-
-  Would include:
-  • Azure SQL Database / AWS RDS
-  • Azure Container Apps / ECS
-  • Azure Key Vault for secrets
-  • Application Insights / CloudWatch
-  • Load balancer
-  • HTTPS termination
-  • CDN for static assets
-end note
-
-@enduml

docs/docker.md

@@ -1,327 +0,0 @@
-# Docker Guide
-
-This document covers Docker deployment, configuration, and troubleshooting for The
-Biergarten App.
-
-## Overview
-
-The project uses Docker Compose to orchestrate multiple services:
-
-- SQL Server 2022 database
-- Database migrations runner (DbUp)
-- Database seeder
-- .NET API
-- Test runners
-
-See the [deployment diagram](diagrams/pdf/deployment.pdf) for visual representation.
-
-## Docker Compose Environments
-
-### 1. Development (`docker-compose.dev.yaml`)
-
-**Purpose**: Local development with persistent data
-
-**Features**:
-
-- Persistent SQL Server volume
-- Hot reload support
-- Swagger UI enabled
-- Seed data included
-- `CLEAR_DATABASE=true` (drops and recreates schema)
-
-**Services**:
-
-```yaml
-sqlserver           # SQL Server 2022 (port 1433)
-database.migrations # DbUp migrations
-database.seed      # Seed initial data
-api.core           # Web API (ports 8080, 8081)
-```
-
-**Start Development Environment**:
-
-```bash
-docker compose -f docker-compose.dev.yaml up -d
-```
-
-**Access**:
-
-- API Swagger: http://localhost:8080/swagger
-- Health Check: http://localhost:8080/health
-- SQL Server: localhost:1433 (sa credentials from .env.dev)
-
-**Stop Environment**:
-
-```bash
-# Stop services (keep volumes)
-docker compose -f docker-compose.dev.yaml down
-
-# Stop and remove volumes (fresh start)
-docker compose -f docker-compose.dev.yaml down -v
-```
-
-### 2. Testing (`docker-compose.test.yaml`)
-
-**Purpose**: Automated CI/CD testing in isolated environment
-
-**Features**:
-
-- Fresh database each run
-- All test suites execute in parallel
-- Test results exported to `./test-results/`
-- Containers auto-exit after completion
-- Fully isolated testnet network
-
-**Services**:
-
-```yaml
-sqlserver           # Test database
-database.migrations # Fresh schema
-database.seed      # Test data
-api.specs          # Reqnroll BDD tests
-repository.tests   # Repository unit tests
-service.auth.tests # Service unit tests
-```
-
-**Run Tests**:
-
-```bash
-# Run all tests
-docker compose -f docker-compose.test.yaml up --abort-on-container-exit
-
-# View results
-ls -la test-results/
-cat test-results/api-specs/results.trx
-cat test-results/repository-tests/results.trx
-cat test-results/service-auth-tests/results.trx
-
-# Clean up
-docker compose -f docker-compose.test.yaml down -v
-```
-
-### 3. Production (`docker-compose.prod.yaml`)
-
-**Purpose**: Production-ready deployment
-
-**Features**:
-
-- Production logging levels
-- No database clearing
-- Optimized build configurations
-- Health checks enabled
-- Restart policies (unless-stopped)
-- Security hardening
-
-**Services**:
-
-```yaml
-sqlserver          # Production SQL Server
-database.migrations # Schema updates only
-api.core          # Production API
-```
-
-**Deploy Production**:
-
-```bash
-docker compose -f docker-compose.prod.yaml up -d
-```
-
-## Service Dependencies
-
-Docker Compose manages startup order using health checks:
-
-```mermaid
-sqlserver (health check)
-    ↓
-database.migrations (completes successfully)
-    ↓
-database.seed (completes successfully)
-    ↓
-api.core / tests (start when ready)
-```
-
-**Health Check Example** (SQL Server):
-
-```yaml
-healthcheck:
-  test: ['CMD-SHELL', "sqlcmd -S localhost -U sa -P '${DB_PASSWORD}' -C -Q 'SELECT 1'"]
-  interval: 10s
-  timeout: 5s
-  retries: 12
-  start_period: 30s
-```
-
-**Dependency Configuration**:
-
-```yaml
-api.core:
-  depends_on:
-    database.seed:
-      condition: service_completed_successfully
-```
-
-## Volumes
-
-### Persistent Volumes
-
-**Development**:
-
-- `sqlserverdata-dev` - Database files persist between restarts
-- `nuget-cache-dev` - NuGet package cache (speeds up builds)
-
-**Testing**:
-
-- `sqlserverdata-test` - Temporary, typically removed after tests
-
-**Production**:
-
-- `sqlserverdata-prod` - Production database files
-- `nuget-cache-prod` - Production NuGet cache
-
-### Mounted Volumes
-
-**Test Results**:
-
-```yaml
-volumes:
-  - ./test-results:/app/test-results
-```
-
-Test results are written to host filesystem for CI/CD integration.
-
-**Code Volumes** (development only):
-
-```yaml
-volumes:
-  - ./src:/app/src # Hot reload for development
-```
-
-## Networks
-
-Each environment uses isolated bridge networks:
-
-- `devnet` - Development network
-- `testnet` - Testing network (fully isolated)
-- `prodnet` - Production network
-
-## Environment Variables
-
-All containers are configured via environment variables from `.env` files:
-
-```yaml
-env_file: '.env.dev' # or .env.test, .env.prod
-
-environment:
-  ASPNETCORE_ENVIRONMENT: 'Development'
-  DOTNET_RUNNING_IN_CONTAINER: 'true'
-  DB_SERVER: '${DB_SERVER}'
-  DB_NAME: '${DB_NAME}'
-  DB_USER: '${DB_USER}'
-  DB_PASSWORD: '${DB_PASSWORD}'
-  JWT_SECRET: '${JWT_SECRET}'
-```
-
-For complete list, see [Environment Variables](environment-variables.md).
-
-## Common Commands
-
-### View Services
-
-```bash
-# Running services
-docker compose -f docker-compose.dev.yaml ps
-
-# All containers (including stopped)
-docker ps -a
-```
-
-### View Logs
-
-```bash
-# All services
-docker compose -f docker-compose.dev.yaml logs -f
-
-# Specific service
-docker compose -f docker-compose.dev.yaml logs -f api.core
-
-# Last 100 lines
-docker compose -f docker-compose.dev.yaml logs --tail=100 api.core
-```
-
-### Execute Commands in Container
-
-```bash
-# Interactive shell
-docker exec -it dev-env-api-core bash
-
-# Run command
-docker exec dev-env-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'password' -C
-```
-
-### Restart Services
-
-```bash
-# Restart all services
-docker compose -f docker-compose.dev.yaml restart
-
-# Restart specific service
-docker compose -f docker-compose.dev.yaml restart api.core
-
-# Rebuild and restart
-docker compose -f docker-compose.dev.yaml up -d --build api.core
-```
-
-### Build Images
-
-```bash
-# Build all images
-docker compose -f docker-compose.dev.yaml build
-
-# Build specific service
-docker compose -f docker-compose.dev.yaml build api.core
-
-# Build without cache
-docker compose -f docker-compose.dev.yaml build --no-cache
-```
-
-### Clean Up
-
-```bash
-# Stop and remove containers
-docker compose -f docker-compose.dev.yaml down
-
-# Remove containers and volumes
-docker compose -f docker-compose.dev.yaml down -v
-
-# Remove containers, volumes, and images
-docker compose -f docker-compose.dev.yaml down -v --rmi all
-
-# System-wide cleanup
-docker system prune -af --volumes
-```
-
-## Dockerfile Structure
-
-### Multi-Stage Build
-
-```dockerfile
-# Stage 1: Build
-FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
-WORKDIR /src
-COPY ["Project/Project.csproj", "Project/"]
-RUN dotnet restore
-COPY . .
-RUN dotnet build -c Release
-
-# Stage 2: Runtime
-FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final
-WORKDIR /app
-COPY --from=build /app/build .
-ENTRYPOINT ["dotnet", "Project.dll"]
-```
-
-## Additional Resources
-
-- [Docker Compose Documentation](https://docs.docker.com/compose/)
-- [.NET Docker Images](https://hub.docker.com/_/microsoft-dotnet)
-- [SQL Server Docker Images](https://hub.docker.com/_/microsoft-mssql-server)

docs/environment-variables.md

@@ -1,304 +0,0 @@
-# Environment Variables
-
-This document covers the active environment variables used by the current Biergarten
-stack.
-
-## Overview
-
-The application uses environment variables for:
-
-- **.NET API backend** - database connections, token secrets, runtime settings
-- **React Router website** - API base URL and session signing
-- **Docker containers** - environment-specific orchestration
-
-## Configuration Patterns
-
-### Backend (.NET API)
-
-Direct environment variable access via `Environment.GetEnvironmentVariable()`.
-
-### Frontend (`src/Website`)
-
-The active website reads runtime values from the server environment for its auth and API
-integration.
-
-### Docker
-
-Environment-specific `.env` files loaded via `env_file:` in docker-compose.yaml:
-
-- `.env.dev` - Development
-- `.env.test` - Testing
-- `.env.prod` - Production
-
-## Backend Variables (.NET API)
-
-### Database Connection
-
-**Option 1: Component-Based (Recommended for Docker)**
-
-Build connection string from individual components:
-
-```bash
-DB_SERVER=sqlserver,1433          # SQL Server host and port
-DB_NAME=Biergarten                # Database name
-DB_USER=sa                        # SQL Server username
-DB_PASSWORD=YourStrong!Passw0rd   # SQL Server password
-DB_TRUST_SERVER_CERTIFICATE=True  # Optional, defaults to True
-```
-
-**Option 2: Full Connection String (Local Development)**
-
-Provide complete connection string:
-
-```bash
-DB_CONNECTION_STRING="Server=localhost,1433;Database=Biergarten;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;"
-```
-
-**Priority**: `DB_CONNECTION_STRING` is checked first. If not found, connection string is
-built from components.
-
-**Implementation**: See `DefaultSqlConnectionFactory.cs`
-
-### JWT Authentication Secrets (Backend)
-
-The backend uses separate secrets for different token types to enable independent key rotation and validation isolation.
-
-```bash
-# Access token secret (1-hour tokens)
-ACCESS_TOKEN_SECRET=<generated-secret>              # Signs short-lived access tokens
-
-# Refresh token secret (21-day tokens)
-REFRESH_TOKEN_SECRET=<generated-secret>             # Signs long-lived refresh tokens
-
-# Confirmation token secret (30-minute tokens)
-CONFIRMATION_TOKEN_SECRET=<generated-secret>        # Signs email confirmation tokens
-
-# Website base URL (used in confirmation emails)
-WEBSITE_BASE_URL=https://thebiergarten.app          # Base URL for the website
-```
-
-**Security Requirements**:
-
-- Each secret should be minimum 32 characters
-- Recommend 127+ characters for production
-- Generate using cryptographically secure random functions
-- Never reuse secrets across token types or environments
-- Rotate secrets periodically in production
-
-**Generate Secrets**:
-
-```bash
-# macOS/Linux - Generate 127-character base64 secret
-openssl rand -base64 127
-
-# Windows PowerShell
-[Convert]::ToBase64String((1..127 | %{Get-Random -Max 256}))
-```
-
-**Token Expiration**:
-
-- **Access tokens**: 1 hour
-- **Refresh tokens**: 21 days
-- **Confirmation tokens**: 30 minutes
-
-(Defined in `TokenServiceExpirationHours` class)
-
-**JWT Implementation**:
-
-- **Algorithm**: HS256 (HMAC-SHA256)
-- **Handler**: Microsoft.IdentityModel.JsonWebTokens.JsonWebTokenHandler
-- **Validation**: Token signature, expiration, and malformed token checks
-
-### Migration Control
-
-```bash
-CLEAR_DATABASE=true
-```
-
-- **Required**: No
-- **Default**: false
-- **Effect**: If "true", drops and recreates database during migrations
-- **Usage**: Development and testing environments ONLY
-- **Warning**: NEVER use in production
-
-### ASP.NET Core Configuration
-
-```bash
-ASPNETCORE_ENVIRONMENT=Development    # Development, Production, Staging
-ASPNETCORE_URLS=http://0.0.0.0:8080  # Binding address and port
-DOTNET_RUNNING_IN_CONTAINER=true     # Flag for container execution
-```
-
-## Frontend Variables (`src/Website`)
-
-The active website does not use the old Next.js/Prisma environment model. Its core runtime
-variables are:
-
-```bash
-API_BASE_URL=http://localhost:8080       # Base URL for the .NET API
-SESSION_SECRET=<generated-secret>        # Cookie session signing secret
-NODE_ENV=development                     # Standard Node runtime mode
-```
-
-### Frontend Variable Details
-
-#### `API_BASE_URL`
-
-- **Required**: Yes for local development
-- **Default in code**: `http://localhost:8080`
-- **Used by**: `src/Website/app/lib/auth.server.ts`
-- **Purpose**: Routes website auth actions to the .NET API
-
-#### `SESSION_SECRET`
-
-- **Required**: Strongly recommended in all environments
-- **Default in local code path**: `dev-secret-change-me`
-- **Used by**: React Router cookie session storage in `auth.server.ts`
-- **Purpose**: Signs and validates the website session cookie
-
-#### `NODE_ENV`
-
-- **Required**: No
-- **Typical values**: `development`, `production`, `test`
-- **Purpose**: Controls secure cookie behavior and runtime mode
-
-### Admin Account (Seeding)
-
-```bash
-ADMIN_PASSWORD=SecureAdminPassword123!   # Initial admin password for seeding
-```
-
-- **Required**: No (only needed for seeding)
-- **Purpose**: Sets admin account password during database seeding
-- **Security**: Use strong password, change immediately in production
-
-## Docker-Specific Variables
-
-### SQL Server Container
-
-```bash
-SA_PASSWORD=YourStrong!Passw0rd   # SQL Server SA password
-ACCEPT_EULA=Y                     # Accept SQL Server EULA (required)
-MSSQL_PID=Express                 # SQL Server edition (Express, Developer, Enterprise)
-```
-
-**Password Requirements**:
-
-- Minimum 8 characters
-- Uppercase, lowercase, digits, and special characters
-- Maps to `DB_PASSWORD` for application containers
-
-## Environment File Structure
-
-### Backend/Docker (Root Directory)
-
-```
-.env.example          # Template (tracked in Git)
-.env.dev             # Development config (gitignored)
-.env.test            # Testing config (gitignored)
-.env.prod            # Production config (gitignored)
-```
-
-**Setup**:
-
-```bash
-cp .env.example .env.dev
-# Edit .env.dev with your values
-```
-
-## Legacy Frontend Variables
-
-Variables for the archived Next.js frontend (`src/Website-v1`) have been removed from this
-active reference. See [archive/legacy-website-v1.md](archive/legacy-website-v1.md) if you
-need the legacy Prisma, Cloudinary, Mapbox, or SparkPost notes.
-
-**Docker Compose Mapping**:
-
-- `docker-compose.dev.yaml` → `.env.dev`
-- `docker-compose.test.yaml` → `.env.test`
-- `docker-compose.prod.yaml` → `.env.prod`
-
-## Variable Reference Table
-
-| Variable                      | Backend | Frontend | Docker | Required | Notes                      |
-| ----------------------------- | :-----: | :------: | :----: | :------: | -------------------------- |
-| `DB_SERVER`                   |    ✓    |          |   ✓    |  Yes\*   | SQL Server address         |
-| `DB_NAME`                     |    ✓    |          |   ✓    |  Yes\*   | Database name              |
-| `DB_USER`                     |    ✓    |          |   ✓    |  Yes\*   | SQL username               |
-| `DB_PASSWORD`                 |    ✓    |          |   ✓    |  Yes\*   | SQL password               |
-| `DB_CONNECTION_STRING`        |    ✓    |          |        |  Yes\*   | Alternative to components  |
-| `DB_TRUST_SERVER_CERTIFICATE` |    ✓    |          |   ✓    |    No    | Defaults to `True`         |
-| `ACCESS_TOKEN_SECRET`         |    ✓    |          |   ✓    |   Yes    | Access token signing       |
-| `REFRESH_TOKEN_SECRET`        |    ✓    |          |   ✓    |   Yes    | Refresh token signing      |
-| `CONFIRMATION_TOKEN_SECRET`   |    ✓    |          |   ✓    |   Yes    | Confirmation token signing |
-| `WEBSITE_BASE_URL`            |    ✓    |          |        |   Yes    | Website URL for emails     |
-| `API_BASE_URL`                |         |    ✓     |        |   Yes    | Website-to-API base URL    |
-| `SESSION_SECRET`              |         |    ✓     |        |   Yes    | Website session signing    |
-| `NODE_ENV`                    |         |    ✓     |        |    No    | Runtime mode               |
-| `CLEAR_DATABASE`              |    ✓    |          |   ✓    |    No    | Dev/test reset flag        |
-| `ASPNETCORE_ENVIRONMENT`      |    ✓    |          |   ✓    |   Yes    | ASP.NET environment        |
-| `ASPNETCORE_URLS`             |    ✓    |          |   ✓    |   Yes    | API binding address        |
-| `SA_PASSWORD`                 |         |          |   ✓    |   Yes    | SQL Server container       |
-| `ACCEPT_EULA`                 |         |          |   ✓    |   Yes    | SQL Server EULA            |
-| `MSSQL_PID`                   |         |          |   ✓    |    No    | SQL Server edition         |
-| `DOTNET_RUNNING_IN_CONTAINER` |    ✓    |          |   ✓    |    No    | Container flag             |
-
-\* Either `DB_CONNECTION_STRING` OR the component variables (`DB_SERVER`, `DB_NAME`,
-`DB_USER`, `DB_PASSWORD`) must be provided.
-
-## Validation
-
-### Backend Validation
-
-Variables are validated at startup:
-
-- Missing required variables cause application to fail
-- JWT_SECRET length is enforced (min 32 chars)
-- Connection string format is validated
-
-### Frontend Validation
-
-The active website relies on runtime defaults for local development and the surrounding
-server environment in deployed environments.
-
-- `API_BASE_URL` defaults to `http://localhost:8080`
-- `SESSION_SECRET` falls back to a development-only local secret
-- `NODE_ENV` controls secure cookie behavior
-
-## Example Configuration Files
-
-### `.env.dev` (Backend/Docker)
-
-```bash
-# Database
-DB_SERVER=sqlserver,1433
-DB_NAME=Biergarten
-DB_USER=sa
-DB_PASSWORD=Dev_Password_123!
-
-# JWT Authentication Secrets
-ACCESS_TOKEN_SECRET=<generated-with-openssl>
-REFRESH_TOKEN_SECRET=<generated-with-openssl>
-CONFIRMATION_TOKEN_SECRET=<generated-with-openssl>
-WEBSITE_BASE_URL=http://localhost:3000
-
-# Migration
-CLEAR_DATABASE=true
-
-# ASP.NET Core
-ASPNETCORE_ENVIRONMENT=Development
-ASPNETCORE_URLS=http://0.0.0.0:8080
-
-# SQL Server Container
-SA_PASSWORD=Dev_Password_123!
-ACCEPT_EULA=Y
-MSSQL_PID=Express
-```
-
-### Frontend local runtime example
-
-```bash
-API_BASE_URL=http://localhost:8080
-SESSION_SECRET=<generated-with-openssl>
-NODE_ENV=development
-```

docs/getting-started.md

@@ -1,138 +0,0 @@
-# Getting Started
-
-This guide covers local setup for the current Biergarten stack: the .NET backend in
-`src/Core` and the active React Router frontend in `src/Website`.
-
-## Prerequisites
-
-- **.NET SDK 10+**
-- **Node.js 18+**
-- **Docker Desktop** or equivalent Docker Engine setup
-- **Java 8+** if you want to regenerate PlantUML diagrams
-
-## Recommended Path: Docker for Backend, Node for Frontend
-
-### 1. Clone the Repository
-
-```bash
-git clone <repository-url>
-cd the-biergarten-app
-```
-
-### 2. Configure Backend Environment Variables
-
-```bash
-cp .env.example .env.dev
-```
-
-At minimum, ensure `.env.dev` includes valid database and token values:
-
-```bash
-DB_SERVER=sqlserver,1433
-DB_NAME=Biergarten
-DB_USER=sa
-DB_PASSWORD=YourStrong!Passw0rd
-ACCESS_TOKEN_SECRET=<generated>
-REFRESH_TOKEN_SECRET=<generated>
-CONFIRMATION_TOKEN_SECRET=<generated>
-WEBSITE_BASE_URL=http://localhost:3000
-```
-
-See [Environment Variables](environment-variables.md) for the full list.
-
-### 3. Start the Backend Stack
-
-```bash
-docker compose -f docker-compose.dev.yaml up -d
-```
-
-This starts SQL Server, migrations, seeding, and the API.
-
-Available endpoints:
-
-- API Swagger: http://localhost:8080/swagger
-- Health Check: http://localhost:8080/health
-
-### 4. Start the Active Frontend
-
-```bash
-cd src/Website
-npm install
-API_BASE_URL=http://localhost:8080 SESSION_SECRET=dev-secret-change-me npm run dev
-```
-
-The website will be available at the local address printed by React Router dev.
-
-Required frontend runtime variables for local work:
-
-- `API_BASE_URL` - Base URL for the .NET API
-- `SESSION_SECRET` - Cookie session signing secret for the website server
-
-### 5. Optional: Run Storybook
-
-```bash
-cd src/Website
-npm run storybook
-```
-
-Storybook runs at http://localhost:6006 by default.
-
-## Useful Commands
-
-### Backend
-
-```bash
-docker compose -f docker-compose.dev.yaml logs -f
-docker compose -f docker-compose.dev.yaml down
-docker compose -f docker-compose.dev.yaml down -v
-```
-
-### Frontend
-
-```bash
-cd src/Website
-npm run lint
-npm run typecheck
-npm run format:check
-npm run test:storybook
-npm run test:storybook:playwright
-```
-
-## Manual Backend Setup
-
-If you do not want to use Docker, you can run the backend locally.
-
-### 1. Set Environment Variables
-
-```bash
-export DB_CONNECTION_STRING="Server=localhost,1433;Database=Biergarten;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;"
-export ACCESS_TOKEN_SECRET="<generated>"
-export REFRESH_TOKEN_SECRET="<generated>"
-export CONFIRMATION_TOKEN_SECRET="<generated>"
-export WEBSITE_BASE_URL="http://localhost:3000"
-```
-
-### 2. Run Migrations and Seed
-
-```bash
-cd src/Core
-dotnet run --project Database/Database.Migrations/Database.Migrations.csproj
-dotnet run --project Database/Database.Seed/Database.Seed.csproj
-```
-
-### 3. Start the API
-
-```bash
-dotnet run --project API/API.Core/API.Core.csproj
-```
-
-## Legacy Frontend Note
-
-The previous Next.js frontend now lives in `src/Website-v1` and is not the active website.
-Legacy setup details have been moved to [docs/archive/legacy-website-v1.md](archive/legacy-website-v1.md).
-
-## Next Steps
-
-- Review [Architecture](architecture.md)
-- Run backend and frontend checks from [Testing](testing.md)
-- Use [Docker Guide](docker.md) for container troubleshooting

docs/index.md

@@ -0,0 +1,33 @@
+---
+title: The Biergarten App
+last-updated: 2026-08-31
+tags:
+  - overview
+  - index
+---
+
+Welcome to the documentation for The Biergarten App.
+
+## Documentation Sections
+
+- **[Architecture](web/architecture.md)** — System design and components
+- **[Website](web/getting-started.md)** — Backend and frontend documentation
+- **[Pipeline](pipeline/README.md)** — Data generation pipeline
+
+## AI Disclosure
+
+Parts of this documentation are drafted and maintained with AI assistance
+(Claude, Sonnet or Opus, via Claude Code), including prose (architecture
+notes, guides) and diagrams (the Mermaid sources under `diagrams/`).
+AI-authored changes are reviewed by a maintainer before merging, same as any
+other contribution.
+
+Staleness checks are partly automated too, to guard against doc-rot: the
+repo's `doc-drift-web` and `doc-drift-pipeline` Claude Code skills
+(`.claude/skills/`) diff recent code changes against these docs and flag
+claims that may need updating.
+
+This is separate from the pipeline's own use of AI to *generate seed data*
+(brewery names, descriptions, user profiles) — see
+[ETHICS-AND-KNOWN-ISSUES.md](pipeline/ETHICS-AND-KNOWN-ISSUES.md) for that
+disclosure.

docs/makefile

@@ -0,0 +1,43 @@
+# Makefile for rendering all Mermaid (.mmd) diagrams to SVG,
+# preserving the source directory structure under OUT_ROOT.
+#
+# Usage:
+#   make            # render all diagrams
+#   make clean      # remove all rendered output
+#   make FORMAT=png # render as PNG instead of SVG
+#   make FORMAT=pdf # render as PDF instead of SVG
+#
+# Requires: @mermaid-js/mermaid-cli (mmdc) on PATH
+#   npm install -g @mermaid-js/mermaid-cli
+
+SRC_ROOT  := .
+OUT_ROOT  := rendered-diagrams
+FORMAT    := svg
+
+# Optional: point to a shared Mermaid config/theme file if you have one.
+# CONFIG    := ./mermaidconfig.json
+# CONFIG_FLAG := -c $(CONFIG)
+CONFIG_FLAG :=
+
+# Find every .mmd file under SRC_ROOT, excluding the output directory itself.
+SRC_FILES := $(shell find $(SRC_ROOT) -type f -name "*.mmd" -not -path "./$(OUT_ROOT)/*")
+
+# Map each source file to its corresponding output file, preserving subdirectories.
+OUT_FILES := $(patsubst $(SRC_ROOT)/%.mmd,$(OUT_ROOT)/%.$(FORMAT),$(SRC_FILES))
+
+.PHONY: all clean list
+
+all: $(OUT_FILES)
+
+# Pattern rule: build any output file from its matching .mmd source file,
+# creating the destination subdirectory as needed.
+$(OUT_ROOT)/%.$(FORMAT): $(SRC_ROOT)/%.mmd
+	@mkdir -p $(dir $@)
+	mmdc $(CONFIG_FLAG) -i $< -o $@
+
+clean:
+	rm -rf $(OUT_ROOT)
+
+# Debug helper: print which source files were discovered.
+list:
+	@echo "$(SRC_FILES)" | tr ' ' '\n'

docs/pipeline/ETHICS-AND-KNOWN-ISSUES.md

@@ -0,0 +1,392 @@
+---
+title: Pipeline ethics, bias, and known issues
+last-updated: 2026-08-31
+tags:
+  - pipeline
+  - ethics
+  - bias
+  - known-issues
+  - ai-generated
+---
+
+This document covers the ethical context of the Biergarten Pipeline's output,
+the model's biases, and known issues including hallucinated brewing science and
+low-resource language failures.
+
+> All testing described below used `google_gemma-4-E4B-it-Q6_K.gguf`.
+
+## Table of contents
+
+- [What this dataset is](#what-this-dataset-is)
+- [What this dataset is not](#what-this-dataset-is-not)
+- [Model bias and language quality](#model-bias-and-language-quality)
+- [Western and Eurocentric lens](#western-and-eurocentric-lens)
+- [Wikipedia enrichment](#wikipedia-enrichment)
+- [Names-by-country dataset](#names-by-country-dataset)
+- [The "avoid AI phrases" prompt instruction](#the-avoid-ai-phrases-prompt-instruction)
+- [Known issues](#known-issues)
+  - [Hallucinated brewing techniques](#hallucinated-brewing-techniques)
+  - [Low-resource language hallucination](#low-resource-language-hallucination)
+  - [Synthetic coordinates](#synthetic-coordinates)
+
+---
+
+## What this dataset is
+
+This is AI-generated fixture data for a proof-of-concept version of The
+Biergarten App. Anyone who interacts with an application seeded from this
+pipeline must be told upfront that the content is AI-generated.
+
+---
+
+## What this dataset is not
+
+The pipeline is not intended to produce accurate brewing science, faithful
+cultural representation, or reliable local-language text. Hallucinations such as
+invented fermentation techniques, or incoherent local-language prose, are
+expected, observed, and partially documented in [Known issues](#known-issues)
+below.
+
+Human control sits at the context layer (that is, prompt design, Wikipedia
+enrichment). Statistical output shapes in future pipeline stages (check-in
+distributions, rating skews, activity profiles) will be handled the same way.
+
+**Treat this data as an exercise in prompt engineering and model behaviour, not
+as a source of truth for brewing techniques or cultural representation.**
+
+**Natural language processing is a powerful tool for data analysis and
+generation, but its output should be treated with scrutiny. Human language is
+not simply data points to be analyzed: it carries cultural and human meaning
+that artificial intelligence cannot capture.**
+
+---
+
+## Model bias and language quality
+
+The underlying model's training biases surface within this pipeline. Output
+quality tracks with how well a language is represented in the training corpus:
+standard French (`fr-FR`) produces coherent text; regional variants like `fr-CD`
+and `fr-CI` are noticeably weaker; low-resource languages like Welsh, Māori, and
+Sicilian produce output that is syntactically plausible but often semantically
+broken.
+
+This is a property of the training distribution, not something that can be
+mitigated through prompt design. This is a well-documented characteristic of
+large language models trained predominantly on English-language
+material.[^llm-bias]
+
+Mitigations are documented in
+[Known issues: Low-resource language hallucination](#low-resource-language-hallucination).
+
+### Western and Eurocentric lens
+
+The model's training data skews heavily Western and North American. When
+generating brewery descriptions for Kinshasa, Abidjan, or Osaka, for example, it
+defaults to framing and cultural reference points drawn from that perspective
+rather than from the lived context of those cities. Wikipedia enrichment grounds
+some generation in city-specific material, but it does not eliminate the skew.
+
+**Output should be read with an understanding of this bias.**
+
+---
+
+## Wikipedia enrichment
+
+City and beer context is fetched from the Wikipedia API. Wikipedia text is
+co-licensed under the **Creative Commons Attribution-ShareAlike 4.0
+International License (CC BY-SA 4.0)**[^cc-sa] and the **GNU Free Documentation
+License (GFDL)**.[^wp-license]
+
+Wikipedia's own accuracy limitations and editorial biases can propagate into
+generated descriptions.
+
+---
+
+## Names-by-country dataset
+
+`tooling/pipeline/forenames-by-country.json` and `surnames-by-country.json`
+(used to sample a `Name` per ISO 3166-1 country code for user generation) are
+vendored verbatim, unmodified, from
+[sigpwned/popular-names-by-country-dataset](https://github.com/sigpwned/popular-names-by-country-dataset)
+(the `common-forenames-by-country.json` / `common-surnames-by-country.json`
+release assets), released under **CC0** (public domain). That dataset's own
+forename/surname lists are pulled from Wikipedia's "Lists of most common
+surnames" and "List of most popular given names" as of the week of 2023-07-08;
+see that project's README for full provenance. Names are not LLM-generated; this
+is curated fixture data per ROADMAP.md §2. Per-forename gender from the source
+data is preserved through to the sampled `Name` (rather than discarded during
+loading) so it's available for gender-aware persona/bio generation later.
+
+The full multinational dataset is kept as-is (106 countries for forenames, 75
+for surnames) rather than trimmed to `locations.json`'s current country list, so
+it doesn't need re-sourcing if more countries are added later. `SampleName()` (a
+free helper in `generate_users.cc`) returns no result for a country present in
+neither file; of the countries in `locations.json`, that's currently `KE`, `SE`,
+`SG`, `TH`, `VN`, and `ZA`; `GenerateUsers` skips cities in those countries the
+same way brewery generation skips cities whose enrichment lookup fails.
+
+---
+
+## The "avoid AI phrases" prompt instruction
+
+The system prompt instructs the model to avoid common AI-generated phrasing
+patterns. This is a prompt engineering experiment:
+
+> How far can a model be pushed against its own stylistic defaults?
+
+This is not an attempt to disguise the content as human-written. All downstream
+consumers are informed of the AI-generated origin before engagement.
+
+---
+
+## Known issues
+
+### Hallucinated brewing techniques
+
+When forced by the system prompt to generate a "highly specialized technical
+brewing detail," the model frequently hallucinates fermentation science and
+brewing chemistry. While the resulting text sounds confident, it is nonsensical
+to a reader with brewing or scientific expertise.
+
+Small-parameter models such as Gemma 4 E4B cannot reliably satisfy prompts
+calling for specialist brewing detail. This is consistent with the **CHOKE**
+failure mode (Certain Hallucinations Overriding Known Evidence) [^llm-choke]
+where a specific-sounding prompt causes a model to produce confident, coherent,
+and factually wrong output.
+
+#### Example — Osaka, produced using Gemma 4 E4B
+
+```log
+[2026-04-21 15:04:40.258] [info] 11. city="Osaka" country="Japan" state="Osaka" iso3166_2=JP-27 lat=34.6937 lon=135.5023
+[2026-04-21 15:04:40.258] [info]    brewery_name_en="Kani-no-Kuni Brewing"
+[2026-04-21 15:04:40.258] [info]    brewery_description_en="The humid scent of takoyaki and savory grilled squid always settles over the neighborhood early in the morning, mingling strangely with the metallic tang of spent grain outside our drying shed. We decided to build this place here because Osaka is a city that never pauses, a place built around the constant exchange of goods and tastes, and that is what we want our beer to reflect. Many people here are accustomed to the dependable, clean taste of the major pale lagers, but we are interested in exploring the deeper, more textured expressions of fermentation. Our base malts are specifically crafted by incorporating strains of local rice, like Yamada Nishiki, which we malt and use not for sake, but for its complex, buttery flavor profile during the mash. This combination, followed by a slow, anaerobic aging process, gives our beers a profound, satisfying depth that stands apart from the hurried mass-market style. The heavy, deep red brick of the original warehouse wall has absorbed decades of Kansai humidity and seasonal rains, creating a patina that tells the exact story of this district's tireless movement. We chose this structure not for its charm, but for its resilience and the sheer density of the local history held within its mortar. Our goal is simply to serve a drink worthy of this powerful trading city. If you are looking for a quiet spot away from the main thoroughfare, look for us just off the side street near Shinsekai."
+[2026-04-21 15:04:40.258] [info]    brewery_name_local="カニの国ブルワリー"
+[2026-04-21 15:04:40.258] [info]    brewery_description_local="早朝の、たこ焼きや香ばしいイカ焼きの湿った匂いは、いつも乾燥小屋の外にある使用済み麦芽の金属的な匂いと奇妙に混ざり合って近隣に漂います。私たちはこの場所に店を構えることを決めたのです。なぜなら、大阪は決して止まることのない都市であり、商品と味が絶え間なく交換されることで築かれた場所だからです。地元の多くの方々は、信頼できる大規模な淡麗ラガーの味が習慣になっていますが、私たちは発酵の、より深く、より複雑な表現を探求することに関心があります。私たちのベースモルトは、山田錦のような地元の米の品種を意図的に組み込んで作られています。この米を酒ではなく、麦芽として、仕込みの最中にその複雑でバターのような風味を引き出すために使用しています。この組み合わせを、ゆっくりとした嫌気的な熟成プロセスに続けることで、私たちのビールは、慌ただしい市場のスタイルとは一線を画す、深みのある、満足感のある複雑さを持っています。オリジナルの倉庫の重く深紅のレンガ壁は、関西特有の湿気と季節の雨を何十年も吸収し、この地区の絶え間ない動きの正確な物語を語るような古色を帯びています。私たちはこの構造物を、その魅力のためではなく、その回復力とモルタルに込められた地域の歴史の密度ゆえに選びました。私たちの目標は、ただこの力強い交易都市に値する飲み物を提供することだけです。もしメインの通りから離れた静かな場所をお探しなら、新世界近くの脇道にある私たちを探してください。"
+```
+
+A review of the following text for brewing techniques reveals three
+inaccuracies. No comments are made on the local-language version, since its
+reviewer does not read Japanese:
+
+#### 1. "Buttery flavours" framed as a desirable malt-derived flavour
+
+**Incorrect.**
+
+Diacetyl is a fermentation byproduct of yeast metabolism, not a malt-derived
+compound.[^diacetyl-source] Diacetyl produces a buttery or butterscotch
+off-flavour and is carefully managed in many beer styles, in particular lighter
+beers, through a process called a _diacetyl rest_. In this process, fermentation
+temperature is briefly raised to allow yeast to reabsorb the compound before
+packaging.[^diacetyl-rest]
+
+The Oxford Companion to Beer claims that, while low levels are tolerable in some
+ales and stouts, diacetyl is considered undesirable at any perceptible
+concentration when it results from bacterial contamination or stressed
+fermentation.[^oxford-beer]
+
+#### 2. Yamada Nishiki sake rice described as a self-saccharifying base malt
+
+**Incorrect.**
+
+Yamada Nishiki (_山田錦_) is a short-grain Japanese rice bred specifically for
+sake production.[^yn-wiki] Its value lies in its large starchy core
+(_shinpaku_), low protein content, and amenability to _koji_ mold penetration
+during saccharification.[^yn-sakestreet] Sake brewing does not use the grain's
+own enzymatic activity for saccharification — it relies on _Aspergillus oryzae_
+(koji mold) grown on a portion of the steamed rice to convert starches to
+fermentable sugars.[^yn-sakeonline]
+
+#### 3. "Anaerobic aging" presented as a differentiating technique
+
+**Misleading**
+
+Anaerobic conditions during packaging and aging are not a differentiating
+technique. Anaerobic conditions are the standard baseline for all commercial
+beer production. Breweries exclude oxygen as a top priority for packaging and
+shelf stability; published research in _Microbiology Spectrum_ confirms that
+packaged beer constitutes an anaerobic environment by definition.[^anaerobic]
+Professional packaging lines use CO_2 purges and closed transfers specifically
+to maintain this state.[^packaging] Framing anaerobic aging as a distinctive
+practice is misleading and suggests hallucinated output.
+
+### Low-resource language hallucination
+
+The generation pipeline passes local language codes to the model to retrieve a
+translated `description_local`. Output quality is reliable for high-resource
+languages such as French, though it may struggle with regional variants and
+idiomatic phrasing.
+
+```json
+[
+  {
+    "city": "Kinshasa",
+    "state_province": "Kinshasa",
+    "iso3166_2": "CD-KN",
+    "country": "Democratic Republic of the Congo",
+    "iso3166_1": "CD",
+    "latitude": -4.4419,
+    "longitude": 15.2663,
+    "local_languages": ["fr-CD", "ln"]
+  },
+  {
+    "city": "Paris",
+    "state_province": "Île-de-France",
+    "iso3166_2": "FR-IDF",
+    "country": "France",
+    "iso3166_1": "FR",
+    "latitude": 48.8566,
+    "longitude": 2.3522,
+    "local_languages": ["fr-FR"]
+  },
+  {
+    "city": "Abidjan",
+    "state_province": "Abidjan",
+    "iso3166_2": "CI-AB",
+    "country": "Ivory Coast",
+    "iso3166_1": "CI",
+    "latitude": 5.36,
+    "longitude": -4.0083,
+    "local_languages": ["fr-CI"]
+  },
+  {
+    "city": "Montreal",
+    "state_province": "Quebec",
+    "iso3166_2": "CA-QC",
+    "country": "Canada",
+    "iso3166_1": "CA",
+    "latitude": 45.5017,
+    "longitude": -73.5673,
+    "local_languages": ["fr-CA"]
+  },
+  {
+    "city": "Brussels",
+    "state_province": "Brussels-Capital Region",
+    "iso3166_2": "BE-BRU",
+    "country": "Belgium",
+    "iso3166_1": "BE",
+    "latitude": 50.8503,
+    "longitude": 4.3517,
+    "local_languages": ["fr-BE", "nl-BE"]
+  }
+]
+```
+
+When fed into the pipeline, this dataset often causes the model to reason that a
+local variant of French is needed, but it often defaults to a standardized
+dialect of French, without cultural or linguistic nuance.
+
+For languages such as Welsh (Wales), Māori (Aotearoa/New Zealand), or Sicilian
+(Sicily, Italy), the model can generate text that looks syntactically plausible
+but is semantically incoherent. This comes from limited training-data coverage
+rather than prompt engineering.
+
+Output sample: [./french-cities.example](french-cities.example)
+
+#### Proposed mitigations
+
+- **Prevention via allowlist:** introduce a high-resource language allowlist. If
+  a location's code is unlisted, skip `description_local` generation and fall
+  back to English.
+- **Upstream sanitization:** strip known low-resource language codes from the
+  `locations.json` payload before generation.
+- **Downstream flagging:** add a `description_local_confidence` column to the
+  SQLite schema so downstream applications can filter or flag potentially
+  hallucinated text by language tier.
+
+### Synthetic coordinates
+
+Each brewery and user address carries a longitude/latitude pair, sampled
+uniformly at random within a 5 km disc centred on the city's curated
+`latitude`/`longitude` from `locations.json`.
+
+The coordinate pair itself is **plausible by construction**, always falling
+within the city's vicinity, but does not correspond to a real business or
+resident, and should not be treated as accurate geocoding data. This is
+consistent with the rest of the dataset: fixture data for a proof-of-concept,
+not a source of truth.
+
+For brewery addresses specifically (not user addresses, which carry no street
+address at all), `address_line1`/`postal_code` _are_ looked up from a real
+address registry — `NominatimAddressService` reverse-geocodes the synthetic
+coordinate pair against the live OpenStreetMap/Nominatim database, so the street
+address is a genuine nearby address, just not the address of an actual brewery.
+This lookup only happens for non-`--mocked` runs; `--mocked` runs use
+`MockAddressService`'s fixed placeholder address instead, which is not looked up
+from any real registry.
+
+---
+
+## Footnotes
+
+[^llm-choke]:
+    CHOKE (Certain Hallucinations Overriding Known Evidence) is a hallucination
+    failure mode defined by Simhi et al. (2025), in which a model that can
+    consistently answer a question correctly produces a confident, wrong
+    response when the prompt is trivially perturbed. Source: Trust Me, I'm
+    Wrong: LLMs Hallucinate with Certainty Despite Knowing the Answer — Adi
+    Simhi, Itay Itzhak, Fazl Barez, Gabriel Stanovsky, Yonatan Belinkov.
+
+[^llm-bias]:
+    For example, Blasi et al. (2022), "Systematic Inequalities in Language
+    Technology Performance across the World's Languages," _ACL Anthology_. The
+    pattern is consistent with models trained predominantly on English-language
+    web corpora.
+
+[^wp-license]:
+    Source:
+    [Wikipedia:FAQ/Copyright](https://en.wikipedia.org/wiki/Wikipedia:FAQ/Copyright).
+
+[^cc-sa]:
+    Creative Commons CC BY-SA 4.0 deed: "If you remix, transform, or build upon
+    the material, you must distribute your contributions under the same license
+    as the original." Source:
+    [creativecommons.org/licenses/by-sa/4.0](https://creativecommons.org/licenses/by-sa/4.0/deed.en).
+
+[^diacetyl-source]:
+    White Labs confirms that diacetyl is a yeast-derived fermentation byproduct:
+    specifically, a compound produced during amino acid metabolism that leaks
+    out of the yeast cell and oxidises into its characteristic buttery
+    off-flavour. It is generally considered undesirable at any perceived level
+    in most styles, though low levels are tolerated in some English ales and
+    European lagers. Source:
+    [whitelabs.com — Compound Spotlight: Diacetyl](https://www.whitelabs.com/news-update-detail?id=54).
+
+[^diacetyl-rest]:
+    Brewing Science Institute: diacetyl "is produced during the fermentation
+    process, primarily as a byproduct of yeast metabolism… generally considered
+    a flaw in most beer styles." Source:
+    [brewingscience.com — Diacetyl: Understanding Its Role as an Off-Flavor in Beer](https://brewingscience.com/diacetyl-understanding-its-role-as-an-off-flavor-in-beer/).
+
+[^oxford-beer]:
+    Oxford Companion to Beer via _Beer & Brewing_: "At low to moderate levels,
+    diacetyl can be perceived as a positive flavor characteristic in some ales
+    and stouts" but "particularly unwelcome in lager-style beers." Source:
+    [beerandbrewing.com — diacetyl](https://www.beerandbrewing.com/dictionary/48TDqQibPi).
+
+[^yn-wiki]:
+    Wikipedia: "Yamada Nishiki (山田錦) is a short-grain Japanese rice famous
+    for its use in high-quality sake." Source:
+    [en.wikipedia.org/wiki/Yamada_Nishiki](https://en.wikipedia.org/wiki/Yamada_Nishiki).
+
+[^yn-sakestreet]:
+    Sake Street: Yamadanishiki's large _shinpaku_ allows koji mold to penetrate
+    to the centre of the rice grain, making it "particularly suitable for
+    producing good koji." Source:
+    [sakestreet.com — What is Yamadanishiki?](https://sakestreet.com/en/media/what-is-yamadanishiki).
+
+[^yn-sakeonline]:
+    Sake Online: "Steamed rice is added to make koji (rice malt) and yeast
+    starter, which promotes alcohol fermentation." Source:
+    [sakeonline.com.au — Types of Sake Rice: Yamada Nishiki](https://sakeonline.com.au/blogs/news/types-of-sake-rice-yamada-nishiki-and-its-characteristics).
+
+[^anaerobic]:
+    Pai et al. (2022): "Breweries have recognized oxygen exclusion as a top
+    priority for the proper packaging and aging of beer… packaged beer is an
+    anaerobic environment." _Microbiology Spectrum._ Source:
+    [journals.asm.org](https://journals.asm.org/doi/10.1128/spectrum.02656-22).
+
+[^packaging]:
+    Beer Production Processes (oboe.com): Professional packaging lines use
+    double CO_2 pre-evacuation cycles and closed transfers "so the beer moves in
+    a completely anaerobic environment." Source:
+    [oboe.com — Flavor Quality Control](https://oboe.com/learn/beer-production-processes-308lmf/flavor-quality-control-4).

docs/pipeline/README.md

@@ -0,0 +1,475 @@
+---
+title: Biergarten Pipeline — C++ CLI for generating seed data
+last-updated: 2026-09-02
+tags:
+  - pipeline
+  - cpp
+  - llm
+  - seed-data
+  - docker
+---
+
+A C++20 command-line pipeline that samples city records from local JSON,
+enriches each with Wikipedia context, and generates bilingual brewery names and
+descriptions plus locale-grounded user profiles via a local GGUF model or a
+deterministic mock.
+
+> **This pipeline produces AI-generated data.** It is not a source of truth for
+> brewing techniques, cultural representation, or local-language accuracy. See
+> [ETHICS-AND-KNOWN-ISSUES.md](./ETHICS-AND-KNOWN-ISSUES.md) for full
+> documentation of limitations, hallucination patterns, and bias.
+
+---
+
+## Table of contents
+
+- [How it fits the main app](#how-it-fits-the-main-app)
+- [Quick start](#quick-start)
+  - [Build](#build)
+  - [Model](#model)
+  - [Run](#run)
+- [Docker / RunPod](#docker--runpod)
+- [Architecture](#architecture)
+  - [Pipeline Stages](#pipeline-stages)
+  - [Key Components](#key-components)
+  - [Runtime Behaviour](#runtime-behaviour)
+- [Generated output](#generated-output)
+- [Tech stack](#tech-stack)
+- [Tested hardware](#tested-hardware)
+- [Fixture strategy](#fixture-strategy)
+- [Repo layout](#repo-layout)
+- [Code tour](#code-tour)
+- [Next steps](#next-steps)
+
+---
+
+## How it fits the main app
+
+The pipeline is a data ingestion layer. It sits outside the web app runtime and
+produces seed records the app imports at startup or during a dedicated seed
+step.
+
+| Planned app area                 | Pipeline contribution                                                                             |
+| -------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Brewery discovery and management | Sampled city records, localized names, long-form descriptions                                     |
+| Beer reviews and ratings         | Stable brewery fixtures with enough context to anchor review pages                                |
+| Social follow relationships      | Repeatable brewery entities for feeds, follows, and saved lists                                   |
+| Geospatial brewery experiences   | Latitude, longitude, and country-level metadata                                                   |
+| User accounts and profiles       | Locale-grounded names, bios, and an auth-ready email/date-of-birth pair for seeding real accounts |
+
+---
+
+## Quick start
+
+### Build
+
+Requirements: C++20 compiler, CMake 3.31+, OpenSSL, Boost (JSON and
+ProgramOptions). SQLite is fetched from the upstream amalgamation, so no system
+SQLite package is required.
+
+```bash
+cmake -S . -B build
+cmake --build build
+```
+
+CMake automatically detects whether a compatible llama.cpp installation is
+present on the system (`libllama`, `libggml`, `libggml-base`, and `llama.h`
+visible on the default search paths). If found, it links against those libraries
+and skips the FetchContent build. If not found, it fetches and builds llama.cpp
+from source at tag `b9012`. No additional flags are required in either case.
+
+Metal is enabled automatically on Apple Silicon. CUDA or HIP/ROCm is detected
+automatically on Linux when the relevant toolkit is present.
+
+### Model
+
+> Skip this step if you only need `--mocked`.
+
+```bash
+mkdir -p models
+curl -L \
+  -o models/google_gemma-4-E4B-it-Q6_K.gguf \
+  https://huggingface.co/bartowski/google_gemma-4-E4B-it-GGUF/resolve/main/google_gemma-4-E4B-it-Q6_K.gguf?download=true
+```
+
+### Run
+
+Run from `build/` so the copied `locations.json` and `prompts/` are available.
+Each run writes a fresh dated SQLite file such as
+`biergarten_seed_2026-04-19T15-30-45.123456Z.sqlite` into the working directory.
+
+```bash
+./biergarten-pipeline --mocked
+
+./biergarten-pipeline \
+  --model ../models/google_gemma-4-E4B-it-Q6_K.gguf \
+  --prompt-dir prompts \
+  --location-count 25 \
+  --temperature 1.0 --top-p 0.95 --top-k 64 --n-ctx 8192 --seed -1
+```
+
+#### CLI flags
+
+| Flag               | Purpose                                                                                                          |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `--mocked`         | Deterministic mock generator, no model required.                                                                 |
+| `--model, -m`      | Path to a GGUF file. Selects the local Llama.cpp generator.                                                      |
+| `--openai`         | Use the OpenAI API (Chat Completions) for brewery/user data. Requires the `OPENAI_API_KEY` environment variable. |
+| `--openai-model`   | OpenAI model ID used when `--openai` is set. Default: `gpt-4o-mini`.                                             |
+| `--prompt-dir`     | Directory containing prompt files (for example, `BREWERY_GENERATION.md`). Required unless `--mocked` is set.     |
+| `--output, -o`     | Directory for generated SQLite artifacts. Default: `output`.                                                     |
+| `--log-path`       | Path for application logs. Default: `pipeline.log`.                                                              |
+| `--location-count` | Number of cities to sample from `locations.json` per run. Default: `10`.                                         |
+| `--temperature`    | Sampling temperature. Default: `1.0`.                                                                            |
+| `--top-p`          | Nucleus sampling. Default: `0.95`.                                                                               |
+| `--top-k`          | Top-k sampling. Default: `64`.                                                                                   |
+| `--n-ctx`          | Context window size. Default: `8192`.                                                                            |
+| `--seed`           | Random seed. Default: `-1` (random at runtime).                                                                  |
+| `--n-gpu-layers`   | Number of model layers to offload to GPU. Default: `0`.                                                          |
+| `--help, -h`       | Print usage and exit.                                                                                            |
+
+`--mocked`, `--model`, and `--openai` are mutually exclusive. Omitting all three
+exits with an error before the pipeline starts. Sampling flags are ignored
+unless `--model` is set (Llama).
+
+The post-build step copies `prompts/` into `build/prompts/`. Rebuild after
+editing any prompt file.
+
+---
+
+## Docker / RunPod
+
+The `tooling/pipeline/runpod/` directory contains a GPU-ready container
+configuration for running the pipeline on RunPod or any Docker host with an
+NVIDIA GPU.
+
+### How it works
+
+The container uses a two-stage build. The builder stage installs CMake/Ninja,
+clones the matching llama.cpp release tag for its headers only (installed into
+`/usr/local/include`), and copies prebuilt shared libraries (`libllama`,
+`libggml`, and CUDA/CPU backend plugins) from
+`ghcr.io/ggml-org/llama.cpp:full-cuda` into `/usr/local/lib`. With both headers
+and libraries present, CMake's system-library detection (see [Build](#build)
+above) finds them and skips the FetchContent source build, keeping image build
+times short.
+
+The runtime stage copies the compiled binary, the same prebuilt shared
+libraries, and config/prompt assets into a slim CUDA runtime image. It sets
+`LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH` so the dynamic linker resolves
+`libllama`/`libggml` at startup, and also co-locates `libggml-cuda.so` and the
+CPU backend plugins next to the binary for `ggml_backend_load_all()`'s `dlopen`
+scan.
+
+### Build the image
+
+Run from the `tooling/pipeline/` directory (the CMake project root), not from
+inside `runpod/`, so the `COPY . .` step picks up the full project context.
+
+```bash
+docker build -t biergarten-pipeline:latest -f runpod/Dockerfile .
+```
+
+To monitor the full build output and confirm CMake selects the system llama.cpp:
+
+```bash
+docker build \
+  --progress=plain \
+  --no-cache \
+  -t biergarten-pipeline:latest \
+  -f runpod/Dockerfile \
+  . 2>&1 | tee build.log
+```
+
+Look for `[biergarten] Found system llama.cpp — skipping FetchContent` in the
+output to confirm the fast path was taken.
+
+### Run the container
+
+The container always runs the model-backed path; there is no `--mocked`
+container mode (use a native build for that; see [Quick start](#quick-start)).
+The entrypoint, `runpod/start.sh`, downloads the GGUF model automatically if it
+is not already present at the configured path.
+
+```bash
+docker run --rm \
+  --runtime=nvidia \
+  -v "$PWD/models:/workspace/models" \
+  -v "$PWD/output:/workspace/output" \
+  -v "$PWD/logs:/workspace/logs" \
+  biergarten-pipeline:latest
+```
+
+By default this downloads `google_gemma-4-E4B-it-Q6_K.gguf` to `./models/` on
+first run if it isn't already there. To use a pre-downloaded model, place it at
+that path first; see [Model](#model).
+
+#### Environment variables
+
+| Variable                                                                                                | Purpose                                                                        |
+| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `BIERGARTEN_MODEL_PATH`                                                                                 | GGUF model path. Default: `/workspace/models/google_gemma-4-E4B-it-Q6_K.gguf`. |
+| `BIERGARTEN_OUTPUT_DIR`                                                                                 | SQLite output directory. Default: `/workspace/output`.                         |
+| `BIERGARTEN_LOG_PATH`                                                                                   | Log file path. Default: `/workspace/logs/pipeline.log`.                        |
+| `BIERGARTEN_GL_LAYERS`                                                                                  | GPU layers to offload (`--n-gpu-layers`). Default: `40`.                       |
+| `BIERGARTEN_TEMPERATURE`, `BIERGARTEN_TOP_P`, `BIERGARTEN_TOP_K`, `BIERGARTEN_N_CTX`, `BIERGARTEN_SEED` | Optional sampling overrides, unset by default (binary defaults apply).         |
+| `BIERGARTEN_EXTRA_ARGS`                                                                                 | Additional raw CLI args appended verbatim.                                     |
+
+`--prompt-dir` is hardcoded to `/app/prompts` inside the container and is not
+configurable via environment variable.
+
+### RunPod deployment
+
+Use a GPU pod template. Mount persistent storage for `/workspace/models`,
+`/workspace/output`, and `/workspace/logs`. See
+`tooling/pipeline/runpod/pod-template.yaml` for a starter template; set the
+environment variables listed in [Environment variables](#environment-variables)
+to match your run.
+
+---
+
+## Architecture
+
+### Pipeline stages
+
+| Stage              | Implementation                                                                                                                                                                                                                                                                                                                                                 |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Load               | `ICuratedDataService` (`CuratedJsonDataService`) reads `locations.json`, `personas.json`, `forenames-by-country.json`, and `surnames-by-country.json` (paths supplied via a `CuratedDataFilePaths` DTO at construction) into typed records, caching each after its first load. `--mocked` runs use `MockCuratedDataService`'s fixed in-memory dataset instead. |
+| Sample             | `BiergartenPipelineOrchestrator::QueryCitiesWithCountries()` samples `--location-count` locations per run (default `10`).                                                                                                                                                                                                                                      |
+| Enrich             | `WikipediaEnrichmentService` fetches brewing and beer-related context. Keeps going when a lookup fails. `--mocked` runs use `MockEnrichmentService` instead and skip Wikipedia entirely.                                                                                                                                                                       |
+| Generate Users     | `GenerateUsers()` samples a persona and a forename/surname pair per enriched city (skipping countries with no name data), then `MockGenerator` or `LlamaGenerator` produces a username, bio, and activity weight around the sampled name.                                                                                                                      |
+| Generate Breweries | `MockGenerator`, `LlamaGenerator`, or `OpenAIGenerator` produces brewery names and descriptions in English and the local language, then `IAddressService::ReverseGeocode()` resolves a street address for the brewery's jittered coordinates.                                                                                                                  |
+| Store              | `SqliteExportService` writes each successful user and brewery into a fresh dated `.sqlite` database with normalized `cities`, `breweries`, `brewery_addresses`, `users`, and `user_addresses` tables.                                                                                                                                                          |
+| Log                | `spdlog` writes results and warnings to the console.                                                                                                                                                                                                                                                                                                           |
+
+If name sampling, enrichment, or generation fails for a city, that city is
+skipped and the pipeline continues. `GenerateUsers()` runs before
+`GenerateBreweries()` in `BiergartenPipelineOrchestrator::Run()`.
+
+### Key components
+
+| Component                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/main.cc`                | Argument parsing and the Boost.DI composition root.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `CuratedJsonDataService`     | Implements `ICuratedDataService`; takes a `CuratedDataFilePaths` DTO (locations/personas/forenames/surnames paths) in its constructor, parses and validates curated location, persona, and forename/surname JSON, and memoizes each result after its first load on a given instance. `MockCuratedDataService` is the in-memory substitute (4 fixed locations, 3 personas, and name data for `US`/`DE`/`FR`/`BE`) used in `--mocked` runs.                                                                                                                                                                             |
+| `WikipediaEnrichmentService` | Queries Wikipedia extracts, caches results, and returns empty context on failure. `MockEnrichmentService` is the no-op substitute used in `--mocked` runs.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `LlamaGenerator`             | Formats prompts for Gemma 4, validates JSON output for both `GenerateBrewery` and `GenerateUser`, and retries malformed responses up to three times with corrective feedback in the retry prompt. The token budget is fixed across attempts; it is not raised automatically on truncation.                                                                                                                                                                                                                                                                                                                            |
+| `MockGenerator`              | Uses stable hash-based output so the same city/persona/name input always produces the same brewery or user.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `NominatimAddressService`    | Reverse-geocodes each brewery's jittered coordinates into a street address (`address_line1`, `postal_code`) via the public [Nominatim API](https://nominatim.openstreetmap.org), respecting its one-request-per-second usage policy. Falls back to a placeholder `address_line1` ("Address unavailable") and empty `postal_code` when the lookup fails or returns no usable street address. `MockAddressService` is the no-network substitute (`"123 Mock Street"`, `"00000"`) used in `--mocked` runs. Only breweries get a resolved street address; generated users carry a coordinate pair with no address fields. |
+| `SqliteExportService`        | Creates a dated SQLite file per run and persists each successful user and brewery into normalized tables.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Brewery/user payloads        | Brewery payloads include English and local-language name and description fields. User payloads carry a sampled first/last name and gender, an LLM-generated username/bio/activity weight, and a programmatically generated (not LLM-authored) unique email and date of birth.                                                                                                                                                                                                                                                                                                                                         |
+
+### Runtime behaviour
+
+| Component / behavior                       | Details                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WikipediaEnrichmentService`               | Fetches two Wikipedia extracts per city: a generic "brewing" extract and a "beer in `{country}`" extract. It does not currently query a city- or region-specific page. Each query string is cached after its first successful (or empty) lookup.                                                                                                                             |
+| `GetLocationContext()`                     | Returns an empty string when the web client is unavailable or when lookup/parsing fails.                                                                                                                                                                                                                                                                                     |
+| `LlamaGenerator`                           | Validates model output as structured JSON. On validation failure it retries up to three times, replaying the previous error message in the next prompt so the model can self-correct. All runs to date have produced valid output on the first pass; the retry path is kept for resilience.                                                                                  |
+| `MockGenerator`                            | Uses stable hashes for repeatable output in demos and Storybook runs.                                                                                                                                                                                                                                                                                                        |
+| `NominatimAddressService.ReverseGeocode()` | Sleeps one second after every request to respect Nominatim's usage policy, and returns `std::nullopt` (logged as a warning, not a skipped city) if the request fails, the response has no `address` object, or neither `house_number` nor `road` is present — the brewery is still generated and exported, just with a placeholder address.                                  |
+| `CuratedJsonDataService`                   | Memoizes each of `LoadLocations()`, `LoadPersonas()`, `LoadForenamesByCountry()`, and `LoadSurnamesByCountry()` independently the first time each is called, since `BiergartenPipelineOrchestrator` owns a single `ICuratedDataService` instance for the whole run; later calls return the cached result instead of re-parsing.                                              |
+| `GenerateUsers()`                          | Samples a forename/surname pair per city via `SampleName()`, keyed by the city's ISO 3166-1 code. Countries present in `locations.json` but absent from either name fixture (currently `KE`, `SE`, `SG`, `TH`, `VN`, `ZA`) are skipped, the same way a failed enrichment or generation call skips a city; see ETHICS-AND-KNOWN-ISSUES.md's Names-by-Country Dataset section. |
+
+### Process flow - activity diagram
+
+See [Activity diagram](./diagrams/current/activity.md).
+
+### Architectural overview - class diagram
+
+See [Class diagram](./diagrams/current/class.md).
+
+---
+
+## Generated output
+
+Each successful run stores a `BreweryRecord` pair with the source location and a
+`BreweryResult` payload, and a `UserRecord` pair with the source location and a
+`UserResult` payload. The same generated records are also written to a fresh
+SQLite export file named with the current UTC timestamp.
+
+| Field               | Meaning                                                                               |
+| ------------------- | ------------------------------------------------------------------------------------- |
+| `name_en`           | Brewery name in English.                                                              |
+| `description_en`    | Brewery description in English.                                                       |
+| `name_local`        | Brewery name in the local language.                                                   |
+| `description_local` | Brewery description in the local language.                                            |
+| `address_line1`     | Street address resolved via reverse geocoding, or a placeholder if resolution failed. |
+| `postal_code`       | Postal code resolved via reverse geocoding, or empty if resolution failed.            |
+
+| Field             | Meaning                                                                                |
+| ----------------- | -------------------------------------------------------------------------------------- |
+| `first_name`      | Sampled forename, copied from the curated name data (not LLM-invented).                |
+| `last_name`       | Sampled surname, copied from the curated name data (not LLM-invented).                 |
+| `gender`          | Gender associated with the sampled forename in the source dataset.                     |
+| `username`        | LLM-generated handle.                                                                  |
+| `bio`             | LLM-generated short biography.                                                         |
+| `activity_weight` | Relative check-in/activity weight, reserved for a future J-curve activity profile.     |
+| `email`           | Unique `@thebiergarten.app` address, generated programmatically from the sampled name. |
+| `date_of_birth`   | Randomized date of birth (age 19-48), generated programmatically.                      |
+
+The log dump also includes city, country, state or province, ISO subdivision
+code, latitude, and longitude for each entry.
+
+### Consumer data shape
+
+| Field                               | Why it matters                                   |
+| ----------------------------------- | ------------------------------------------------ |
+| `city`, `state_province`, `country` | Human-readable location labels and page headings |
+| `iso3166_1`, `iso3166_2`            | Filtering, regional grouping, locale matching    |
+| `latitude`, `longitude`             | Map pins and nearby brewery views                |
+| `local_languages`                   | Locale-aware copy selection                      |
+| `name_en`, `description_en`         | Default English display content                  |
+| `name_local`, `description_local`   | Local-language display content                   |
+
+---
+
+## Tech stack
+
+- C++20
+- CMake 3.31+
+- Boost.JSON, Boost.ProgramOptions, Boost.DI
+- spdlog
+- cpp-httplib (with OpenSSL)
+- SQLite amalgamation fetched and compiled via CMake FetchContent
+- llama.cpp (auto-detected from system install or fetched via FetchContent)
+- Docker with NVIDIA CUDA 12.6 base image for GPU container builds
+- RunPod for cloud GPU inference
+
+The build fetches Boost.DI, spdlog, and SQLite via CMake. llama.cpp is fetched
+only when a system installation is not detected. Metal is enabled on Apple
+Silicon; CUDA or HIP/ROCm is detected on Linux when the toolkit is present.
+
+> **Code style:** The code follows the Google C++ Style Guide, except that
+> indentation is 3 spaces instead of Google's 2, and uses C++20 throughout.
+
+---
+
+## Tested hardware
+
+### ARM macOS (M1 Pro)
+
+|           |                                   |
+| --------- | --------------------------------- |
+| Host      | MacBook Pro 14" (2021)            |
+| CPU       | Apple M1 Pro (8-core)             |
+| GPU       | Apple M1 Pro (14-core integrated) |
+| Memory    | 16 GB                             |
+| Model     | Gemma 4 E4B                       |
+| Inference | llama.cpp with Metal              |
+
+### x86_64 Linux (NVIDIA RTX 2000)
+
+|           |                                |
+| --------- | ------------------------------ |
+| Host      | ThinkPad P1 Gen 7 (Fedora 43)  |
+| CPU       | Intel Core Ultra 7 155H        |
+| GPU       | NVIDIA RTX 2000 Ada Generation |
+| Memory    | 32 GB                          |
+| Model     | Gemma 4 E4B                    |
+| Inference | llama.cpp with CUDA 12.x       |
+
+### x86_64 Linux (Docker / RunPod, NVIDIA CUDA)
+
+|           |                                             |
+| --------- | ------------------------------------------- |
+| Host      | RunPod GPU pod                              |
+| Base      | nvidia/cuda:12.6.3-devel-ubuntu24.04        |
+| Model     | Gemma 4 E4B Q6_K                            |
+| Inference | llama.cpp prebuilt CUDA backends via dlopen |
+
+---
+
+## Fixture strategy
+
+- `--mocked` for stable fixtures, repeatable screenshots, and Storybook runs.
+  `MockCuratedDataService` swaps in for `CuratedJsonDataService`, so no fixture
+  files need to be present on disk.
+- `--model` when geographically grounded content matters for demos.
+- Keep `locations.json` structured enough to support discovery and future
+  filtering.
+- `personas.json`, `forenames-by-country.json`, and `surnames-by-country.json`
+  are curated/vendored fixture data, not LLM-generated; see
+  ETHICS-AND-KNOWN-ISSUES.md's Names-by-Country Dataset section for provenance.
+- Treat SQLite output as seed material for the app's brewery and user domains,
+  not production data.
+
+---
+
+## Repo layout
+
+| Path                                         | Purpose                                                     |
+| -------------------------------------------- | ----------------------------------------------------------- |
+| `tooling/pipeline/includes/`                 | Public headers and shared models.                           |
+| `tooling/pipeline/src/`                      | Implementation files.                                       |
+| `tooling/pipeline/locations.json`            | Curated city input copied into the build tree.              |
+| `tooling/pipeline/personas.json`             | Curated user persona archetypes copied into the build tree. |
+| `tooling/pipeline/forenames-by-country.json` | Vendored (CC0) forename data by ISO 3166-1 country code.    |
+| `tooling/pipeline/surnames-by-country.json`  | Vendored (CC0) surname data by ISO 3166-1 country code.     |
+| `tooling/pipeline/prompts/`                  | System prompts used by the model-backed path.               |
+| `tooling/pipeline/runpod/`                   | Dockerfile, launcher, and RunPod pod template.              |
+| `docs/pipeline/diagrams/`                    | Architecture and pipeline diagrams.                         |
+| `docs/pipeline/ETHICS-AND-KNOWN-ISSUES.md`   | Ethics, bias, hallucination analysis, mitigations.          |
+
+---
+
+## Code tour
+
+Paths below are relative to `tooling/pipeline/`.
+
+| Path                                    | Purpose                                                                                                                                                     |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/main.cc`                           | Argument parsing and DI composition root.                                                                                                                   |
+| `src/biergarten_pipeline_orchestrator/` | Orchestration, sampling, logging, and export.                                                                                                               |
+| `src/services/curated_data/`            | `CuratedJsonDataService`, the file-backed `ICuratedDataService`, and `MockCuratedDataService`, the in-memory `ICuratedDataService` used in `--mocked` runs. |
+| `src/services/enrichment/wikipedia/`    | Enrichment service and cache.                                                                                                                               |
+| `src/services/sqlite/`                  | SQLite export implementation.                                                                                                                               |
+| `src/data_generation/llama/`            | Local inference, prompt loading, and output validation.                                                                                                     |
+| `src/data_generation/mock/`             | Deterministic fallback.                                                                                                                                     |
+| `runpod/`                               | Container build and runtime launcher.                                                                                                                       |
+
+---
+
+## Next steps
+
+The pipeline currently produces city-aware brewery and user records and dated
+SQLite exports.
+
+The next passes add additional fixture types so the app can exercise the full
+brewery and social domains without live data.
+
+For the detailed engineering breakdown of what's needed to reach the
+architecture in [`diagrams/planned/`](./diagrams/planned/), see
+[ROADMAP.md](./ROADMAP.md).
+
+### Testing
+
+- Unit test JSON validation and retry logic against malformed, truncated, and
+  empty model outputs.
+- Integration test the enrichment pipeline with missing context, short context,
+  and fake context inputs.
+- Adversarial context tests: feed plausible but geographically incorrect
+  Wikipedia extracts and verify the model does not silently blend them with
+  training data.
+- Verify bilingual enrichment behaviour when only an English extract is
+  available versus when both extracts are present.
+- Confirm the retry path is reachable when the reasoning block consumes
+  available token budget.
+
+### Beer generation
+
+Generate catalog entries with style, ABV, IBU, color, aroma notes, and food
+pairing hints. Link beers back to breweries and cities. Keep style coverage wide
+enough to exercise search, sort, and category filters.
+
+### Check-in system
+
+Produce timestamped check-in events between users and breweries. Use a J-curve
+activity profile: a small set of users accounts for most check-ins, the rest
+appear occasionally. Add bursty behaviour around weekends and travel periods.
+
+### Beer ratings
+
+Generate rating events with a strong positive skew and a long tail of lower
+scores. Avoid uniform distributions. Attach timestamps and user IDs so the app
+can compute averages, trends, and per-style comparisons.

docs/pipeline/ROADMAP.md

@@ -0,0 +1,208 @@
+---
+title: Pipeline roadmap — reaching the planned architecture
+last-updated: 2026-09-01
+tags:
+  - pipeline
+  - roadmap
+  - cpp
+  - concurrency
+---
+
+Engineering breakdown for closing the gap between the **current** pipeline and
+the **planned** architecture in
+[`diagrams/planned/class.md`](./diagrams/planned/class.md) /
+[`diagrams/planned/activity.md`](./diagrams/planned/activity.md). Items are
+grouped by layer, roughly by dependency order. For the current implementation,
+see [README.md](./README.md).
+
+The only concurrency today is a log dispatcher thread draining a
+`BoundedChannel<LogEntry>` into spdlog; sampling, enrichment, generation, and
+export run synchronously on the main thread — §6 introduces the planned worker
+threads.
+
+---
+
+## 1. Domain Models
+
+`tooling/pipeline/includes/data_model/generated_models.h` and `models.h`.
+
+- [ ] Add `Completeness` enum (`Full`/`Partial`/`Absent`) and a
+      `LocationContext` struct (`text`, `completeness`, `char_count`); replace
+      `EnrichedCity::region_context` (a plain `string` today) with it.
+- [ ] Add `BeerStyle` (`name`, `description`, `min_abv`, `max_abv`, `min_ibu`,
+      `max_ibu`).
+- [ ] Add `BeerResult`, `CheckinResult`, `RatingResult` payloads.
+- [ ] Add `GenerationMetadata` (`generation_id`, `generated_time`,
+      `context_provided`, `generated_with`).
+- [x] `UserResult` gained `first_name`/`last_name`/`gender`/`activity_weight`
+      (was just `username`/`bio`), copied from the sampled `Name`, not
+      LLM-invented.
+- [x] Added `Name` (`first_name`, `last_name`, `gender`) and `ForenameEntry`
+      (`name`, `gender`). Flatter than planned: no `NamesByCountry` wrapper —
+      `ICuratedDataService` exposes `ForenamesByCountryMap`/
+      `SurnamesByCountryMap` (keyed by ISO 3166-1) directly, and sampling is a
+      free function, `SampleName(forenames, surnames, iso3166_1, rng)`, not a
+      class method.
+- [ ] Extend `GeneratedBrewery` with `brewery_id`, `context_completeness`,
+      `metadata` (currently just `{location, brewery}`).
+- [ ] Add `GeneratedBeer`, `GeneratedCheckin`, `GeneratedRating`,
+      `GeneratedFollow` aggregate structs.
+- [x] Added `UserRecord` (`location`, `user`, `email`, `date_of_birth`), the
+      current stand-in for the planned `GeneratedUser`. `email`/ `date_of_birth`
+      are programmatic (never LLM-authored), for downstream auth-account
+      seeding. Missing `user_id`/`password`/`metadata`; already exported via
+      `ProcessRecord(const UserRecord&)` (§5).
+- [x] Added `UserPersona` (`name`, `description`, `style_affinities`).
+
+## 2. Data Preloading
+
+`tooling/pipeline/includes/services/curated_data/`, fixture files.
+
+- [x] Extracted `ICuratedDataService` (not `DataPreloader`); `Load*()` methods
+      take no arguments, return `const&`. `CuratedJsonDataService` (renamed from
+      `JsonLoader`) takes a `CuratedDataFilePaths` DTO at construction and
+      memoizes each `Load*()` result. `MockCuratedDataService` (fixed data for
+      `US`/`DE`/`FR`/`BE`) binds in its place under `--mocked`.
+- [ ] Add `LoadBeerStyles()`. `beer-styles.json` exists and is copied into the
+      Docker image, but no loader reads it and the native CMake build doesn't
+      copy it into `build/` at all.
+- [x] Added `LoadPersonas()` and authored `personas.json`.
+- [x] Added `LoadForenamesByCountry()` / `LoadSurnamesByCountry()` (two methods,
+      not one combined `LoadNamesByCountry()`), parsing vendored CC0 data from
+      `sigpwned/popular-names-by-country-dataset` — see
+      ETHICS-AND-KNOWN-ISSUES.md for provenance. Deliberately not pre-paired or
+      filtered to `locations.json`'s countries, to keep per-forename gender and
+      support more countries later without re-sourcing.
+
+## 3. Policy / Strategy Layer
+
+Entirely new — no `includes/policy/` (or equivalent) exists today.
+
+- [ ] `ContextStrategy` + `BreweryContextStrategy`/`BeerContextStrategy`. Today
+      `WikipediaEnrichmentService::GetLocationContext` hardcodes a `"brewing"`
+      query and a `"beer in {country}"` query directly.
+- [ ] `SamplingStrategy` + `UniformSamplingStrategy`, replacing the inline
+      `std::ranges::sample(...)` in `QueryCitiesWithCountries()`.
+- [ ] `BeerSelectionStrategy` + `RandomBeerSelectionStrategy` (depends on §1,
+      §2).
+- [ ] `CheckinDistributionStrategy` + `JCurveCheckinStrategy` /
+      `RandomCheckinStrategy` — the "Check-In System" README next step, made
+      concrete.
+- [ ] `FollowGenerationStrategy` + `RandomFollowStrategy` /
+      `ActivityWeightedFollowStrategy`.
+
+## 4. Data Generation
+
+`tooling/pipeline/includes/data_generation/`, `src/data_generation/`.
+
+- [ ] Extend `DataGenerator` with `GenerateBeer`, `GenerateCheckin`,
+      `GenerateRating` (today: only `GenerateBrewery`/`GenerateUser`).
+- [x] Added `OpenAIGenerator`, a third backend calling the OpenAI Chat
+      Completions API with Structured Outputs (`json_schema`, `strict`) —
+      schema-valid JSON with no `IPromptFormatter`/GBNF grammar needed. Selected
+      via `--openai`/`GeneratorMode::kOpenAI`; landed ahead of §3/§4. Now shown
+      in `diagrams/planned/class.md` alongside `MockGenerator`/`LlamaGenerator`,
+      noting only `GenerateBrewery`/`GenerateUser` are implemented so far.
+- [x] Implemented `LlamaGenerator::GenerateUser` for real (GBNF grammar,
+      `ValidateUserJson`, 3 retries with corrective feedback,
+      `prompts/USER_GENERATION.md`). Signature is
+      `(city, persona, name) : UserResult`, matching the activity diagram.
+- [ ] Implement
+      `MockGenerator::GenerateBeer`/`GenerateCheckin`/`GenerateRating`.
+- [ ] Add `IPromptFormatter::ExpectedArchitecture()` and
+      `LlamaGenerator::ValidateModelArchitecture()` so a mismatched GGUF chat
+      template fails fast instead of degrading silently.
+- [ ] Add prompt templates for beer/checkin/rating, next to
+      `prompts/BREWERY_GENERATION.md`.
+
+## 5. Export Service
+
+`tooling/pipeline/includes/services/database/`, `src/services/sqlite/`.
+
+- [x] `IExportService::ProcessRecord(const UserRecord&)` and the `users` table
+      are implemented — every successful user is exported with its resolved
+      `location_id`.
+- [ ] Extend `IExportService` with `ProcessBeer`, `ProcessCheckin`,
+      `ProcessRating`, `ProcessFollow`.
+- [ ] Add `beers`, `checkins`, `ratings`, `follows` tables to
+      `InitializeSchema()` (`cities`/`breweries`/`brewery_addresses`/`users`/
+      `user_addresses` already exist — see `sqlite_statement_helpers.h` for the
+      pattern).
+- [ ] Add a `brewery_cache_` alongside `city_cache_`, and move from one open
+      transaction for the whole run to per-phase batched commits (`BEGIN` /
+      `COMMIT & BEGIN` on a batch threshold), per the planned activity diagram.
+
+## 6. Concurrency & Orchestration
+
+`tooling/pipeline/includes/concurrency/`,
+`src/biergarten_pipeline_orchestrator/`.
+
+- [ ] `BoundedChannel<T>` exists and is production-tested but only wired to the
+      log channel. Stand up the per-phase producer/consumer channels (`loc_ch`,
+      `exp_ch`, etc.) with a dedicated LLM worker thread and SQLite worker
+      thread each; the brewery phase needs a third, a Geocode Worker between
+      them on its own `geo_ch` (§9).
+- [ ] Rewrite `Run()` from one synchronous pass into phased methods —
+      `RunUserPhase` → `RunBreweryAndBeerPhase` (`RunBeerPhase` sub-step once
+      `brewery_pool_` fills) → `RunCheckinPhase`/`RunFollowPhase` (parallel) →
+      `RunRatingPhase` — backed by `user_pool_`, `brewery_pool_`, `beer_pool_`,
+      `checkin_pool_`, `follow_pool_`.
+- [ ] Structurally join worker threads (e.g. `std::jthread`) before `Run()`
+      returns, per the existing comment in `biergarten_pipeline_orchestrator.h`,
+      so nothing logs to a closed channel during teardown.
+
+## 7. Enrichment
+
+- [ ] Decide whether to restore the city/region-specific Wikipedia query
+      currently commented out in `get_summary.cc` — the §3 `ContextStrategy`
+      work is a natural place to reintroduce it.
+- [ ] Pre-warm caches at startup (`PreWarmBeerStyleCache`,
+      `PreWarmLocationCache`) instead of fetching lazily per record.
+
+## 8. Fixtures / Build
+
+- [x] Authored `personas.json`, `forenames-by-country.json`,
+      `surnames-by-country.json` (§2).
+- [ ] Fix the `beer-styles.json` build-tree gap: add it to the "Runtime Assets"
+      `configure_file` step in `CMakeLists.txt`.
+
+## 9. Geocoding
+
+`tooling/pipeline/includes/services/address/`, `src/services/address/` — added
+entirely after `diagrams/planned/` was authored; wasn't tracked here until now.
+
+- [x] Added `IAddressService`
+      (`ReverseGeocode(lon, lat) :     optional<AddressLookupResult>`),
+      `NominatimAddressService` (public Nominatim API, 1s sleep per request,
+      `nullopt` on failure or no usable address), and `MockAddressService`
+      (fixed placeholder for `--mocked`). Called once per brewery, after
+      `GenerateBrewery` and before export, to resolve
+      `BreweryAddress::address_line1`/`postal_code` — users aren't geocoded.
+      `diagrams/planned/class.md` now models this as an
+      `InfrastructureGeocoding` namespace owned by the orchestrator.
+- [ ] Give the brewery phase its own **Geocode Worker** thread, between the LLM
+      worker and the SQLite worker (`loc_ch` → LLM Worker → `geo_ch` → Geocode
+      Worker → `exp_ch` → SQLite Worker), rather than calling `ReverseGeocode`
+      inline — Nominatim's rate limit is unrelated to inference speed, so
+      coupling them stalls whichever side is slower and needlessly cools the
+      LLM's KV cache. It never skips a record on lookup failure, only attaches a
+      placeholder; shown as its own subgraph (`B_GEO`) in
+      `diagrams/planned/activity.md`. One worker per phase is safe today since
+      `RunUserPhase` joins before `RunBreweryPhase` starts; concurrent phases
+      plus user-geocoding would need a shared rate-limited client instead, since
+      the throttle is global, not per-thread.
+
+---
+
+## Suggested build order
+
+The planned activity diagram's phase notes imply a dependency order:
+
+1. Domain models (§1) and data preloading (§2) — nothing else compiles without
+   these.
+2. Export schema (§5) — so every generation phase has somewhere to land output.
+3. Policy/strategy layer (§3) and generator interface (§4).
+4. Concurrency/orchestration rewrite (§6) — wires §1–§5 into the phased,
+   parallel pipeline the planned diagrams show.
+5. Enrichment cache pre-warming and the city/region query decision (§7) — most
+   valuable once phases run concurrently.

docs/pipeline/diagrams/current/activity.md

@@ -0,0 +1,11 @@
+# The Biergarten Data Pipeline (Current — Synchronous Data Path)
+
+The only concurrency in the current pipeline is a dedicated log dispatcher
+thread that drains `log_channel` and forwards entries to spdlog for the entire
+run (joined during shutdown after `log_channel` closes).
+`BiergartenPipelineOrchestrator::Run()` itself is synchronous — sampling,
+enrichment, generation, and export all happen on the main thread.
+
+```mermaid
+--8<-- "pipeline/diagrams/current/activity.mmd"
+```

docs/pipeline/diagrams/current/activity.mmd

@@ -0,0 +1,90 @@
+---
+config:
+    layout: elk
+---
+flowchart LR
+    Start([start]) --> ParseArgs["main.cc: ParseArguments(argc, argv)"]
+    ParseArgs --> ArgsValid{Arguments valid?}
+    ArgsValid -- no --> LogErr[Log error / usage info] --> Stop1([stop])
+    ArgsValid -- yes --> Init["main.cc: Init OpenSSL global state and LlamaBackendState"]
+    Init --> DI["main.cc: di::make_injector(...)<br/>binds ILogger, IEnrichmentService, DataGenerator, IExportService, IPromptFormatter, WebClient based on --mocked vs. model-backed mode"]
+    DI --> LogThread["main.cc: create BoundedChannel log_channel, spawn log dispatcher thread (LogDispatcher::Run)"]
+    LogThread --> CreateOrch["main.cc: injector.create BiergartenPipelineOrchestrator"]
+    CreateOrch --> Run["BiergartenPipelineOrchestrator::Run()"]
+
+    Run --> SqliteInit["SqliteExportService.Initialize()<br/>builds biergarten_seed_&lt;UTC datetime&gt;.sqlite (numeric suffix if it exists), opens DB connection, executes schema DDL, begins transaction"]
+    SqliteInit --> QueryLoc[Orchestrator: QueryLocations]
+    QueryLoc --> LoadLoc["CuratedJsonDataService.LoadLocations()"]
+    LoadLoc --> SampleLoc["std::ranges::sample(all_locations, --location-count) — defaults to 10"]
+
+    SampleLoc --> EnrichLoop{For each sampled Location}
+    EnrichLoop --> GetContext["IEnrichmentService.GetLocationContext(loc)<br/>WikipediaEnrichmentService fetches a generic 'brewing' extract and a 'beer in {country}' extract (not city/region-specific); MockEnrichmentService (--mocked) returns an empty string"]
+    GetContext --> LookupFailed{Lookup failed?}
+    LookupFailed -- yes --> SkipCity1[Log warning, skip city] --> EnrichLoop
+    LookupFailed -- no --> StoreEnriched["Store EnrichedCity{Location, region_context}"] --> EnrichLoop
+    EnrichLoop -- done --> GenUsers[Orchestrator: GenerateUsers enriched_cities]
+    SkipCity1 ~~~ GenUsers
+    StoreEnriched ~~~ GenUsers
+
+    GenUsers --> LoadUserData["CuratedJsonDataService: LoadPersonas / LoadForenamesByCountry / LoadSurnamesByCountry<br/>each memoized after first parse; MockCuratedDataService (--mocked) returns a fixed in-memory dataset instead, skipping these JSON files"]
+
+    LoadUserData --> UserLoop{For each EnrichedCity}
+    UserLoop --> SampleName["SampleName(forenames_by_country, surnames_by_country, location.iso3166_1)"]
+    SampleName --> NamesAvail{Names available for country?}
+    NamesAvail -- no --> SkipCity2[Log warning, skip city] --> UserLoop
+    NamesAvail -- yes --> SamplePersona["Sample UserPersona (uniform random)"]
+    SamplePersona --> UserGenMode{Generator mode}
+
+    UserGenMode -- MockGenerator --> UserMockGen[DeterministicHash and Format]
+    UserGenMode -- LlamaGenerator --> UserLlamaLoad["prompt_directory_.Load(USER_GENERATION) → USER_GENERATION.md in --prompt-dir"]
+    UserLlamaLoad --> UserLlamaRetry["Infer(...) with kUserJsonGrammar → ValidateUserJson<br/>retry up to 3 attempts, appending validation error to the retry prompt on failure"]
+    UserGenMode -- OpenAIGenerator --> UserOAILoad["prompt_directory_.Load(USER_GENERATION) — same prompt file as LlamaGenerator, content is backend-agnostic"]
+    UserOAILoad --> UserOAIRetry["CallChatCompletionsApi(...) with kUserJsonSchema → ValidateUserJson<br/>retry up to 2 attempts — Structured Outputs (json_schema, strict) already guarantees schema shape, so retries only cover transient failures / placeholder text"]
+
+    UserMockGen --> UserGenDone{Generation successful?}
+    UserLlamaRetry --> UserGenDone
+    UserOAIRetry --> UserGenDone
+
+    UserGenDone -- yes --> UserPostProc["GetRandomCoordsWithinRange (5km jitter), BuildEmail, GenerateDateOfBirth<br/>email and date_of_birth are generated programmatically, never LLM-authored; generation + coordinate jitter run inside one try/catch per record"]
+    UserGenDone -- no --> UserGenFail["Log warning: generation failed, skipping"] --> UserLoop
+
+    UserPostProc --> UserExport["SqliteExportService.ProcessRecord(UserRecord)<br/>reuse cached city_id or insert City and cache its id; insert User + UserAddress (FK city_id)"]
+    UserExport --> UserExportFail{Exception during insert?}
+    UserExportFail -- yes --> UserExportWarn["Log warning: SQLite export failed"] --> UserLoop
+    UserExportFail -- no --> UserLoop
+    UserLoop -- done --> GenBrew[Orchestrator: GenerateBreweries enriched_cities]
+    SkipCity2 ~~~ GenBrew
+    UserGenFail ~~~ GenBrew
+    UserExportWarn ~~~ GenBrew
+    UserExportFail ~~~ GenBrew
+
+    GenBrew --> BrewLoop{For each EnrichedCity}
+    BrewLoop --> BrewGenMode{Generator mode}
+
+    BrewGenMode -- MockGenerator --> BrewMockGen[DeterministicHash and Format]
+    BrewGenMode -- LlamaGenerator --> BrewLlamaLoad["PrepareRegionContext, prompt_directory_.Load(BREWERY_GENERATION) → BREWERY_GENERATION.md"]
+    BrewLlamaLoad --> BrewLlamaRetry["Infer(...) with kBreweryJsonGrammar → ValidateBreweryJson<br/>retry up to 3 attempts; max_tokens is fixed across retries, not raised on truncation"]
+    BrewGenMode -- OpenAIGenerator --> BrewOAILoad["PrepareRegionContext, prompt_directory_.Load(BREWERY_GENERATION) — same prompt file as LlamaGenerator"]
+    BrewOAILoad --> BrewOAIRetry["CallChatCompletionsApi(...) with kBreweryJsonSchema → ValidateBreweryJson<br/>retry up to 2 attempts — Structured Outputs already guarantees schema shape"]
+
+    BrewMockGen --> BrewGenDone{Generation successful?}
+    BrewLlamaRetry --> BrewGenDone
+    BrewOAIRetry --> BrewGenDone
+
+    BrewGenDone -- yes --> BrewPostProc["GetRandomCoordsWithinRange (5km jitter)<br/>generation + jitter run inside one try/catch per record"]
+    BrewGenDone -- no --> BrewGenFail["Log warning: generation failed, skipping"] --> BrewLoop
+
+    BrewPostProc --> BrewGeocode["IAddressService.ReverseGeocode(longitude, latitude)<br/>NominatimAddressService hits the live Nominatim API (1 req/sec) and returns nullopt on failure; MockAddressService (--mocked) returns a fixed placeholder address instead"]
+    BrewGeocode --> BrewGeocodeFailed{Geocode resolved?}
+    BrewGeocodeFailed -- no --> BrewPlaceholder["Log warning: could not reverse geocode; use placeholder address_line1, empty postal_code"] --> BrewExport
+    BrewGeocodeFailed -- yes --> BrewExport["SqliteExportService.ProcessRecord(BreweryRecord)<br/>reuse cached city_id or insert City and cache its id; insert Brewery + BreweryAddress (FK city_id)"]
+    BrewExport --> BrewExportFail{Exception during insert?}
+    BrewExportFail -- yes --> BrewExportWarn["Log warning: SQLite export failed (data loss prevented per-record; pipeline continues)"] --> BrewLoop
+    BrewExportFail -- no --> BrewLoop
+    BrewLoop -- done --> Finalize["SqliteExportService.Finalize()<br/>commits transaction, closes database connection"]
+    BrewGenFail ~~~ Finalize
+    BrewExportWarn ~~~ Finalize
+    BrewExportFail ~~~ Finalize
+
+    Finalize --> CloseLog["main.cc: close log_channel, join log dispatcher thread"]
+    CloseLog --> Stop2(["return 0 / stop"])

docs/pipeline/diagrams/current/class.md

@@ -0,0 +1,5 @@
+# The Biergarten Data Pipeline — Class Diagram (Current)
+
+```mermaid
+--8<-- "pipeline/diagrams/current/class.mmd"
+```

docs/pipeline/diagrams/current/class.mmd

@@ -0,0 +1,290 @@
+---
+config:
+    layout: elk
+---
+
+classDiagram
+    class BiergartenPipelineOrchestrator {
+        -shared_ptr~ILogger~ logger_
+        -unique_ptr~IEnrichmentService~ context_service_
+        -unique_ptr~DataGenerator~ generator_
+        -unique_ptr~IExportService~ exporter_
+        -unique_ptr~ICuratedDataService~ curated_data_service_
+        -unique_ptr~IAddressService~ address_service_
+        -ApplicationOptions application_options_
+        -vector~BreweryRecord~ generated_breweries_
+        -vector~UserRecord~ generated_users_
+        +Run() bool
+        -QueryLocations() vector~City~
+        -GenerateBreweries(cities) void
+        -GenerateUsers(cities) void
+        -LogResults() void
+    }
+    note for BiergartenPipelineOrchestrator "GenerateBreweries/GenerateUsers jitter each address via GetRandomCoordsWithinRange(), uniformly within 5km of the city centre. GenerateBreweries additionally reverse-geocodes the jittered coordinates via address_service_."
+
+    class LogLevel {
+        <<enumeration>>
+        Debug
+        Info
+        Warn
+        Error
+    }
+
+    class PipelinePhase {
+        <<enumeration>>
+        Startup
+        Enrichment
+        UserGeneration
+        BreweryAndBeerGeneration
+        CheckinGeneration
+        RatingGeneration
+        FollowGeneration
+        Teardown
+    }
+
+    class LogDTO {
+        <<struct>>
+        +LogLevel level
+        +PipelinePhase phase
+        +string message
+    }
+
+    class LogEntry {
+        <<struct>>
+        +time_point timestamp
+        +source_location origin
+        +thread::id thread_id
+        +LogLevel level
+        +PipelinePhase phase
+        +string message
+    }
+
+    class ILogger {
+        <<interface>>
+        +Log(payload) void
+        -DoLog(entry)* void
+    }
+
+    class LogProducer {
+        -BoundedChannel~LogEntry~ channel_
+        -DoLog(entry) void
+    }
+
+    class LogDispatcher {
+        -BoundedChannel~LogEntry~ channel_
+        +Run() void
+        -ToSpdlogLevel(level) level_enum
+    }
+
+    class IEnrichmentService {
+        <<interface>>
+        +GetLocationContext(loc) string
+    }
+
+    class MockEnrichmentService {
+        +GetLocationContext(loc) string
+    }
+
+    class WikipediaEnrichmentService {
+        -unique_ptr~WebClient~ client_
+        -unordered_map~string, string~ extract_cache_
+        +GetLocationContext(loc) string
+        -FetchExtract(query) string
+    }
+
+    class WebClient {
+        <<interface>>
+        +Get(url) string
+        +UrlEncode(value) string
+    }
+
+    class HttpWebClient {
+        +Get(url) string
+        +UrlEncode(value) string
+    }
+
+    class DataGenerator {
+        <<interface>>
+        +GenerateBrewery(city) BreweryResult
+        +GenerateUser(city, persona, name) UserResult
+    }
+
+    class MockGenerator {
+        +GenerateBrewery(city) BreweryResult
+        +GenerateUser(city, persona, name) UserResult
+        -DeterministicHash(location) size_t
+        -DeterministicHash(location, persona, name) size_t
+    }
+
+    class LlamaGenerator {
+        -ModelHandle model_
+        -ContextHandle context_
+        -unique_ptr~IPromptFormatter~ prompt_formatter_
+        -unique_ptr~IPromptDirectory~ prompt_directory_
+        -mt19937 rng_
+        +GenerateBrewery(...) BreweryResult
+        +GenerateUser(...) UserResult
+        -Load(model_path) void
+        -Infer(...) string
+        -InferFormatted(...) string
+    }
+
+    class OpenAIGenerator {
+        -string api_key_
+        -string model_
+        -shared_ptr~ILogger~ logger_
+        -unique_ptr~IPromptDirectory~ prompt_directory_
+        -unique_ptr~WebClient~ web_client_
+        +GenerateBrewery(city) BreweryResult
+        +GenerateUser(city, persona, name) UserResult
+        -CallChatCompletionsApi(...) string
+    }
+    note for OpenAIGenerator "Chat Completions with Structured Outputs (json_schema, strict) guarantees schema-valid JSON, replacing llama.cpp's GBNF grammar — no IPromptFormatter needed"
+
+    class IPromptFormatter {
+        <<interface>>
+        +Format(system_prompt, user_prompt) string
+    }
+
+    class Gemma4JinjaPromptFormatter {
+        +Format(system_prompt, user_prompt) string
+    }
+
+    class IPromptDirectory {
+        <<interface>>
+        +Load(key) string
+    }
+
+    class PromptDirectory {
+        -path prompt_dir_
+        -unordered_map~string, string~ cache_
+        +Load(key) string
+    }
+
+    class ICuratedDataService {
+        <<interface>>
+        +LoadLocations() vector~Location~
+        +LoadPersonas() vector~UserPersona~
+        +LoadForenamesByCountry() unordered_map~string, forename_list~
+        +LoadSurnamesByCountry() unordered_map~string, surname_list~
+    }
+
+    class CuratedJsonDataService {
+        -CuratedDataFilePaths filepaths_
+        -cache cache_
+        +LoadLocations() vector~Location~
+        +LoadPersonas() vector~UserPersona~
+        +LoadForenamesByCountry() unordered_map~string, forename_list~
+        +LoadSurnamesByCountry() unordered_map~string, surname_list~
+    }
+    note for CuratedJsonDataService "Takes a CuratedDataFilePaths DTO (locations/personas/forenames/surnames paths) once at construction, not per Load* call. Each Load* method memoizes its result in cache_ after its first call."
+
+    class MockCuratedDataService {
+        -vector~Location~ locations_
+        -vector~UserPersona~ personas_
+        -unordered_map~string, forename_list~ forenames_by_country_
+        -unordered_map~string, surname_list~ surnames_by_country_
+        +LoadLocations() vector~Location~
+        +LoadPersonas() vector~UserPersona~
+        +LoadForenamesByCountry() unordered_map~string, forename_list~
+        +LoadSurnamesByCountry() unordered_map~string, surname_list~
+    }
+    note for MockCuratedDataService "Fixed 4-location/3-persona dataset (US, DE, FR, BE) for --mocked runs"
+
+    class IAddressService {
+        <<interface>>
+        +ReverseGeocode(longitude, latitude) optional~AddressLookupResult~
+    }
+
+    class NominatimAddressService {
+        -unique_ptr~WebClient~ client_
+        -shared_ptr~ILogger~ logger_
+        +ReverseGeocode(longitude, latitude) optional~AddressLookupResult~
+    }
+    note for NominatimAddressService "Queries the public Nominatim API; sleeps 1s per request per its usage policy; returns nullopt on failure or when no usable street address is found"
+
+    class MockAddressService {
+        +ReverseGeocode(longitude, latitude) optional~AddressLookupResult~
+    }
+    note for MockAddressService "Returns a fixed placeholder address ('123 Mock Street', '00000') for --mocked runs, no network call"
+
+    class IExportService {
+        <<interface>>
+        +Initialize() void
+        +ProcessRecord(brewery) uint64_t
+        +ProcessRecord(user) uint64_t
+        +Finalize() void
+    }
+
+    class SqliteExportService {
+        -unique_ptr~IDateTimeProvider~ date_time_provider_
+        -string run_timestamp_utc_
+        -path database_path_
+        -SqliteDatabaseHandle db_handle_
+        -SqliteStatementHandle insert_city_stmt_
+        -SqliteStatementHandle insert_brewery_stmt_
+        -SqliteStatementHandle insert_brewery_address_stmt_
+        -SqliteStatementHandle insert_user_stmt_
+        -SqliteStatementHandle insert_user_address_stmt_
+        -bool transaction_open_
+        -unordered_map~string, sqlite3_int64~ city_cache_
+        +Initialize() void
+        +ProcessRecord(brewery) uint64_t
+        +ProcessRecord(user) uint64_t
+        +Finalize() void
+        -InitializeSchema() void
+        -ResolveCityId(city) sqlite3_int64
+    }
+
+    class IDateTimeProvider {
+        <<interface>>
+        +GetUtcTimestamp() string
+    }
+
+    class SystemDateTimeProvider {
+        +GetUtcTimestamp() string
+    }
+
+    BiergartenPipelineOrchestrator *-- ILogger : owns
+    BiergartenPipelineOrchestrator *-- IEnrichmentService : owns
+    BiergartenPipelineOrchestrator *-- DataGenerator : owns
+    BiergartenPipelineOrchestrator *-- IExportService : owns
+    BiergartenPipelineOrchestrator *-- ICuratedDataService : owns
+    BiergartenPipelineOrchestrator *-- IAddressService : owns
+
+    LogEntry *-- LogLevel
+    LogEntry *-- PipelinePhase
+    LogDTO *-- LogLevel
+    LogDTO *-- PipelinePhase
+    ILogger <|.. LogProducer : implements
+    LogProducer ..> LogEntry : emits
+    LogDispatcher ..> LogEntry : consumes
+
+    IEnrichmentService <|.. WikipediaEnrichmentService : implements
+    IEnrichmentService <|.. MockEnrichmentService : implements
+    WikipediaEnrichmentService *-- WebClient : owns
+
+    WebClient <|.. HttpWebClient : implements
+
+    DataGenerator <|.. MockGenerator : implements
+    DataGenerator <|.. LlamaGenerator : implements
+    DataGenerator <|.. OpenAIGenerator : implements
+
+    LlamaGenerator *-- IPromptFormatter : uses
+    LlamaGenerator *-- IPromptDirectory : uses
+
+    OpenAIGenerator *-- IPromptDirectory : uses
+    OpenAIGenerator *-- WebClient : uses
+
+    IPromptFormatter <|.. Gemma4JinjaPromptFormatter : implements
+    IPromptDirectory <|.. PromptDirectory : implements
+
+    ICuratedDataService <|.. CuratedJsonDataService : implements
+    ICuratedDataService <|.. MockCuratedDataService : implements
+
+    IAddressService <|.. NominatimAddressService : implements
+    IAddressService <|.. MockAddressService : implements
+
+    IExportService <|.. SqliteExportService : implements
+    SqliteExportService *-- IDateTimeProvider : owns
+    IDateTimeProvider <|.. SystemDateTimeProvider : implements

docs/pipeline/diagrams/planned/activity.md

@@ -0,0 +1,16 @@
+# The Biergarten Data Pipeline — Activity Diagram (Planned)
+
+Each generation phase runs a producer/consumer chain concurrently: an
+**Orchestrator** producer feeds a bounded channel, an **LLM Worker** consumes it
+and generates records (closing its output channel when the input is drained and
+closed), and a **SQLite Worker** consumes that output channel and commits in
+batches. The brewery phase inserts a fourth stage, a **Geocode Worker**, between
+the LLM Worker and the SQLite Worker: reverse-geocoding is network-bound and
+rate-limited independently of LLM inference (Nominatim's 1-request-per-second
+policy), so keeping it off the LLM Worker's thread means neither stage stalls
+waiting on the other's bottleneck. The Checkin and Follow phases run in parallel
+with each other once the user and brewery pools are populated.
+
+```mermaid
+--8<-- "pipeline/diagrams/planned/activity.mmd"
+```

docs/pipeline/diagrams/planned/activity.mmd

@@ -0,0 +1,213 @@
+---
+config:
+    layout: elk
+---
+
+flowchart LR
+    Start([start]) --> ParseArgs["Main: ParseArguments(argc, argv)"]
+    ParseArgs --> InvalidArgs{Invalid args?}
+    InvalidArgs -- yes --> LogErr["spdlog::error"] --> Stop1([stop])
+    InvalidArgs -- no --> InitOpenSSL["Main: Init OpenSSL global state and LlamaBackendState"]
+    InitOpenSSL --> BuildDI["Main: Build DI injector"]
+    BuildDI --> InitSqlite["Main: Initialize SqliteExportService<br/>opens SQLite connection; transactions now managed per-phase via batching"]
+    InitSqlite --> LogSetup["Main: create BoundedChannel log_ch, spawn Log Worker thread<br/>drains log_ch for the pipeline lifetime; all workers emit LogEntry via PipelineLogger, never spdlog directly"]
+    LogSetup --> OrchRun["BiergartenPipelineOrchestrator::Run()"]
+
+    OrchRun --> PL1["JsonLoader.LoadBeerStyles → EnrichmentService.PreWarmBeerStyleCache"]
+    OrchRun --> PL2["JsonLoader.LoadLocations → EnrichmentService.PreWarmLocationCache"]
+    OrchRun --> PL3["JsonLoader.LoadForenamesByCountry"]
+    OrchRun --> PL4["JsonLoader.LoadSurnamesByCountry"]
+    OrchRun --> PL5["JsonLoader.LoadPersonas"]
+    PL1 & PL2 & PL3 & PL4 & PL5 --> UserPhase["Orchestrator: RunUserPhase(sampled_locations)<br/>each Load* call memoized after first parse; MockCuratedDataService (--mocked) returns a fixed in-memory dataset instead, skipping these JSON files"]
+
+    UserPhase --> UCreate["Create BoundedChannels (loc_ch, exp_ch)"]
+
+    subgraph USERGEN["Phase 0 — User Generation (concurrent)"]
+        direction LR
+        subgraph U_PROD["Orchestrator (producer)"]
+            UP1["Loop: send Location → loc_ch"]
+            UP1 --> UP2["Close loc_ch"]
+        end
+        subgraph U_LLM["LLM Worker"]
+            UL1{"loc_ch has items?"}
+            UL1 -- yes --> UL2["Receive Location"]
+            UL2 --> UL3["GetLocationContextFromCache(location) — guaranteed cache hit from startup"]
+            UL3 --> UL4["IPersonaSelectionStrategy.SelectPersona(personas_palette_) — guaranteed cache hit; returns Persona{style_affinities, abv_range, ibu_preference, checkin_weight}"]
+            UL4 --> UL5["SampleName(forenames_by_country, surnames_by_country, iso3166_1, rng)<br/>deterministic, no LLM; free function; skips the city if either map has no entry for iso3166_1"]
+            UL5 --> UL6["GenerateUser(enriched_city, persona, sampled_name) via DataGenerator<br/>LLM receives EnrichedCity context + persona description + sampled name"]
+            UL6 --> UL7["PipelineLogger.Log(Info, UserGeneration, city, user_id, llm)"]
+            UL7 --> UL8["Send GeneratedUser → exp_ch"]
+            UL8 --> UL1
+            UL1 -- no --> UL9["Close exp_ch"]
+        end
+        subgraph U_SQL["SQLite Worker"]
+            US1["BEGIN TRANSACTION"] --> US2{"exp_ch has items?"}
+            US2 -- yes --> US3["Receive GeneratedUser"]
+            US3 --> US4["ProcessUser(user)"]
+            US4 --> US5["PipelineLogger.Log(Info, UserGeneration, city, user_id, sqlite)"]
+            US5 --> US6["Append → user_pool_"]
+            US6 --> US7{"Batch size reached?"}
+            US7 -- yes --> US8["COMMIT and BEGIN"] --> US2
+            US7 -- no --> US2
+            US2 -- no --> US9["COMMIT (Final)"]
+        end
+    end
+
+    UCreate --> UP1
+    UP2 -.->|loc_ch| UL1
+    UL9 -.->|exp_ch| US2
+    UL9 & US9 --> UserJoin["Orchestrator: Join LLM Worker, SQLite Worker"]
+
+    UserJoin --> BreweryPhase["Orchestrator: RunBreweryPhase(sampled_locations)"]
+    BreweryPhase --> BCreate["Create BoundedChannels (loc_ch, geo_ch, exp_ch)"]
+
+    subgraph BREWGEN["Phase 1a — Brewery Generation (concurrent)"]
+        direction LR
+        subgraph B_PROD["Orchestrator (producer)"]
+            BP1["Loop: sample User from user_pool_, pair with Location"]
+            BP1 --> BP2["Send BreweryTask(Location, User) → loc_ch"]
+            BP2 --> BP3["Close loc_ch"]
+        end
+        subgraph B_LLM["LLM Worker"]
+            BL1{"loc_ch has items?"}
+            BL1 -- yes --> BL2["Receive BreweryTask(Location, User)"]
+            BL2 --> BL3["GetLocationContextFromCache(task.location) — guaranteed cache hit"]
+            BL3 --> BL4["GenerateBrewery(enriched_city, context, task.user) via DataGenerator<br/>KV cache stays warm; brewery linked to sampled owner_user_id"]
+            BL4 --> BL5["PipelineLogger.Log(Info, BreweryGeneration, city, brewery_id, llm)"]
+            BL5 --> BL6["Send GeneratedBrewery → geo_ch"]
+            BL6 --> BL1
+            BL1 -- no --> BL7["Close geo_ch"]
+        end
+        subgraph B_GEO["Geocode Worker"]
+            BG1{"geo_ch has items?"}
+            BG1 -- yes --> BG2["Receive GeneratedBrewery"]
+            BG2 --> BG3["AddressService.ReverseGeocode(brewery.longitude, brewery.latitude)<br/>rate-limited independently of LLM throughput — NominatimAddressService sleeps 1s per request; MockAddressService (--mocked) returns a fixed placeholder, no network call"]
+            BG3 --> BG4{"Address resolved?"}
+            BG4 -- yes --> BG5["Attach resolved AddressLookupResult to brewery"]
+            BG4 -- no --> BG6["Log warning: could not reverse geocode; attach placeholder address_line1, empty postal_code — brewery is never dropped"]
+            BG5 --> BG7["PipelineLogger.Log(Info, BreweryGeneration, city, brewery_id, geocode)"]
+            BG6 --> BG7
+            BG7 --> BG8["Send GeneratedBrewery → exp_ch"]
+            BG8 --> BG1
+            BG1 -- no --> BG9["Close exp_ch"]
+        end
+        subgraph B_SQL["SQLite Worker"]
+            BS1["BEGIN TRANSACTION"] --> BS2{"exp_ch has items?"}
+            BS2 -- yes --> BS3["Receive GeneratedBrewery"]
+            BS3 --> BS4["ProcessBrewery(brewery)"]
+            BS4 --> BS5["PipelineLogger.Log(Info, BreweryGeneration, city, brewery_id, sqlite)"]
+            BS5 --> BS6["Append → brewery_pool_"]
+            BS6 --> BS7{"Batch size reached?"}
+            BS7 -- yes --> BS8["COMMIT and BEGIN"] --> BS2
+            BS7 -- no --> BS2
+            BS2 -- no --> BS9["COMMIT (Final)"]
+        end
+    end
+
+    BCreate --> BP1
+    BP3 -.->|loc_ch| BL1
+    BL7 -.->|geo_ch| BG1
+    BG9 -.->|exp_ch| BS2
+    BL7 & BG9 & BS9 --> BrewJoin["Orchestrator: Join LLM Worker, Geocode Worker, SQLite Worker<br/>brewery_pool_ is now fully populated"]
+
+    BrewJoin --> BeerPhase["Orchestrator: RunBeerPhase()"]
+    BeerPhase --> BeCreate["Create BoundedChannels (brew_ch, exp_ch)"]
+
+    subgraph BEERGEN["Phase 1b — Beer Generation (concurrent)"]
+        direction LR
+        subgraph BE_PROD["Orchestrator (producer)"]
+            BeP1["Loop: send Breweries → brew_ch"]
+            BeP1 --> BeP2["Close brew_ch"]
+        end
+        subgraph BE_LLM["LLM Worker"]
+            BeL1{"brew_ch has items?"}
+            BeL1 -- yes --> BeL2["Receive GeneratedBrewery"]
+            BeL2 --> BeL3["IBeerSelectionStrategy.SelectStyles(brewery, beer_style_palette_)"]
+            BeL3 --> BeL4{"For each selected BeerStyle"}
+            BeL4 -- remaining --> BeL5["GetStyleContextFromCache(style) — guaranteed cache hit; KV cache stays warm across all beer generations in this phase"]
+            BeL5 --> BeL6["GenerateBeer(brewery, style_context) via DataGenerator"]
+            BeL6 --> BeL7["Attach GeneratedBeer to bundle"] --> BeL4
+            BeL4 -- done --> BeL8["PipelineLogger.Log(Info, BeerGeneration, city, brewery_id, llm)"]
+            BeL8 --> BeL9["Send BeersBundle → exp_ch"]
+            BeL9 --> BeL1
+            BeL1 -- no --> BeL10["Close exp_ch"]
+        end
+        subgraph BE_SQL["SQLite Worker"]
+            BeS1["BEGIN TRANSACTION"] --> BeS2{"exp_ch has items?"}
+            BeS2 -- yes --> BeS3["Receive BeersBundle"]
+            BeS3 --> BeS4{"For each beer in bundle"}
+            BeS4 -- remaining --> BeS5["Set beer.brewery_id from bundle"]
+            BeS5 --> BeS6["ProcessBeer(beer)"]
+            BeS6 --> BeS7["Append → beer_pool_"] --> BeS4
+            BeS4 -- done --> BeS8["PipelineLogger.Log(Info, BeerGeneration, city, brewery_id, sqlite)"]
+            BeS8 --> BeS9{"Batch size reached?"}
+            BeS9 -- yes --> BeS10["COMMIT and BEGIN"] --> BeS2
+            BeS9 -- no --> BeS2
+            BeS2 -- no --> BeS11["COMMIT (Final)"]
+        end
+    end
+
+    BeCreate --> BeP1
+    BeP2 -.->|brew_ch| BeL1
+    BeL10 -.->|exp_ch| BeS2
+    BeL10 & BeS11 --> BeerJoin["Orchestrator: Join LLM Worker, SQLite Worker<br/>brewery_pool_ and beer_pool_ are now completely populated — Checkin and Follow phases may run in parallel"]
+
+    BeerJoin --> CheckinPhase["Orchestrator: RunCheckinPhase()"]
+    BeerJoin --> FollowPhase["Orchestrator: RunFollowPhase()"]
+
+    subgraph CHECKIN["Checkin Generation"]
+        CK1["ICheckinDistributionStrategy.AssignActivityWeights(user_pool_)<br/>weights seeded from persona.checkin_weight; J-curve profile emerges from persona distribution"]
+        CK1 --> CK2["BEGIN TRANSACTION"]
+        CK2 --> CK3{"For each GeneratedUser in user_pool_"}
+        CK3 -- remaining --> CK4["CheckinsForUser(user, brewery_pool_.size())"]
+        CK4 --> CK5{"For each checkin index"}
+        CK5 -- remaining --> CK6["TimestampFor(user, index)"]
+        CK6 --> CK7["Select brewery from brewery_pool_"]
+        CK7 --> CK8["GenerateCheckin(user, brewery, timestamp) via DataGenerator"]
+        CK8 --> CK9["ProcessCheckin(checkin)"]
+        CK9 --> CK10["PipelineLogger.Log(Info, CheckinGeneration, nullopt, checkin_id, sqlite)"]
+        CK10 --> CK11["Append → checkin_pool_"]
+        CK11 --> CK12{"Batch size reached?"}
+        CK12 -- yes --> CK13["COMMIT and BEGIN"] --> CK5
+        CK12 -- no --> CK5
+        CK5 -- done --> CK3
+        CK3 -- done --> CK14["COMMIT (Final)"]
+    end
+
+    subgraph FOLLOW["Follow Generation"]
+        FL1["IFollowGenerationStrategy.AssignFollowWeights(user_pool_)<br/>RandomFollowStrategy: uniform weights; ActivityWeightedFollowStrategy: derived from user.activity_weight so high-activity users attract more followers"]
+        FL1 --> FL2["BEGIN TRANSACTION"]
+        FL2 --> FL3["IFollowGenerationStrategy.GenerateFollows(user_pool_)<br/>self-follow constraint (follower_id != followed_id) enforced here and at the DB schema level"]
+        FL3 --> FL4{"For each GeneratedFollow"}
+        FL4 -- remaining --> FL5["ProcessFollow(follow)"]
+        FL5 --> FL6["PipelineLogger.Log(Info, FollowGeneration, nullopt, follower_id, sqlite)"]
+        FL6 --> FL7["Append → follow_pool_"]
+        FL7 --> FL8{"Batch size reached?"}
+        FL8 -- yes --> FL9["COMMIT and BEGIN"] --> FL4
+        FL8 -- no --> FL4
+        FL4 -- done --> FL10["COMMIT (Final)"]
+    end
+
+    CheckinPhase --> CK1
+    FollowPhase --> FL1
+    CK14 & FL10 --> PhaseJoin["Orchestrator: Join CheckinPhase, FollowPhase<br/>checkin_pool_ and follow_pool_ are now fully populated"]
+
+    PhaseJoin --> RatingPhase["Orchestrator: RunRatingPhase()<br/>beer selection biased by user.persona.style_affinities and abv_range; rating skew modulated per persona"]
+    RatingPhase --> RT1["BEGIN TRANSACTION"]
+    RT1 --> RT2{"For each GeneratedCheckin in checkin_pool_"}
+    RT2 -- remaining --> RT3["Match brewery_id, select beer from beer_pool_ (same brewery_id, biased by persona affinities)"]
+    RT3 --> RT4{"Beer exists for brewery?"}
+    RT4 -- yes --> RT5["GenerateRating(user, beer, checkin_id) via DataGenerator"]
+    RT5 --> RT6["ProcessRating(rating)"]
+    RT6 --> RT7["PipelineLogger.Log(Info, RatingGeneration, nullopt, rating_id, sqlite)"]
+    RT7 --> RT8{"Batch size reached?"}
+    RT8 -- yes --> RT9["COMMIT and BEGIN"] --> RT2
+    RT8 -- no --> RT2
+    RT4 -- no --> RT10["Log warning; skip — brewery has no beers"] --> RT2
+    RT2 -- done --> RT11["COMMIT (Final)"]
+
+    RT11 --> Teardown["Orchestrator: Finalize SqliteExportService — safely closes the DB connection"]
+    Teardown --> CloseLogCh["Orchestrator: close log_ch"]
+    CloseLogCh --> MainDone["Main: spdlog::info 'Pipeline complete in X ms'"]
+    MainDone --> JoinLog["Main: Join Log Worker — drain guarantees no LogEntry is dropped at shutdown"]
+    JoinLog --> Stop2([stop])

docs/pipeline/diagrams/planned/class.md

@@ -0,0 +1,17 @@
+# Biergarten Data Pipeline — Class Diagram (Planned)
+
+```mermaid
+--8<-- "pipeline/diagrams/planned/class.mmd"
+```
+
+## Notes
+
+- `Logger`, `PipelineLogger`, and `LogWorker` are referenced only in
+  relationships in the source PlantUML (not given their own class blocks there
+  either) — they appear here as implicit nodes for the same reason.
+- Package grouping from the PlantUML source (`Domain: Models`,
+  `Domain: Application Configuration`, `Domain: Policy`,
+  `Infrastructure: Logging`, `Infrastructure: Pipeline Channel`,
+  `Infrastructure: Data Preloading`, `Infrastructure: Enrichment`,
+  `Infrastructure: Prompting`, `Infrastructure: Data Generation`,
+  `Infrastructure: Data Export`) is preserved as Mermaid `namespace` blocks.

docs/pipeline/diagrams/planned/class.mmd

@@ -0,0 +1,647 @@
+---
+config:
+    layout: elk
+---
+classDiagram
+    namespace DomainModels {
+        class Location {
+            +string city
+            +string state_province
+            +string iso3166_2
+            +string country
+            +string iso3166_1
+            +vector~string~ local_languages
+            +double latitude
+            +double longitude
+        }
+
+        class LocationContext {
+            +string text
+            +Completeness completeness
+            +size_t char_count
+        }
+
+        class Completeness {
+            <<enumeration>>
+            Full
+            Partial
+            Absent
+        }
+
+        class EnrichedCity {
+            +Location location
+            +LocationContext context
+        }
+
+        class BeerStyle {
+            +string name
+            +string description
+            +float min_abv
+            +float max_abv
+            +int min_ibu
+            +int max_ibu
+        }
+
+        class BreweryResult {
+            +string name_en
+            +string description_en
+            +string name_local
+            +string description_local
+        }
+
+        class BeerResult {
+            +string name_en
+            +string description_en
+            +string name_local
+            +string description_local
+            +string style
+            +float abv
+            +int ibu
+        }
+
+        class UserResult {
+            +string first_name
+            +string last_name
+            +string gender
+            +string username
+            +string bio
+            +float activity_weight
+        }
+
+        class Name {
+            +string first_name
+            +string last_name
+            +string gender
+        }
+
+        class ForenameEntry {
+            +string name
+            +string gender
+        }
+
+        class CheckinResult {
+            +string checked_in_at
+            +string note
+        }
+
+        class RatingResult {
+            +float score
+            +string note
+        }
+
+        class GenerationMetadata {
+            +uint64_t generation_id
+            +string generated_time
+            +bool context_provided
+            +string generated_with
+        }
+
+        class GeneratedBrewery {
+            +uint64_t brewery_id
+            +Location location
+            +BreweryResult brewery
+            +Completeness context_completeness
+            +GenerationMetadata metadata
+        }
+
+        class GeneratedBeer {
+            +uint64_t beer_id
+            +uint64_t brewery_id
+            +Location location
+            +BeerStyle style
+            +BeerResult beer
+            +GenerationMetadata metadata
+        }
+
+        class GeneratedUser {
+            +uint64_t user_id
+            +Location location
+            +UserResult user
+            +string email
+            +string date_of_birth
+            +string password
+            +GenerationMetadata metadata
+        }
+
+        class GeneratedCheckin {
+            +uint64_t checkin_id
+            +uint64_t user_id
+            +uint64_t brewery_id
+            +CheckinResult checkin
+            +GenerationMetadata metadata
+        }
+
+        class GeneratedRating {
+            +uint64_t user_id
+            +uint64_t beer_id
+            +uint64_t checkin_id
+            +RatingResult rating
+            +GenerationMetadata metadata
+        }
+
+        class GeneratedFollow {
+            +uint64_t follower_id
+            +uint64_t followed_id
+            +GenerationMetadata metadata
+        }
+
+        class UserPersona {
+            +string name
+            +string description
+            +vector~string~ style_affinities
+        }
+    }
+    note for ForenameEntry "forename_list/surname_list are unordered_set aliases, keyed by ISO 3166-1 country code via ICuratedDataService. SampleName() is a free function, not a method, sourced from popular-names-by-country-dataset (CC0)."
+    note for GeneratedUser "email, date_of_birth, and password are generated programmatically by the orchestrator (not LLM-authored) so a downstream auth-account seeding consumer can register real accounts from this export."
+    ForenameEntry ..> Name : SampleName() produces
+    LocationContext *-- Completeness
+
+    namespace DomainApplicationConfiguration {
+        class SamplingOptions {
+            +float temperature
+            +float top_p
+            +uint32_t top_k
+            +uint32_t n_ctx
+            +int seed
+        }
+
+        class GeneratorMode {
+            <<enumeration>>
+            kMock
+            kLlama
+            kOpenAI
+        }
+
+        class GeneratorOptions {
+            +path model_path
+            +GeneratorMode mode
+            +optional~SamplingOptions~ sampling
+            +string openai_api_key
+            +string openai_model
+        }
+
+        class PipelineOptions {
+            +path output_path
+            +path log_path
+        }
+
+        class ApplicationOptions {
+            +GeneratorOptions generator
+            +PipelineOptions pipeline
+        }
+    }
+    note for GeneratorOptions "Already implemented (models.h), not planned: the three-way GeneratorMode split (kMock/kLlama/kOpenAI) and the openai_api_key/openai_model fields ship today, ahead of the rest of this diagram."
+    ApplicationOptions *-- GeneratorOptions
+    ApplicationOptions *-- PipelineOptions
+    GeneratorOptions *-- GeneratorMode
+    GeneratorOptions o-- SamplingOptions
+
+    namespace DomainPolicy {
+        class ContextStrategy {
+            <<interface>>
+            +QueriesFor(loc) vector~string~
+            +MaxContextChars() size_t
+        }
+
+        class BreweryContextStrategy {
+            +QueriesFor(loc) vector~string~
+            +MaxContextChars() size_t
+        }
+
+        class BeerContextStrategy {
+            +QueriesFor(loc) vector~string~
+            +MaxContextChars() size_t
+        }
+
+        class SamplingStrategy {
+            <<interface>>
+            +Sample(locations) vector~Location~
+        }
+
+        class UniformSamplingStrategy {
+            -size_t sample_size_
+            +Sample(locations) vector~Location~
+        }
+
+        class BeerSelectionStrategy {
+            <<interface>>
+            +SelectStyles(brewery, palette) vector~BeerStyle~
+        }
+
+        class RandomBeerSelectionStrategy {
+            -mt19937 rng_
+            -size_t min_beers_
+            -size_t max_beers_
+            +SelectStyles(brewery, palette) vector~BeerStyle~
+        }
+
+        class CheckinDistributionStrategy {
+            <<interface>>
+            +AssignActivityWeights(users) void
+            +CheckinsForUser(user, brewery_count) size_t
+            +TimestampFor(user, index) string
+        }
+
+        class JCurveCheckinStrategy {
+            -mt19937 rng_
+            +AssignActivityWeights(users) void
+            +CheckinsForUser(user, brewery_count) size_t
+            +TimestampFor(user, index) string
+        }
+
+        class RandomCheckinStrategy {
+            -mt19937 rng_
+            -size_t min_checkins_
+            -size_t max_checkins_
+            +AssignActivityWeights(users) void
+            +CheckinsForUser(user, brewery_count) size_t
+            +TimestampFor(user, index) string
+        }
+
+        class FollowGenerationStrategy {
+            <<interface>>
+            +GenerateFollows(users) vector~GeneratedFollow~
+        }
+
+        class RandomFollowStrategy {
+            -mt19937 rng_
+            -size_t min_follows_
+            -size_t max_follows_
+            +GenerateFollows(users) vector~GeneratedFollow~
+        }
+
+        class ActivityWeightedFollowStrategy {
+            -mt19937 rng_
+            -size_t min_follows_
+            -size_t max_follows_
+            +GenerateFollows(users) vector~GeneratedFollow~
+        }
+    }
+
+    namespace InfrastructureLogging {
+        class LogLevel {
+            <<enumeration>>
+            Debug
+            Info
+            Warn
+            Error
+        }
+
+        class PipelinePhase {
+            <<enumeration>>
+            Startup
+            UserGeneration
+            BreweryAndBeerGeneration
+            CheckinGeneration
+            RatingGeneration
+            FollowGeneration
+            Teardown
+        }
+
+        class LogEntry {
+            +time_point timestamp
+            +LogLevel level
+            +PipelinePhase phase
+            +string message
+            +optional~string~ worker
+        }
+
+        class ILogger {
+            <<interface>>
+            +Log(entry) void
+        }
+
+        class LogProducer {
+            -BoundedChannel~LogEntry~ channel_
+            +Log(entry) void
+        }
+
+        class LogDispatcher {
+            -BoundedChannel~LogEntry~ channel_
+            +Run() void
+            -ToSpdlogLevel(level) level_enum
+        }
+    }
+    LogEntry *-- LogLevel
+    LogEntry *-- PipelinePhase
+    ILogger <|.. LogProducer
+    LogProducer ..> LogEntry : emits
+    LogDispatcher ..> LogEntry : consumes
+
+    namespace InfrastructurePipelineChannel {
+        class BoundedChannel~T~ {
+            -queue~T~ queue_
+            -mutex mutex_
+            -condition_variable not_full_
+            -condition_variable not_empty_
+            -size_t capacity_
+            -bool closed_
+            +Send(item) void
+            +Receive() optional~T~
+            +Close() void
+        }
+    }
+
+    namespace InfrastructureDataPreloading {
+        class ICuratedDataService {
+            <<interface>>
+            +LoadLocations(filepath) vector~Location~
+            +LoadBeerStyles(filepath) vector~BeerStyle~
+            +LoadPersonas(filepath) vector~UserPersona~
+            +LoadForenamesByCountry(filepath) unordered_map~string, forename_list~
+            +LoadSurnamesByCountry(filepath) unordered_map~string, surname_list~
+        }
+
+        class JsonLoader {
+            +LoadLocations(filepath) vector~Location~
+            +LoadBeerStyles(filepath) vector~BeerStyle~
+            +LoadPersonas(filepath) vector~UserPersona~
+            +LoadForenamesByCountry(filepath) unordered_map~string, forename_list~
+            +LoadSurnamesByCountry(filepath) unordered_map~string, surname_list~
+        }
+
+        class MockCuratedDataService {
+            +LoadLocations(filepath) vector~Location~
+            +LoadBeerStyles(filepath) vector~BeerStyle~
+            +LoadPersonas(filepath) vector~UserPersona~
+            +LoadForenamesByCountry(filepath) unordered_map~string, forename_list~
+            +LoadSurnamesByCountry(filepath) unordered_map~string, surname_list~
+        }
+    }
+    note for JsonLoader "Each Load* call is memoized after its first parse — implemented today, ahead of LoadBeerStyles which is still planned."
+    note for MockCuratedDataService "Fixed in-memory dataset for --mocked mode, implemented today for Locations/Personas/Forenames/Surnames; would need a LoadBeerStyles fixture too once that method is implemented."
+
+    namespace InfrastructureEnrichment {
+        class EnrichmentService {
+            <<interface>>
+            +GetLocationContext(loc, strategy) LocationContext
+        }
+
+        class WikipediaService {
+            -unique_ptr~WebClient~ client_
+            -unordered_map~string, string~ extract_cache_
+            +GetLocationContext(loc, strategy) LocationContext
+            -FetchExtract(query) string
+        }
+
+        class WebClient {
+            <<interface>>
+            +Get(url) string
+            +UrlEncode(value) string
+        }
+
+        class HttpWebClient {
+            +Get(url) string
+            +UrlEncode(value) string
+        }
+    }
+
+    namespace InfrastructureGeocoding {
+        class AddressLookupResult {
+            +string address_line1
+            +string postal_code
+        }
+
+        class AddressService {
+            <<interface>>
+            +ReverseGeocode(longitude, latitude) optional~AddressLookupResult~
+        }
+
+        class NominatimAddressService {
+            -unique_ptr~WebClient~ client_
+            -Logger logger_
+            +ReverseGeocode(longitude, latitude) optional~AddressLookupResult~
+        }
+
+        class MockAddressService {
+            +ReverseGeocode(longitude, latitude) optional~AddressLookupResult~
+        }
+    }
+    note for NominatimAddressService "Already implemented (services/address/), not planned: queries the public Nominatim API, sleeping 1s per request per its usage policy; returns nullopt on failure or when no usable street address is found. Ships today, ahead of the rest of this diagram."
+    note for MockAddressService "Already implemented, not planned: returns a fixed placeholder address ('123 Mock Street', '00000') for --mocked runs, no network call."
+    AddressService <|.. NominatimAddressService
+    AddressService <|.. MockAddressService
+    AddressService ..> AddressLookupResult : returns
+    NominatimAddressService *-- WebClient
+
+    namespace InfrastructurePrompting {
+        class IPromptDirectory {
+            <<interface>>
+            +Load(key) string
+        }
+
+        class PromptDirectory {
+            -path prompt_dir_
+            -unordered_map~string, string~ cache_
+            +PromptDirectory(prompt_dir)
+            +Load(key) string
+        }
+    }
+    IPromptDirectory <|.. PromptDirectory
+
+    namespace InfrastructureDataGeneration {
+        class DataGenerator {
+            <<interface>>
+            +GenerateBrewery(location, context) BreweryResult
+            +GenerateBeer(brewery_id, location, context, style) BeerResult
+            +GenerateUser(city, persona, name) UserResult
+            +GenerateCheckin(user, brewery, timestamp) CheckinResult
+            +GenerateRating(user, beer, checkin_id) RatingResult
+        }
+
+        class MockGenerator {
+            +GenerateBrewery(...) BreweryResult
+            +GenerateBeer(...) BeerResult
+            +GenerateUser(...) UserResult
+            +GenerateCheckin(...) CheckinResult
+            +GenerateRating(...) RatingResult
+            -DeterministicHash(location) size_t
+        }
+
+        class LlamaGenerator {
+            -ModelHandle model_
+            -ContextHandle context_
+            -unique_ptr~PromptFormatter~ prompt_formatter_
+            -unique_ptr~IPromptDirectory~ prompt_directory_
+            -mt19937 rng_
+            +GenerateBrewery(...) BreweryResult
+            +GenerateBeer(...) BeerResult
+            +GenerateUser(...) UserResult
+            +GenerateCheckin(...) CheckinResult
+            +GenerateRating(...) RatingResult
+            -Load(opts) void
+            -Infer(system_prompt, user_prompt, max_tokens, grammar) string
+            -ValidateModelArchitecture() void
+        }
+
+        class PromptFormatter {
+            <<interface>>
+            +Format(system_prompt, user_prompt) string
+            +ExpectedArchitecture() string_view
+        }
+
+        class Gemma4JinjaPromptFormatter {
+            +Format(system_prompt, user_prompt) string
+            +ExpectedArchitecture() string_view
+        }
+
+        class OpenAIGenerator {
+            -string api_key_
+            -string model_
+            -Logger logger_
+            -unique_ptr~IPromptDirectory~ prompt_directory_
+            -unique_ptr~WebClient~ web_client_
+            +GenerateBrewery(location, context) BreweryResult
+            +GenerateBeer(brewery_id, location, context, style) BeerResult
+            +GenerateUser(city, persona, name) UserResult
+            +GenerateCheckin(user, brewery, timestamp) CheckinResult
+            +GenerateRating(user, beer, checkin_id) RatingResult
+            -CallChatCompletionsApi(...) string
+        }
+    }
+    note for OpenAIGenerator "Already implemented (data_generation/openai/), not planned: calls the OpenAI Chat Completions API with Structured Outputs (json_schema, strict) to guarantee schema-valid JSON, needing no IPromptFormatter or GBNF grammar. Ships today for GenerateBrewery/GenerateUser only, ahead of the rest of this diagram — GenerateBeer/GenerateCheckin/GenerateRating are shown here for interface completeness but not yet implemented on any backend."
+
+    namespace InfrastructureDataExport {
+        class ExportService {
+            <<interface>>
+            +Initialize() void
+            +ProcessBrewery(brewery) uint64_t
+            +ProcessBeer(beer) uint64_t
+            +ProcessUser(user) uint64_t
+            +ProcessCheckin(checkin) uint64_t
+            +ProcessRating(rating) void
+            +ProcessFollow(follow) void
+            +Finalize() void
+        }
+
+        class SqliteExportService {
+            -unique_ptr~DateTimeProvider~ date_time_provider_
+            -SqliteDatabaseHandle db_handle_
+            -SqliteStatementHandle insert_location_stmt_
+            -SqliteStatementHandle insert_brewery_stmt_
+            -SqliteStatementHandle insert_beer_stmt_
+            -SqliteStatementHandle insert_user_stmt_
+            -SqliteStatementHandle insert_checkin_stmt_
+            -SqliteStatementHandle insert_rating_stmt_
+            -SqliteStatementHandle insert_follow_stmt_
+            -bool transaction_open_
+            -unordered_map~string, uint64_t~ location_cache_
+            -unordered_map~string, uint64_t~ brewery_cache_
+            +Initialize() void
+            +ProcessRecord(brewery) uint64_t
+            +ProcessRecord(beer) uint64_t
+            +ProcessRecord(user) uint64_t
+            +ProcessRecord(checkin) uint64_t
+            +ProcessRecord(rating) void
+            +ProcessRecord(follow) void
+            +Finalize() void
+            -InitializeSchema() void
+            -PrepareStatements() void
+            -RollbackAndCloseNoThrow() void
+            -FinalizeStatements() void
+        }
+
+        class DateTimeProvider {
+            <<interface>>
+            +GetUtcTimestamp() string
+        }
+
+        class SystemDateTimeProvider {
+            +GetUtcTimestamp() string
+        }
+    }
+
+    class BiergartenPipelineOrchestrator {
+        -unique_ptr~ICuratedDataService~ curated_data_service_
+        -unique_ptr~EnrichmentService~ enrichment_service_
+        -unique_ptr~DataGenerator~ generator_
+        -unique_ptr~Logger~ logger_
+        -unique_ptr~ExportService~ exporter_
+        -unique_ptr~AddressService~ address_service_
+        -unique_ptr~ContextStrategy~ brewery_context_strategy_
+        -unique_ptr~SamplingStrategy~ sampling_strategy_
+        -unique_ptr~BeerSelectionStrategy~ beer_selection_strategy_
+        -unique_ptr~CheckinDistributionStrategy~ checkin_strategy_
+        -unique_ptr~FollowGenerationStrategy~ follow_strategy_
+        -vector~BeerStyle~ beer_style_palette_
+        -ApplicationOptions options_
+        -vector~GeneratedUser~ user_pool_
+        -vector~GeneratedBrewery~ brewery_pool_
+        -vector~GeneratedBeer~ beer_pool_
+        -vector~GeneratedCheckin~ checkin_pool_
+        -vector~GeneratedFollow~ follow_pool_
+        +Run() bool
+        -RunUserPhase(locations) void
+        -RunBreweryAndBeerPhase(locations) void
+        -RunCheckinPhase() void
+        -RunRatingPhase() void
+        -RunFollowPhase() void
+    }
+
+    BiergartenPipelineOrchestrator *-- ICuratedDataService
+    BiergartenPipelineOrchestrator *-- EnrichmentService
+    BiergartenPipelineOrchestrator *-- DataGenerator
+    BiergartenPipelineOrchestrator *-- ExportService
+    BiergartenPipelineOrchestrator *-- AddressService
+    BiergartenPipelineOrchestrator *-- CheckinDistributionStrategy
+    BiergartenPipelineOrchestrator *-- FollowGenerationStrategy
+    BiergartenPipelineOrchestrator *-- SamplingStrategy
+    BiergartenPipelineOrchestrator *-- BeerSelectionStrategy
+    BiergartenPipelineOrchestrator *-- ApplicationOptions
+    BiergartenPipelineOrchestrator *-- Logger
+
+    BiergartenPipelineOrchestrator "1" *-- "0..*" GeneratedUser : user_pool_
+    BiergartenPipelineOrchestrator "1" *-- "0..*" GeneratedBrewery : brewery_pool_
+    BiergartenPipelineOrchestrator "1" *-- "0..*" GeneratedBeer : beer_pool_
+    BiergartenPipelineOrchestrator "1" *-- "0..*" GeneratedCheckin : checkin_pool_
+    BiergartenPipelineOrchestrator "1" *-- "0..*" GeneratedFollow : follow_pool_
+
+    ICuratedDataService <|.. JsonLoader
+    ICuratedDataService <|.. MockCuratedDataService
+    Logger <|.. PipelineLogger
+    ContextStrategy <|.. BreweryContextStrategy
+    ContextStrategy <|.. BeerContextStrategy
+    SamplingStrategy <|.. UniformSamplingStrategy
+    BeerSelectionStrategy <|.. RandomBeerSelectionStrategy
+    CheckinDistributionStrategy <|.. JCurveCheckinStrategy
+    CheckinDistributionStrategy <|.. RandomCheckinStrategy
+    FollowGenerationStrategy <|.. RandomFollowStrategy
+    FollowGenerationStrategy <|.. ActivityWeightedFollowStrategy
+    EnrichmentService <|.. WikipediaService
+    WebClient <|.. HttpWebClient
+    DataGenerator <|.. MockGenerator
+    DataGenerator <|.. LlamaGenerator
+    DataGenerator <|.. OpenAIGenerator
+    PromptFormatter <|.. Gemma4JinjaPromptFormatter
+    ExportService <|.. SqliteExportService
+    DateTimeProvider <|.. SystemDateTimeProvider
+
+    WikipediaService *-- WebClient
+    WikipediaService ..> ContextStrategy
+    LlamaGenerator *-- PromptFormatter
+    LlamaGenerator *-- IPromptDirectory
+    LlamaGenerator ..> GeneratorOptions
+    OpenAIGenerator *-- IPromptDirectory
+    OpenAIGenerator *-- WebClient
+    SqliteExportService *-- DateTimeProvider
+
+    PipelineLogger o-- BoundedChannel : logs to
+    LogWorker o-- BoundedChannel : drains from
+
+    EnrichedCity *-- Location
+    EnrichedCity *-- LocationContext
+    GeneratedBrewery *-- Location
+    GeneratedBrewery *-- BreweryResult
+    GeneratedBrewery *-- GenerationMetadata
+    GeneratedBeer *-- Location
+    GeneratedBeer *-- BeerStyle
+    GeneratedBeer *-- BeerResult
+    GeneratedBeer *-- GenerationMetadata
+    GeneratedUser *-- Location
+    GeneratedUser *-- UserResult
+    GeneratedUser *-- GenerationMetadata
+    GeneratedCheckin *-- CheckinResult
+    GeneratedCheckin *-- GenerationMetadata
+    GeneratedRating *-- RatingResult
+    GeneratedRating *-- GenerationMetadata
+    GeneratedFollow *-- GenerationMetadata

docs/testing.md

@@ -1,340 +0,0 @@
-# Testing
-
-This document describes the testing strategy and how to run tests for The Biergarten App.
-
-## Overview
-
-The project uses a multi-layered testing approach across backend and frontend:
-
-- **API.Specs** - BDD integration tests using Reqnroll (Gherkin)
-- **Infrastructure.Repository.Tests** - Unit tests for data access layer
-- **Service.Auth.Tests** - Unit tests for authentication business logic
-- **Storybook Vitest project** - Browser-based interaction tests for shared website stories
-- **Storybook Playwright suite** - Browser checks against Storybook-rendered components
-
-## Running Tests with Docker (Recommended)
-
-The easiest way to run all tests is using Docker Compose, which sets up an isolated test
-environment:
-
-```bash
-docker compose -f docker-compose.test.yaml up --abort-on-container-exit
-```
-
-This command:
-
-1. Starts a fresh SQL Server instance
-2. Runs database migrations
-3. Seeds test data
-4. Executes all test suites in parallel
-5. Exports results to `./test-results/`
-6. Exits when tests complete
-
-### View Test Results
-
-```bash
-# List test result files
-ls -la test-results/
-
-# View specific test results
-cat test-results/api-specs/results.trx
-cat test-results/repository-tests/results.trx
-cat test-results/service-auth-tests/results.trx
-```
-
-### Clean Up
-
-```bash
-# Remove test containers and volumes
-docker compose -f docker-compose.test.yaml down -v
-```
-
-## Running Tests Locally
-
-You can run individual test projects locally without Docker:
-
-### Integration Tests (API.Specs)
-
-```bash
-cd src/Core
-dotnet test API/API.Specs/API.Specs.csproj
-```
-
-**Requirements**:
-
-- SQL Server instance running
-- Database migrated and seeded
-- Environment variables set (DB connection, JWT secret)
-
-### Repository Tests
-
-```bash
-cd src/Core
-dotnet test Infrastructure/Infrastructure.Repository.Tests/Infrastructure.Repository.Tests.csproj
-```
-
-**Requirements**:
-
-- SQL Server instance running (uses mock data)
-
-### Service Tests
-
-```bash
-cd src/Core
-dotnet test Service/Service.Auth.Tests/Service.Auth.Tests.csproj
-```
-
-**Requirements**:
-
-- No database required (uses Moq for mocking)
-
-### Frontend Storybook Tests
-
-```bash
-cd src/Website
-npm install
-npm run test:storybook
-```
-
-**Purpose**:
-
-- Verifies shared stories such as form fields, submit buttons, navbar states, toasts, and the theme gallery
-- Runs in browser mode via Vitest and Storybook integration
-
-### Frontend Playwright Storybook Tests
-
-```bash
-cd src/Website
-npm install
-npm run test:storybook:playwright
-```
-
-**Requirements**:
-
-- Storybook dependencies installed
-- Playwright browser dependencies installed
-- The command will start or reuse the Storybook server defined in `playwright.storybook.config.ts`
-
-## Test Coverage
-
-### Current Coverage
-
-**Authentication & User Management**:
-
-- User registration with validation
-- User login with JWT token generation
-- Password hashing and verification (Argon2id)
-- JWT token generation and claims
-- Invalid credentials handling
-- 404 error responses
-
-**Repository Layer**:
-
-- User account creation
-- User credential management
-- GetUserByUsername queries
-- Stored procedure execution
-
-**Service Layer**:
-
-- Login service with password verification
-- Register service with validation
-- Business logic for authentication flow
-
-**Frontend UI Coverage**:
-
-- Shared submit button states
-- Form field happy path and error presentation
-- Navbar guest, authenticated, and mobile behavior
-- Theme gallery rendering across Biergarten themes
-- Toast interactions and themed notification display
-
-### Planned Coverage
-
-- [ ] Email verification workflow
-- [ ] Password reset functionality
-- [ ] Token refresh mechanism
-- [ ] Brewery data management
-- [ ] Beer post operations
-- [ ] User follow/unfollow
-- [ ] Image upload service
-- [ ] Frontend route integration coverage beyond Storybook stories
-
-## Testing Frameworks & Tools
-
-### xUnit
-
-- Primary unit testing framework
-- Used for Repository and Service layer tests
-- Supports parallel test execution
-
-### Reqnroll (Gherkin/BDD)
-
-- Behavior-driven development framework
-- Used for API integration tests
-- Human-readable test scenarios in `.feature` files
-
-### FluentAssertions
-
-- Expressive assertion library
-- Makes test assertions more readable
-- Used across all test projects
-
-### Moq
-
-- Mocking framework for .NET
-- Used in Service layer tests
-- Enables isolated unit testing
-
-### DbMocker
-
-- Database mocking for repository tests
-- Simulates SQL Server responses
-- No real database required for unit tests
-
-## Test Structure
-
-### API.Specs (Integration Tests)
-
-```
-API.Specs/
-├── Features/
-│   ├── Authentication.feature          # Login/register scenarios
-│   └── UserManagement.feature          # User CRUD scenarios
-├── Steps/
-│   ├── AuthenticationSteps.cs          # Step definitions
-│   └── UserManagementSteps.cs
-└── Mocks/
-    └── TestApiFactory.cs               # Test server setup
-```
-
-**Example Feature**:
-
-```gherkin
-Feature: User Authentication
-  As a user
-  I want to register and login
-  So that I can access the platform
-
-Scenario: Successful user registration
-  Given I have valid registration details
-  When I register a new account
-  Then I should receive a JWT token
-  And my account should be created
-```
-
-### Infrastructure.Repository.Tests
-
-```
-Infrastructure.Repository.Tests/
-├── AuthRepositoryTests.cs              # Auth repository tests
-├── UserAccountRepositoryTests.cs       # User account tests
-└── TestFixtures/
-    └── DatabaseFixture.cs              # Shared test setup
-```
-
-### Service.Auth.Tests
-
-```
-Service.Auth.Tests/
-├── LoginService.test.cs                # Login business logic tests
-└── RegisterService.test.cs             # Registration business logic tests
-```
-
-## Writing Tests
-
-### Unit Test Example (xUnit)
-
-```csharp
-public class LoginServiceTests
-{
-    [Fact]
-    public async Task LoginAsync_ValidCredentials_ReturnsToken()
-    {
-        // Arrange
-        var mockRepo = new Mock<IAuthRepository>();
-        var mockJwt = new Mock<IJwtService>();
-        var service = new AuthService(mockRepo.Object, mockJwt.Object);
-
-        // Act
-        var result = await service.LoginAsync("testuser", "password123");
-
-        // Assert
-        result.Should().NotBeNull();
-        result.Token.Should().NotBeNullOrEmpty();
-    }
-}
-```
-
-### Integration Test Example (Reqnroll)
-
-```gherkin
-Scenario: User login with valid credentials
-  Given a registered user with username "testuser"
-  When I POST to "/api/auth/login" with valid credentials
-  Then the response status should be 200
-  And the response should contain a JWT token
-```
-
-## Continuous Integration
-
-Tests run automatically in CI/CD pipelines using the test Docker Compose configuration:
-
-```bash
-# CI/CD command
-docker compose -f docker-compose.test.yaml build
-docker compose -f docker-compose.test.yaml up --abort-on-container-exit
-docker compose -f docker-compose.test.yaml down -v
-```
-
-Exit codes:
-
-- `0` - All tests passed
-- Non-zero - Test failures occurred
-
-Frontend UI checks should also be included in CI for the active website workspace:
-
-```bash
-cd src/Website
-npm ci
-npm run test:storybook
-npm run test:storybook:playwright
-```
-
-## Troubleshooting
-
-### Tests Failing Due to Database Connection
-
-Ensure SQL Server is running and environment variables are set:
-
-```bash
-docker compose -f docker-compose.test.yaml ps
-```
-
-### Port Conflicts
-
-If port 1433 is in use, stop other SQL Server instances or modify the port in
-`docker-compose.test.yaml`.
-
-### Stale Test Data
-
-Clean up test database:
-
-```bash
-docker compose -f docker-compose.test.yaml down -v
-```
-
-### View Container Logs
-
-```bash
-docker compose -f docker-compose.test.yaml logs <service-name>
-```
-
-## Best Practices
-
-1. **Isolation**: Each test should be independent and not rely on other tests
-2. **Cleanup**: Use fixtures and dispose patterns for resource cleanup
-3. **Mocking**: Mock external dependencies in unit tests
-4. **Descriptive Names**: Use clear, descriptive test method names
-5. **Arrange-Act-Assert**: Follow AAA pattern in unit tests
-6. **Given-When-Then**: Follow GWT pattern in BDD scenarios

docs/token-validation.md

@@ -1,205 +0,0 @@
-# Token Validation Architecture
-
-## Overview
-
-The Core project implements comprehensive JWT token validation across three token types:
-
-- **Access Tokens**: Short-lived (1 hour) tokens for API authentication
-- **Refresh Tokens**: Long-lived (21 days) tokens for obtaining new access tokens
-- **Confirmation Tokens**: Short-lived (30 minutes) tokens for email confirmation
-
-## Components
-
-### Infrastructure Layer
-
-#### [ITokenInfrastructure](Infrastructure.Jwt/ITokenInfrastructure.cs)
-
-Low-level JWT operations.
-
-**Methods:**
-- `GenerateJwt()` - Creates signed JWT tokens
-- `ValidateJwtAsync()` - Validates token signature, expiration, and format
-
-**Implementation:** [JwtInfrastructure.cs](Infrastructure.Jwt/JwtInfrastructure.cs)
-- Uses Microsoft.IdentityModel.JsonWebTokens.JsonWebTokenHandler
-- Algorithm: HS256 (HMAC-SHA256)
-- Validates token lifetime, signature, and well-formedness
-
-### Service Layer
-
-#### [ITokenValidationService](Service.Auth/ITokenValidationService.cs)
-
-High-level token validation with context (token type, user extraction).
-
-**Methods:**
-- `ValidateAccessTokenAsync(string token)` - Validates access tokens
-- `ValidateRefreshTokenAsync(string token)` - Validates refresh tokens
-- `ValidateConfirmationTokenAsync(string token)` - Validates confirmation tokens
-
-**Returns:** `ValidatedToken` record containing:
-- `UserId` (Guid)
-- `Username` (string)
-- `Principal` (ClaimsPrincipal) - Full JWT claims
-
-**Implementation:** [TokenValidationService.cs](Service.Auth/TokenValidationService.cs)
-- Reads token secrets from environment variables
-- Extracts and validates claims (Sub, UniqueName)
-- Throws `UnauthorizedException` on validation failure
-
-#### [ITokenService](Service.Auth/ITokenService.cs)
-
-Token generation (existing service extended).
-
-**Methods:**
-- `GenerateAccessToken(UserAccount)` - Creates 1-hour access token
-- `GenerateRefreshToken(UserAccount)` - Creates 21-day refresh token
-- `GenerateConfirmationToken(UserAccount)` - Creates 30-minute confirmation token
-
-### Integration Points
-
-#### [ConfirmationService](Service.Auth/IConfirmationService.cs)
-
-**Flow:**
-1. Receives confirmation token from user
-2. Calls `TokenValidationService.ValidateConfirmationTokenAsync()`
-3. Extracts user ID from validated token
-4. Calls `AuthRepository.ConfirmUserAccountAsync()` to update database
-5. Returns confirmation result
-
-#### [RefreshTokenService](Service.Auth/RefreshTokenService.cs)
-
-**Flow:**
-1. Receives refresh token from user
-2. Calls `TokenValidationService.ValidateRefreshTokenAsync()`
-3. Retrieves user account via `AuthRepository.GetUserByIdAsync()`
-4. Issues new access and refresh tokens via `TokenService`
-5. Returns new token pair
-
-#### [AuthController](API.Core/Controllers/AuthController.cs)
-
-**Endpoints:**
-- `POST /api/auth/register` - Register new user
-- `POST /api/auth/login` - Authenticate user
-- `POST /api/auth/confirm?token=...` - Confirm email
-- `POST /api/auth/refresh` - Refresh access token
-
-## Validation Security
-
-### Token Secrets
-
-Three independent secrets enable:
-- **Key rotation** - Rotate each secret type independently
-- **Isolation** - Compromise of one secret doesn't affect others
-- **Different expiration** - Different token types can expire at different rates
-
-**Environment Variables:**
-```bash
-ACCESS_TOKEN_SECRET=...           # Signs 1-hour access tokens
-REFRESH_TOKEN_SECRET=...          # Signs 21-day refresh tokens
-CONFIRMATION_TOKEN_SECRET=...     # Signs 30-minute confirmation tokens
-```
-
-### Validation Checks
-
-Each token is validated for:
-
-1. **Signature Verification** - Token must be signed with correct secret
-2. **Expiration** - Token must not be expired (checked against current time)
-3. **Claims Presence** - Required claims (Sub, UniqueName) must be present
-4. **Claims Format** - UserId claim must be a valid GUID
-
-### Error Handling
-
-Validation failures return HTTP 401 Unauthorized:
-- Invalid signature → "Invalid token"
-- Expired token → "Invalid token" (message doesn't reveal reason for security)
-- Missing claims → "Invalid token"
-- Malformed claims → "Invalid token"
-
-## Token Lifecycle
-
-### Access Token Lifecycle
-
-1. **Generation**: During login (1-hour validity)
-2. **Usage**: Included in Authorization header on API requests
-3. **Validation**: Validated on protected endpoints
-4. **Expiration**: Token becomes invalid after 1 hour
-5. **Refresh**: Use refresh token to obtain new access token
-
-### Refresh Token Lifecycle
-
-1. **Generation**: During login (21-day validity)
-2. **Storage**: Client-side (secure storage)
-3. **Usage**: Posted to `/api/auth/refresh` endpoint
-4. **Validation**: Validated by RefreshTokenService
-5. **Rotation**: New refresh token issued on successful refresh
-6. **Expiration**: Token becomes invalid after 21 days
-
-### Confirmation Token Lifecycle
-
-1. **Generation**: During user registration (30-minute validity)
-2. **Delivery**: Emailed to user in confirmation link
-3. **Usage**: User clicks link, token posted to `/api/auth/confirm`
-4. **Validation**: Validated by ConfirmationService
-5. **Completion**: User account marked as confirmed
-6. **Expiration**: Token becomes invalid after 30 minutes
-
-## Testing
-
-### Unit Tests
-
-**TokenValidationService.test.cs**
-- Happy path: Valid token extraction
-- Error cases: Invalid, expired, malformed tokens
-- Missing/invalid claims scenarios
-
-**RefreshTokenService.test.cs**
-- Successful refresh with valid token
-- Invalid/expired refresh token rejection
-- Non-existent user handling
-
-**ConfirmationService.test.cs**
-- Successful confirmation with valid token
-- Token validation failures
-- User not found scenarios
-
-### BDD Tests (Reqnroll)
-
-**TokenRefresh.feature**
-- Successful token refresh
-- Invalid/expired token rejection
-- Missing token validation
-
-**Confirmation.feature**
-- Successful email confirmation
-- Expired/tampered token rejection
-- Missing token validation
-
-**AccessTokenValidation.feature**
-- Protected endpoint access token validation
-- Invalid/expired access token rejection
-- Token type mismatch (refresh used as access token)
-
-## Future Enhancements
-
-### Stretch Goals
-
-1. **Middleware for Access Token Validation**
-   - Automatically validate access tokens on protected routes
-   - Populate HttpContext.User from token claims
-   - Return 401 for invalid/missing tokens
-
-2. **Token Blacklisting**
-   - Implement token revocation (e.g., on logout)
-   - Store blacklisted tokens in cache/database
-   - Check blacklist during validation
-
-3. **Refresh Token Rotation Strategy**
-   - Detect token reuse (replay attacks)
-   - Automatically invalidate entire token chain on reuse
-   - Log suspicious activity
-
-4. **Structured Logging**
-   - Log token validation attempts
-   - Track failed validation reasons
-   - Alert on repeated validation failures (brute force detection)

docs/web/architecture.md

@@ -0,0 +1,611 @@
+# Architecture
+
+This document describes the architecture of The Biergarten App.
+
+## High-level overview
+
+The Biergarten App is a monorepo split between the backend and the website:
+
+- **Backend**: .NET 10 Web API with SQL Server, organized as vertical feature
+  slices with MediatR
+- **Frontend**: React 19 + React Router 8 website in `web/frontend`
+- **Architecture Style**: Vertical-slice backend plus server-rendered React
+  frontend
+
+`archive/next-js-web-app/` contains an archived Next.js frontend, kept for
+reference.
+
+## Diagrams
+
+For visual representations, see:
+
+- [Vertical Slice](diagrams/vertical-slice.md) - host wiring and project
+  reference diagrams
+- [Deployment](diagrams/deployment.md) - Docker deployment diagram
+- [Database Schema](diagrams/database-schema.md) - database relationships
+
+Authentication workflow diagrams, one per flow, under
+[`diagrams/auth/`](diagrams/auth/):
+
+- [Registration](diagrams/auth/registration.md)
+- [Login](diagrams/auth/login.md)
+- [Refresh Token](diagrams/auth/refresh-token.md)
+- [Confirm User](diagrams/auth/confirm-user.md)
+- [Resend Confirmation](diagrams/auth/resend-confirmation.md)
+- [Update Username](diagrams/auth/update-username.md)
+- [Update Email](diagrams/auth/update-email.md)
+- [Update Password](diagrams/auth/update-password.md)
+- [Update Profile](diagrams/auth/update-profile.md)
+- [Delete Account](diagrams/auth/delete-account.md)
+- [Error Handling](diagrams/auth/error-handling.md) - shared
+  `GlobalExceptionFilter` mapping used by all flows above
+
+## Backend architecture
+
+### Vertical-slice architecture pattern
+
+The backend organizes business capabilities as feature slices instead of
+technical layers.
+
+Each feature (`Features.Users`, `Features.Breweries`, `Features.Emails`,
+`Features.Locations`, `Features.PhotoUpload`) is a single project that owns its
+own MediatR commands/queries/handlers, validators, and repository end to end.
+
+`Features.Emails`, `Features.Locations`, and `Features.PhotoUpload` have no
+`Controllers/` folder; all three are invoked internally by other slices via
+MediatR/DI, never over HTTP:
+
+```mermaid
+flowchart TB
+    subgraph HOST["API.Core (thin host)"]
+        direction LR
+        H1["Program.cs wiring:<br/>MediatR + AddApplicationPart per slice"]
+        H2["Swagger / OpenAPI"]
+        H3["JWT auth middleware"]
+        H4["GlobalExceptionFilter"]
+    end
+
+    subgraph SLICES["Feature Slices"]
+        direction LR
+        S1["Features.Users<br/>Controllers, Commands/Queries,<br/>Handlers, Repository"]
+        S2["Features.Breweries<br/>Controller, Commands/Queries,<br/>Handlers, Repository"]
+        S3["Features.Emails<br/>(internal only)<br/>Commands, Handlers,<br/>EmailDispatcher"]
+        S4["Features.Locations<br/>(internal only)<br/>Repository"]
+        S5["Features.PhotoUpload<br/>(internal only)<br/>Commands, Handlers,<br/>Repository"]
+    end
+
+    subgraph SHARED["Shared Projects"]
+        direction LR
+        SH1["Shared.Contracts<br/>ResponseBody envelope"]
+        SH2["Shared.Application<br/>ValidationBehavior"]
+    end
+
+    subgraph DOMAIN["Domain Layer"]
+        direction LR
+        D1["Domain.Entities"]
+        D2["Domain.Exceptions"]
+    end
+
+    subgraph INFRA["Infrastructure Layer"]
+        direction LR
+        I1["Database.Connection"]
+        I3["Infrastructure.PasswordHashing"]
+        I4["Email.Templates"]
+    end
+
+    DB[("Database (SQL Server)")]
+
+    HOST -- "discovers controllers via<br/>AddApplicationPart" --> SLICES
+    S3 == "ProjectReference<br/>(handles UserRegisteredNotification & ConfirmationEmailResendRequestedNotification)" ==> S1
+    S1 -- "ProjectReference<br/>(avatar upload)" --> S5
+
+    SLICES --> SHARED
+    SLICES --> DOMAIN
+    SLICES --> INFRA
+
+    INFRA --> DB
+
+    style S3 stroke-dasharray: 4 3
+    style S4 stroke-dasharray: 4 3
+    style S5 stroke-dasharray: 4 3
+```
+
+### Layer responsibilities
+
+#### API layer (`API.Core`)
+
+**Purpose**: Thin ASP.NET Core host: no business logic, no controllers of its
+own
+
+**Components**:
+
+| Component                                             | Description                                                                                                                                                  |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Program.cs`                                          | Thin composition root: builds the host and calls the `ServiceCollectionExtensions` methods below.                                                            |
+| `ServiceCollectionExtensions.cs`                      | Registers MediatR (scanning every `Features.*` assembly), FluentValidation, and uses `AddApplicationPart` so each slice's controllers are discovered by MVC. |
+| `GlobalException.cs`                                  | Global exception filter (host-level cross-cutting concern).                                                                                                  |
+| `Authentication/JwtAuthenticationHandler.cs`          | JWT auth scheme middleware.                                                                                                                                  |
+| Swagger/OpenAPI documentation, health check endpoints | Host-level documentation and health endpoints.                                                                                                               |
+
+**Dependencies**:
+
+- Every `Features.*` project (for controller/MediatR discovery)
+- `Shared.Contracts`, `Shared.Application`
+
+**Rules**:
+
+- No controllers, no business logic, no feature-specific contracts
+- Exists purely to host and wire up the feature slices
+
+#### Feature slices (`Features.Users`, `Features.Breweries`, `Features.Emails`, `Features.Locations`, `Features.PhotoUpload`)
+
+**Purpose**: Each slice is the complete vertical for one business capability
+
+**Components** (per slice):
+
+| Component                                          | Description                                                                                                                                |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Controllers/`                                     | HTTP endpoints, binding directly to Command/Query types as the request contract                                                            |
+| `Commands/<Operation>/` and `Queries/<Operation>/` | One folder per operation, each containing the Command/Query record, its `IRequestHandler`, and (for commands) a FluentValidation validator |
+| `Repository/`                                      | The slice's own Dapper repository implementation                                                                                           |
+| `Dtos/`                                            | Response shapes returned by query handlers (never the raw domain entity)                                                                   |
+| `DependencyInjection/`                             | An `AddFeaturesX()` extension method registering the slice's repository/services                                                           |
+
+##### Note
+
+`Features.Emails` has no `Controllers/` folder. It's invoked only via MediatR
+commands sent from other slices, never over HTTP.
+
+`Features.PhotoUpload` also has no `Controllers/` folder; its
+`UploadPhotoCommand` is sent by other features' handlers (for example, a future
+brewery photo upload command) rather than bound to an HTTP route directly.
+
+**Dependencies**:
+
+- `Domain.Entities`, `Domain.Exceptions`
+- `Database.Connection` (generic ADO.NET connection/command plumbing) plus
+  whichever infrastructure project the slice needs (`Infrastructure.PasswordHashing`
+  for Users, `Infrastructure.Email.Templates` for Emails)
+- `Shared.Contracts`, `Shared.Application`
+- No other `Features.*` project, with two exceptions: `Features.Users`
+  references `Features.PhotoUpload` directly for avatar uploads, and
+  `Features.Emails` references `Features.Users` directly to handle
+  `UserRegisteredNotification` and `ConfirmationEmailResendRequestedNotification`
+
+**Rules**:
+
+- All business logic for that feature lives in its command/query handlers
+- No direct controller-to-repository calls; everything flows through MediatR
+- Read endpoints return a dedicated `Dto` rather than the domain entity
+  directly. The one exception is `UserController.GetAuthenticated`, which
+  returns the caller's own `UserAccount` entity
+
+#### Shared projects (`Shared.Contracts`, `Shared.Application`)
+
+**Purpose**: The minimum cross-slice surface area required because every slice
+needs it, or because duplicating it four times would be worse than sharing it
+
+**Components**:
+
+| Project              | Purpose                                                                                                                                                                                                                                 |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Shared.Contracts`   | `ResponseBody<T>`/`ResponseBody`, the API response envelope `AuthController`, `BreweryController`, and `CityController` return; `UserController`'s read endpoints return their DTOs unwrapped                                           |
+| `Shared.Application` | `ValidationBehavior<TRequest,TResponse>`, the MediatR pipeline behavior that runs FluentValidation before a handler executes |
+
+**Rules**:
+
+- Kept deliberately small: this is the exception to "no slice depends on another
+  slice".
+
+#### Infrastructure layer
+
+**Purpose**: Technical capabilities and external integrations, shared by
+whichever slices need them
+
+**Components**:
+
+| Project                          | Description                                                                                                                                                                                                                                                                |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Database.Connection`            | Generic ADO.NET connection/command plumbing (`DefaultSqlConnectionFactory`, the abstract `DapperRepository` base class), not domain-specific; each slice's own `Repository/` folder builds on this.                                                                        |
+| `Infrastructure.PasswordHashing` | Argon2id password hashing.                                                                                                                                                                                                                                                 |
+| `Infrastructure.Email.Templates` | Email template rendering (Razor components).                                                                                                                                                                                                                               |
+
+**Dependencies**:
+
+- Domain entities
+- External libraries (ADO.NET, JWT, Argon2, MailKit, AWSSDK.S3, and so on)
+
+**Rules**:
+
+- Implements technical concerns only, no business logic
+- Reusable across slices
+
+#### Domain layer (`Domain.Entities`)
+
+**Purpose**: Core business entities and models
+
+**Components**:
+
+| Entity                | Description                                                                                        |
+| --------------------- | -------------------------------------------------------------------------------------------------- |
+| `UserAccount`         | User profile data.                                                                                 |
+| `UserCredential`      | Authentication credentials.                                                                        |
+| `UserVerification`    | Account verification state.                                                                        |
+| `BreweryPost`         | A user-submitted brewery listing.                                                                  |
+| `BreweryPostLocation` | A brewery's address and coordinates.                                                               |
+| `City`                | A city referenced by a brewery location.                                                           |
+| `StateProvince`       | A state/province referenced by a city.                                                             |
+| `Country`             | A country referenced by a state/province.                                                          |
+| `BeerStyle`           | A beer style/category (schema table exists; no repository yet).                                    |
+| `BeerPost`            | A beer listing tied to a brewery and style (schema table exists; no repository yet).               |
+| `Photo`               | A photo uploaded by a user account, written via `Features.PhotoUpload`'s `IPhotoUploadRepository`. |
+
+**Dependencies**:
+
+- None (pure domain)
+
+**Rules**:
+
+- Plain Old CLR Objects (POCOs)
+- No framework dependencies
+- No infrastructure references
+- Represents business concepts
+
+### Design patterns
+
+#### Vertical slice + MediatR
+
+**Purpose**: Organize code by feature instead of by technical layer, so
+everything needed to understand or change one capability lives in one project
+
+**Implementation**:
+
+- Each HTTP write operation is a `Command` (for example, `CreateBreweryCommand`
+  in `Features.Breweries/Commands/CreateBrewery/`); each read operation is a
+  `Query` (for example, `GetBreweryByIdQuery`)
+- Controllers generally bind directly to the Command/Query as the request body;
+  there is no separate request DTO + mapping step for writes
+  - The exception to this is for authenticated routes, when the current user id
+    needs to be extracted from the authentication token to be used in a command
+    or query.
+- A single shared `ValidationBehavior<TRequest,TResponse>`
+  (`Shared.Application/Behaviors/`) runs FluentValidation validators in the
+  MediatR pipeline before any handler executes
+- Query handlers map to a dedicated response `Dto`, so domain entities never
+  leak
+
+**Example**:
+
+```csharp
+public record CreateBreweryCommand(Guid PostedById, string BreweryName, string Description, ...)
+    : IRequest<BreweryDto>;
+
+public class CreateBreweryHandler(IBreweryRepository repository) : IRequestHandler<CreateBreweryCommand, BreweryDto>
+{
+    public async Task<BreweryDto> Handle(CreateBreweryCommand request, CancellationToken cancellationToken) { ... }
+}
+```
+
+#### Repository pattern
+
+**Purpose**: Abstract database access behind interfaces
+
+**Implementation**: each slice owns its own repository, scoped to that feature
+only:
+
+- `Features.Users/Repository/IUserListRepository.cs`,
+  `Features.Users/Repository/IUserProfileRepository.cs`
+- `Features.Breweries/Repository/IBreweryRepository.cs`
+- `Features.PhotoUpload/Repository/IPhotoUploadRepository.cs`
+- `Database.Connection/DefaultSqlConnectionFactory.cs`: the generic connection
+  factory every slice's repository builds on
+- `Database.Connection/DapperRepository.cs`: shared abstract base class every
+  repository extends, providing `CreateConnection()` and a
+  `RollbackQuietlyAsync()` helper that rolls back a transaction while swallowing
+  any exception the rollback itself raises, so the exception that triggered the
+  rollback is what propagates
+
+**Benefits**:
+
+- Testable (easy to mock)
+- Each slice's data access logic is self-contained
+
+**Example**:
+
+```csharp
+public interface IUserListRepository
+{
+    Task<UserAccount?> GetByIdAsync(Guid id);
+    Task<IEnumerable<UserAccount>> GetAllAsync(int? limit, int? offset);
+}
+```
+
+#### Dependency injection
+
+**Purpose**: Loose coupling and testability
+
+**Configuration**: `Program.cs` wires up MediatR/FluentValidation across every
+`Features.*` assembly; each slice exposes its own `AddFeaturesX()` extension
+method that registers its repository and slice-internal services
+
+**Lifetimes**:
+
+- Scoped: Repositories, slice-internal services (per request)
+- Singleton: `DefaultSqlConnectionFactory`
+- Transient: Utilities, helpers
+
+#### Direct SQL via Dapper/ADO.NET
+
+**Purpose**: Keep data access explicit and colocated with the slice that owns it
+
+**Strategy**:
+
+- Each repository issues inline SQL through Dapper, which handles parameter
+  binding.
+- Proximity search (`GET /api/brewery/locations/nearby`) filters and orders rows
+  server-side with `Coordinates.STDistance(@Origin) <= @RangeInMetres`, avoiding
+  a client-side distance calculation over every row.
+- Referential checks (for example, "does this `CityId` exist?") are explicit
+  `SELECT 1 ...` existence checks in the repository method, run inside the same
+  transaction as the write
+- Optimistic concurrency uses each table's `RowVersion` (`ROWVERSION`) column,
+  checked in the `UPDATE ... WHERE ... AND RowVersion = @RowVersion` clause
+- Repositories throw `Domain.Exceptions` types (`NotFoundException`,
+  `ConflictException`, ...) directly when a check fails; `API.Core`'s
+  `GlobalExceptionFilter` maps those exception types to HTTP status codes
+- Application focuses on orchestration; the database enforces integrity via
+  keys, `CHECK` constraints, and cascades
+
+See [Database](database.md) for the schema and the app's SQL error-handling
+approach in more detail.
+
+## Frontend architecture
+
+### Website (`web/frontend`)
+
+The website is a React Router 8 application with server-side rendering enabled.
+
+```text
+web/frontend/
+├── app/
+│   ├── components/      Shared UI: Navbar, FormField, SubmitButton, ToastProvider,
+│   │                    RouteErrorState, ClientOnly (defers client-only children,
+│   │                    for example Leaflet maps, past hydration)
+│   ├── features/        One folder per feature slice, each owning its own
+│   │                    routes/, components/, hooks/, schemas, and server-side
+│   │                    loader helpers:
+│   │                      - account    profile/dashboard management
+│   │                      - auth       login, register, confirm, logout
+│   │                      - breweries  index/directory/detail routes, Leaflet
+│   │                                   map components, nearby-search resource
+│   │                                   route, distance/address utils
+│   │                      - catalog    beers, beer styles
+│   │                      - home       landing page
+│   │                      - theme      theme switcher/guide
+│   │                      - users      public user profile page (/users/:id)
+│   ├── hooks/            Shared hooks not tied to one feature, for example useMediaQuery
+│   ├── routes.ts         Route table (React Router 8 config-based routing)
+│   ├── root.tsx          App shell and global providers
+│   └── app.css           Theme tokens and global styling
+├── .storybook/          Storybook config and preview setup
+├── stories/             Storybook stories for shared UI and themes
+├── tests/playwright/    Storybook Playwright coverage
+└── package.json         Frontend scripts and dependencies
+```
+
+### Frontend responsibilities
+
+- Render brewery discovery routes (`/breweries` index, `/breweries/directory`,
+  `/breweries/:id`) with Leaflet-powered maps and geolocation-based "nearby"
+  search
+- Render the auth demo, account dashboard, and theme guide routes
+- Render the public user profile route (`/users/:id`), including a user's
+  following list and (via brewery comments) links back to commenter profiles
+- Manage cookie-backed website session state
+- Call the .NET API for login, registration, token refresh, confirmation, and
+  brewery/location data
+- Provide shared UI building blocks for forms, navigation, themes, and toasts
+- Supply Storybook documentation and browser-based component verification
+
+### Theme system
+
+The website uses semantic DaisyUI theme tokens backed by four Biergarten themes:
+
+- Biergarten Lager
+- Biergarten Stout
+- Biergarten Cassis
+- Biergarten Weizen
+
+All component styling should prefer semantic tokens such as `primary`,
+`success`, `surface`, and `highlight` instead of hard-coded color values.
+
+### Archived frontend
+
+`archive/next-js-web-app/` contains an archived Next.js frontend, kept for
+reference. Product and engineering documentation points to `web/frontend`.
+
+## Security architecture
+
+### Authentication flow
+
+| Flow                   | Details                                                                                                                                                                                                                                                           |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Registration**       | User submits credentials; password is hashed with Argon2id; user account is created as unverified and a confirmation email is dispatched via `Features.Emails`.                                                                                                   |
+| **Email confirmation** | User follows the confirmation link/token from the email; `Features.Users`' `ConfirmUser` command marks the account as verified.                                                                                                                                   |
+| **Login**              | User submits credentials; password is verified against the hash; access and refresh JWTs are issued and returned to the client; neither is stored server-side.                                                                                                    |
+| **Token refresh**      | Client exchanges a valid, unexpired refresh token for a new access/refresh pair via `Features.Users`' `RefreshToken` command; refresh tokens are stateless JWTs, not tracked server-side, and the previous refresh token remains usable until its own expiration. |
+| **API requests**       | Client sends the access JWT in the `Authorization` header; `JwtAuthenticationHandler` validates the token; request proceeds if valid.                                                                                                                             |
+
+### Password security
+
+**Algorithm**: Argon2id
+
+| Setting     | Value                                          |
+| ----------- | ---------------------------------------------- |
+| Memory      | 64MB                                           |
+| Iterations  | 4                                              |
+| Parallelism | 2 (hardcoded, to avoid thread-pool exhaustion) |
+| Salt        | 128-bit (16 bytes)                             |
+| Hash        | 256-bit (32 bytes)                             |
+
+### JWT tokens
+
+**Algorithm**: HS256 (HMAC-SHA256)
+
+**Claims**:
+
+| Claim         | Meaning              |
+| ------------- | -------------------- |
+| `sub`         | User ID              |
+| `unique_name` | Username             |
+| `jti`         | Unique token ID      |
+| `iat`         | Issued at timestamp  |
+| `exp`         | Expiration timestamp |
+
+**Configuration** (appsettings.json):
+
+```json
+{
+  "Jwt": {
+    "ExpirationMinutes": 60,
+    "Issuer": "biergarten-api",
+    "Audience": "biergarten-users"
+  }
+}
+```
+
+This block exists in `appsettings.json`, but nothing in the code currently reads
+it: actual token lifetimes come from the hardcoded `TokenServiceExpirationHours`
+constants, and `JwtInfrastructure` hardcodes `ValidateIssuer`/`ValidateAudience`
+to `false`, so `Issuer`/`Audience` are not enforced.
+
+## Database architecture
+
+For the table-by-table schema and the custom SQL error code scheme, see
+[Database](database.md).
+
+### SQL-first philosophy
+
+**Principles**:
+
+1. Database is source of truth
+2. Queries live in the owning repository, not scattered across the app
+3. Database handles referential integrity
+4. Application orchestrates, database executes
+
+**Benefits**:
+
+- Performance optimization via execution plans
+- Query logic scoped to the repository that owns it, not spread across layers
+- Version-controlled schema (migrations)
+- Easier query profiling and tuning
+
+### Migration strategy
+
+**Tool**: DbUp
+
+**Process**:
+
+1. Write a SQL script under `Database.Migrations/scripts/`
+2. Embed it in the `Database.Migrations` project
+3. `Database.Migrations` runs each script against the target database on
+   startup, tracked so a script never re-runs once applied
+
+**Migration Files**:
+
+```
+scripts/
+└── 01-schema/
+    ├── 01-UserAccount.sql
+    ├── 02-Photo.sql
+    ├── ...
+    ├── 16-UserProfile.sql
+    └── 17-UserAvatar.sql        # one script per CREATE TABLE
+```
+
+Each table has its own script, numbered so a table's foreign keys always point
+at an earlier-numbered script. As the schema evolves, new numbered scripts get
+added rather than editing an existing one in place, so DbUp's already-applied
+tracking stays valid.
+
+### Data seeding
+
+**Purpose**: Populate development/test databases with realistic data
+
+**Implementation**: `Database.Seed` project, using data produced by the C++
+pipeline under `tooling/pipeline/` (see
+[Pipeline README](../pipeline/README.md))
+
+**Seed Data**:
+
+- Countries, state/provinces, and cities (via `Features.Locations`'
+  `ILocationRepository`, which creates `Country`/`StateProvince` rows on demand
+  while resolving a city)
+- User accounts (via `Features.Users`' repository)
+- Brewery posts with locations (via `Features.Breweries`' repository)
+
+Tables that exist in the schema but have no repository yet ( `UserFollow`,
+`BeerStyle`, `BeerPost`, `BeerPostPhoto`, `BeerPostComment`, `BreweryPostPhoto`)
+are not seeded either.
+
+## Deployment architecture
+
+### Docker containerization
+
+**Container Structure**:
+
+| Container             | Purpose                                                      |
+| --------------------- | ------------------------------------------------------------ |
+| `sqlserver`           | SQL Server 2022                                              |
+| `database.migrations` | Schema migration runner                                      |
+| `database.seed`       | Data seeder                                                  |
+| `api.core`            | ASP.NET Core Web API                                         |
+| `mailpit`             | Local dev/test SMTP server + web UI (not used in production) |
+| `seaweedfs`           | S3-compatible object storage for uploaded photos (dev only)  |
+
+**Environments**:
+
+| Environment     | Compose file                    |
+| --------------- | ------------------------------- |
+| Development     | `docker-compose.dev.yaml`       |
+| Testing         | `docker-compose.test.yaml`      |
+| Production      | `docker-compose.prod.yaml`      |
+| Production seed | `docker-compose.prod.seed.yaml` |
+
+For details, see [Docker Guide](docker.md).
+
+### Health checks
+
+- **SQL Server**: Validates database connectivity
+- **API**: Checks service health and dependencies
+
+**Configuration**:
+
+```yaml
+healthcheck:
+  test: ["CMD-SHELL", "sqlcmd health check"]
+  interval: 10s
+  retries: 12
+  start_period: 30s
+```
+
+## Testing architecture
+
+### Test pyramid
+
+```mermaid
+flowchart TB
+    IT["Integration Tests<br/>API.Specs (Reqnroll)"]
+    UT["Unit Tests (per slice, handler tests)<br/>Features.Users.Tests, Features.Breweries.Tests,<br/>Features.Emails.Tests, Features.PhotoUpload.Tests<br/>(commands/queries/handlers, with repository/service<br/>dependencies mocked via Moq)"]
+
+    IT --- UT
+```
+
+**Strategy**:
+
+- Many unit tests (fast, isolated)
+- Fewer integration tests (slower, e2e)
+- Mock external dependencies
+- Test database for integration tests
+
+For details, see [Testing Guide](testing.md).

docs/web/database.md

@@ -0,0 +1,143 @@
+---
+title: SQL Server database schema, migrations, and error handling
+last-updated: 2026-08-31
+tags:
+  - sql
+  - repository
+  - database
+  - sql-server
+  - schema
+---
+
+SQL Server 2022 schema, migration approach, and the app's SQL error-handling
+convention. For the vertical-slice code that talks to this schema, see
+[Architecture](architecture.md).
+
+## Schema
+
+The schema is split into six SQL Server schemas, one per feature area, each
+living in its own numbered folder under
+`web/backend/Database/Database.Migrations/scripts/`. The folder numbers
+(`01`-`06`) fix the load order so foreign-key dependencies resolve — DbUp runs
+embedded scripts in alphabetical-by-resource-name order, so e.g. `04-Brewery`
+(which references `Auth`, `Geolocation`, and `Media`) runs after all three.
+Each folder's `00-Schema.sql` creates its SQL schema before its tables run:
+
+```
+scripts
+  ├── 01-Auth          (UserAccount, UserVerification, UserCredential)
+  │     ├── 00-Schema.sql
+  │     ├── 01-UserAccount.sql
+  │     ├── 02-UserVerification.sql
+  │     └── 03-UserCredential.sql
+  ├── 02-Geolocation   (Country, StateProvince, City)
+  │     ├── 00-Schema.sql
+  │     ├── 01-Country.sql
+  │     ├── 02-StateProvince.sql
+  │     └── 03-City.sql
+  ├── 03-Media         (Photo)
+  │     ├── 00-Schema.sql
+  │     └── 01-Photo.sql
+  ├── 04-Brewery       (BreweryPost, BreweryPostLocation, BreweryPostPhoto)
+  │     ├── 00-Schema.sql
+  │     ├── 01-BreweryPost.sql
+  │     ├── 02-BreweryPostLocation.sql
+  │     └── 03-BreweryPostPhoto.sql
+  ├── 05-Beer          (BeerStyle, BeerPost, BeerPostPhoto, BeerPostComment)
+  │     ├── 00-Schema.sql
+  │     ├── 01-BeerStyle.sql
+  │     ├── 02-BeerPost.sql
+  │     ├── 03-BeerPostPhoto.sql
+  │     └── 04-BeerPostComment.sql
+  └── 06-Social        (UserFollow, UserProfile, UserAvatar)
+        ├── 00-Schema.sql
+        ├── 01-UserFollow.sql
+        ├── 02-UserProfile.sql
+        └── 03-UserAvatar.sql
+```
+
+Each script is run in order by `Database.Migrations` (DbUp) on startup. Tables
+are referenced schema-qualified in code (e.g. `Auth.UserAccount`), not under
+the default `dbo` schema. Each table is queried directly by the owning
+feature slice's repository (see
+[Direct SQL via Dapper/ADO.NET](architecture.md#direct-sql-via-dapperadonet)).
+
+A generated DBML copy of the schema (for import into a diagramming tool such as
+dbdiagram.io) lives at `web/backend/Database/Database.Migrations/schema.dbml`.
+
+All tables use a `UNIQUEIDENTIFIER` primary key defaulting to `NEWID()`, and
+most carry a `RowVersion ROWVERSION` column used for optimistic concurrency on
+updates (`UPDATE ... WHERE ... AND RowVersion = @RowVersion`).
+
+### Tables backed by the API today
+
+| Table                 | Backed by                                                   | Notes                                                                                                                                                                                                     |
+| --------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `UserAccount`         | `Domain.Entities.UserAccount`, `Features.Users`             | `Username` and `Email` are unique                                                                                                                                                                         |
+| `UserCredential`      | `Domain.Entities.UserCredential`, `Features.Users`          | Argon2id password hash; `IsRevoked`/`RevokedAt` track credential rotation, not JWTs                                                                                                                       |
+| `UserVerification`    | `Domain.Entities.UserVerification`, `Features.Users`        | Written when a user confirms their email                                                                                                                                                                  |
+| `UserProfile`         | `Domain.Entities.UserProfile`, `Features.Users`             | 1:1 with `UserAccount`; holds the user's biography; written via `IUserProfileRepository`, read via `IUserListRepository`'s left joins in both `GetByIdAsync` and `GetAllAsync`                                                  |
+| `UserAvatar`          | `Domain.Entities.UserAvatar`, `Features.Users`              | Links a `UserProfile` to a `Photo` as its avatar; written via `IUserProfileRepository.SaveAvatarAsync`, read via `IUserListRepository`'s `ValidTo IS NULL` join for the active avatar                                                                                           |
+| `BreweryPost`         | `Domain.Entities.BreweryPost`, `Features.Breweries`         | A user-submitted brewery listing                                                                                                                                                                          |
+| `BreweryPostLocation` | `Domain.Entities.BreweryPostLocation`, `Features.Breweries` | 1:1 with `BreweryPost`; `Coordinates` is a `GEOGRAPHY` column, read via a plain Dapper query that selects `CONVERT(varbinary(max), Coordinates)`, since Dapper can't deserialize SQL Server UDTs directly |
+| `City`                | `Domain.Entities.City`, `Features.Locations`                | Referenced by `BreweryPostLocation.CityID`; `CityName` and `StateProvinceID` together are unique; written via `ILocationRepository`, read via `ILocationRepository` and `IBreweryRepository`'s location joins, currently written only by `Database.Seed` |
+| `StateProvince`       | `Domain.Entities.StateProvince`, `Features.Locations`       | Referenced by `City.StateProvinceID`; created on demand by `ILocationRepository.GetOrCreateCityIdAsync`, read via `IBreweryRepository`'s location joins                                                   |
+| `Country`             | `Domain.Entities.Country`, `Features.Locations`             | Referenced by `StateProvince.CountryID`; created on demand by `ILocationRepository.GetOrCreateCityIdAsync`, read via `IBreweryRepository`'s location joins                                                |
+| `Photo`               | `Domain.Entities.Photo`, `Features.PhotoUpload`             | Written via `IPhotoUploadRepository.CreateAsync`, sent as an `UploadPhotoCommand` from other features' handlers; `Hyperlink` holds the object key within the bucket, which readers sign into a time-limited URL via `IFileStorageProvider.GetPresignedUrl`; the active avatar's row is also read via `IUserListRepository`'s `Media.Photo` join; not yet seeded by `Database.Seed`                                                |
+
+### Tables defined in the schema but not yet wired to a feature slice
+
+These exist so the schema can support planned functionality, but have no
+repository or seed data yet:
+
+| Table              | Purpose (from schema)                                                                                                                                                  |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `UserFollow`       | One user following another (`CannotFollowOwnAccount` check constraint)                                                                                                 |
+| `BeerStyle`        | A beer style/category; has a `Domain.Entities.BeerStyle` type, but no repository yet                                                                                   |
+| `BeerPost`         | A beer listing, linked to a `BreweryPost` and `BeerStyle`; `ABV`/`IBU` are constrained (`0-67`, `0-120`); has a `Domain.Entities.BeerPost` type, but no repository yet |
+| `BeerPostPhoto`    | Links a `BeerPost` to a `Photo`                                                                                                                                        |
+| `BeerPostComment`  | A comment + 1-5 `Rating` on a `BeerPost`                                                                                                                               |
+| `BreweryPostPhoto` | Links a `BreweryPost` to a `Photo`                                                                                                                                     |
+
+## Managing Migrations (DbUp)
+
+Migrations are handled by the `Database.Migrations` container using DbUp.
+Scripts are placed in the `scripts/` directory, applied in order, and tracked so
+that each one runs only once.
+
+**Note:** The schema is currently considered volatile. At this stage of
+development, fresh database instances are provisioned for both development and
+testing, so no production data exists yet.
+
+### How to Make Schema Changes
+
+- **Now (no production data):** Update the schema by editing the original DDL
+  statements directly.
+- **Later (with production data):** Add a new, numbered script for any schema
+  changes. Never edit an existing script in place — DbUp tracks completion by
+  script name, so modifying an already-applied script means the changes will be
+  ignored on existing databases.
+
+## Data seeding
+
+`Database.Seed` populates a target database from data produced by the C++
+pipeline (see [Pipeline README](../pipeline/README.md)): countries,
+state/provinces, and cities (created on demand while resolving each brewery's
+location), user accounts, and brewery posts with locations. It doesn't call
+every feature slice that has a write path: `Photo`, for example, has a
+repository (`Features.PhotoUpload`) but no seed data.
+
+## Database error handling
+
+- Optimistic-concurrency conflicts are detected by an `UPDATE` affecting zero
+  rows against the `RowVersion` column.
+- On failure, the repository throws a `Domain.Exceptions` type directly
+  (`NotFoundException`, `ConflictException`, `ArgumentException`, ...).
+  `API.Core`'s `GlobalExceptionFilter` maps these to HTTP status codes (404,
+  409, 400, ...); an unmapped `SqlException` (for example, a genuine
+  connectivity or constraint-violation failure) maps to 503.
+
+  - One exception: `Features.Users`' `DapperUserStore` does catch `SqlException`
+    directly, to detect a duplicate-key race (SQL Server error 2601 or 2627)
+    when two requests try to verify the same account concurrently; see
+    `DapperUserStore.IsDuplicateKeyViolation`.

docs/web/diagrams/auth/confirm-user.md

@@ -0,0 +1,5 @@
+# User Authentication Flow — Confirm User
+
+```mermaid
+--8<-- "web/diagrams/auth/confirm-user.mmd"
+```

docs/web/diagrams/auth/confirm-user.mmd

@@ -0,0 +1,79 @@
+sequenceDiagram
+    actor User
+    participant API as API Controller
+    participant Mediator as MediatR pipeline<br/>(ValidationBehavior)
+    box Handler Layer
+        participant ConfirmHandler as ConfirmUserHandler
+        participant UserMgr as UserManager(ApplicationUser)
+        participant TokenSvc as TokenService
+    end
+    box Infrastructure Layer
+        participant JWT as JWT Infrastructure
+    end
+    box Repository / Cross-slice
+        participant UserStore as DapperUserStore<br/>(IUserStore/IUserPasswordStore/IUserEmailStore)
+    end
+    participant DB as SQL Server
+
+    User->>API: POST /api/auth/confirm?token={token} (requires Bearer access token)
+    activate API
+    API->>Mediator: Send(ConfirmUserCommand(token))
+    activate Mediator
+    Mediator->>ConfirmHandler: Handle(command)
+    activate ConfirmHandler
+
+    ConfirmHandler->>TokenSvc: ValidateConfirmationTokenAsync(token)
+    activate TokenSvc
+    TokenSvc->>JWT: Validate against confirmation token secret, extract userId
+    activate JWT
+    JWT-->>TokenSvc: ValidatedToken or throws
+    deactivate JWT
+    TokenSvc-->>ConfirmHandler: ValidatedToken
+    deactivate TokenSvc
+
+    alt Token invalid or expired
+        ConfirmHandler->>Mediator: throw UnauthorizedException
+        Mediator->>API: propagate
+        API->>User: 401 Unauthorized
+    else Token valid
+        ConfirmHandler->>UserMgr: FindByIdAsync(validatedToken.UserId)
+        activate UserMgr
+        UserMgr->>UserStore: FindByIdAsync(userId)
+        activate UserStore
+        UserStore->>DB: SELECT ... FROM UserAccount WHERE UserAccountID = @Id
+        activate DB
+        DB-->>UserStore: row or null
+        deactivate DB
+        UserStore-->>UserMgr: ApplicationUser or null
+        deactivate UserStore
+        UserMgr-->>ConfirmHandler: ApplicationUser or null
+        deactivate UserMgr
+
+        alt User not found
+            ConfirmHandler->>Mediator: throw UnauthorizedException "User account not found"
+            Mediator->>API: propagate
+            API->>User: 401 Unauthorized
+        else User found
+            ConfirmHandler->>UserStore: SetEmailConfirmedAsync(user, true)
+            Note right of UserStore: IUserEmailStore(ApplicationUser) is injected directly into the handler (not via UserManager), setting the confirmed flag in-memory here
+
+            ConfirmHandler->>UserMgr: UpdateAsync(user)
+            activate UserMgr
+            UserMgr->>UserStore: UpdateAsync(user)
+            activate UserStore
+            UserStore->>DB: UPDATE UserAccount SET ...
+            UserStore->>DB: INSERT INTO UserVerification (UserAccountId, VerificationDateTime)
+            Note right of UserStore: Idempotent — skipped (duplicate-key exception swallowed) if a verification row already exists
+            UserStore-->>UserMgr: IdentityResult.Success
+            deactivate UserStore
+            UserMgr-->>ConfirmHandler: IdentityResult
+            deactivate UserMgr
+
+            ConfirmHandler-->>Mediator: ConfirmationPayload(user.Id, DateTime.UtcNow)
+            deactivate ConfirmHandler
+            Mediator-->>API: ConfirmationPayload
+            deactivate Mediator
+            API->>User: 200 OK {message: "User with ID {id} is confirmed.", payload: {...}}
+        end
+    end
+    deactivate API

docs/web/diagrams/auth/delete-account.md

@@ -0,0 +1,5 @@
+# User Authentication Flow — Delete Account
+
+```mermaid
+--8<-- "web/diagrams/auth/delete-account.mmd"
+```

docs/web/diagrams/auth/delete-account.mmd

@@ -0,0 +1,65 @@
+sequenceDiagram
+    actor User
+    participant API as API Controller
+    participant Mediator as MediatR pipeline<br/>(ValidationBehavior)
+    box Handler Layer
+        participant DeleteAccountHandler
+        participant UserMgr as UserManager(ApplicationUser)
+    end
+    box Repository / Cross-slice
+        participant UserStore as DapperUserStore<br/>(IUserStore/IUserPasswordStore/IUserEmailStore)
+    end
+    participant DB as SQL Server
+
+    User->>API: DELETE /api/auth/account (requires Bearer access token)
+    activate API
+    API->>Mediator: Send(DeleteAccountCommand(GetAuthenticatedUserId()))
+    activate Mediator
+    Mediator->>DeleteAccountHandler: Handle(command)
+    activate DeleteAccountHandler
+
+    DeleteAccountHandler->>UserMgr: FindByIdAsync(userAccountId)
+    activate UserMgr
+    UserMgr->>UserStore: FindByIdAsync(userAccountId)
+    UserStore-->>UserMgr: ApplicationUser or null
+    UserMgr-->>DeleteAccountHandler: ApplicationUser or null
+    deactivate UserMgr
+
+    alt Account not found
+        DeleteAccountHandler->>Mediator: throw NotFoundException
+        Mediator->>API: propagate
+        API->>User: 404 Not Found
+    else Account found
+        DeleteAccountHandler->>UserMgr: DeleteAsync(user)
+        activate UserMgr
+        UserMgr->>UserStore: DeleteAsync(user)
+        activate UserStore
+        UserStore->>DB: DELETE FROM UserAccount WHERE UserAccountID = @Id
+        Note right of UserStore: UserCredential, UserVerification, and UserProfile cascade on delete<br/>(UserAvatar cascades transitively through UserProfile).<br/>Posts, comments, photos, and follows use ON DELETE NO ACTION<br/>if any reference this account, the DELETE throws a foreign key violation (SQL error 547)
+
+        alt Foreign key violation (dependent records exist)
+            UserStore-->>UserMgr: IdentityResult.Failed (AccountHasDependentRecords)
+        else Delete succeeds
+            UserStore-->>UserMgr: IdentityResult.Success
+        end
+        deactivate UserStore
+        UserMgr-->>DeleteAccountHandler: IdentityResult
+        deactivate UserMgr
+
+        alt Account has dependent records
+            DeleteAccountHandler->>Mediator: throw ConflictException<br>"Account cannot be deleted while it still has associated posts, comments, photos, or follows."
+            Mediator->>API: propagate
+            API->>User: 409 Conflict
+        else !result.Succeeded (other failure)
+            DeleteAccountHandler->>Mediator: throw ConflictException
+            Mediator->>API: propagate
+            API->>User: 409 Conflict
+        else result.Succeeded
+            DeleteAccountHandler-->>Mediator: (void)
+            deactivate DeleteAccountHandler
+            Mediator-->>API: (void)
+            deactivate Mediator
+            API->>User: 200 OK {message: "Account deleted successfully."}
+        end
+    end
+    deactivate API

docs/web/diagrams/auth/error-handling.md

@@ -0,0 +1,11 @@
+# User Authentication Flow — Error Handling
+
+Global exception mapping performed by `API.Core`'s `GlobalExceptionFilter`.
+Applies uniformly across every authentication endpoint (registration, login,
+refresh, confirm, resend, update-username/email/password/profile,
+delete-account) — see the per-flow diagrams for where each exception type is
+thrown.
+
+```mermaid
+--8<-- "web/diagrams/auth/error-handling.mmd"
+```

docs/web/diagrams/auth/error-handling.mmd

@@ -0,0 +1,12 @@
+sequenceDiagram
+    participant API as API Controller
+
+    Note over API: GlobalExceptionFilter catches:
+    Note over API: FluentValidation.ValidationException → 400 Bad Request {message, errors} (grouped by property)
+    Note over API: ConflictException → 409 Conflict
+    Note over API: NotFoundException → 404 Not Found
+    Note over API: UnauthorizedException → 401 Unauthorized
+    Note over API: ForbiddenException → 403 Forbidden
+    Note over API: Domain.Exceptions.ValidationException → 400 Bad Request
+    Note over API: Microsoft.Data.SqlClient.SqlException → 503 Service Unavailable
+    Note over API: All others → 500 Internal Server Error

docs/web/diagrams/auth/login.md

@@ -0,0 +1,5 @@
+# User Authentication Flow — Login
+
+```mermaid
+--8<-- "web/diagrams/auth/login.mmd"
+```

docs/web/diagrams/auth/login.mmd

@@ -0,0 +1,93 @@
+sequenceDiagram
+    actor User
+    participant API as API Controller
+    participant Mediator as MediatR pipeline<br/>(ValidationBehavior)
+    box Handler Layer
+        participant LoginHandler
+        participant UserMgr as UserManager(ApplicationUser)
+        participant TokenSvc as TokenService
+    end
+    box Infrastructure Layer
+        participant Argon2 as Argon2PasswordHasher
+        participant JWT as JWT Infrastructure
+    end
+    box Repository / Cross-slice
+        participant UserStore as DapperUserStore<br/>(IUserStore/IUserPasswordStore/IUserEmailStore)
+    end
+    participant DB as SQL Server
+
+    User->>API: POST /api/auth/login {username, password}
+    activate API
+    API->>Mediator: Send(LoginCommand)
+    activate Mediator
+    Note right of Mediator: ValidationBehavior runs LoginValidator — username and password must both be non-empty
+
+    alt Validation fails
+        Mediator->>API: throws FluentValidation.ValidationException
+        API->>User: 400 Bad Request {message, errors}
+    else Validation succeeds
+        Mediator->>LoginHandler: Handle(command)
+        activate LoginHandler
+
+        LoginHandler->>UserMgr: FindByNameAsync(username)
+        activate UserMgr
+        UserMgr->>UserStore: FindByNameAsync(username)
+        activate UserStore
+        UserStore->>DB: SELECT ... FROM UserAccount WHERE Username = @Username
+        activate DB
+        DB-->>UserStore: UserAccount row or null
+        deactivate DB
+        UserStore->>UserStore: Hydrate (active UserCredential.Hash, UserVerification → EmailConfirmed)
+        UserStore-->>UserMgr: ApplicationUser or null
+        deactivate UserStore
+        UserMgr-->>LoginHandler: ApplicationUser or null
+        deactivate UserMgr
+
+        alt User not found
+            LoginHandler->>Mediator: throw UnauthorizedException "Invalid username or password."
+            Mediator->>API: propagate
+            API->>User: 401 Unauthorized
+        else User found
+            LoginHandler->>UserMgr: CheckPasswordAsync(user, password)
+            activate UserMgr
+            Note right of UserMgr: HasPasswordAsync short-circuits to false (no active credential hydrated) without calling the hasher — otherwise delegates to Argon2PasswordHasher
+            UserMgr->>Argon2: VerifyHashedPassword(user, user.PasswordHash, password)
+            activate Argon2
+            Note right of Argon2: Parse stored PHC string ($argon2id$v=19$m=...,t=...,p=...$salt$hash), rehash password with the embedded salt/parameters, constant-time compare (CryptographicOperations.FixedTimeEquals)
+            Argon2-->>UserMgr: Success/Failed
+            deactivate Argon2
+            UserMgr-->>LoginHandler: true/false
+            deactivate UserMgr
+
+            alt Password invalid
+                LoginHandler->>Mediator: throw UnauthorizedException
+                Mediator->>API: propagate
+                API->>User: 401 Unauthorized
+            else Password valid
+                LoginHandler->>TokenSvc: GenerateAccessToken(user)
+                activate TokenSvc
+                TokenSvc->>JWT: GenerateJwt(...)
+                activate JWT
+                JWT-->>TokenSvc: Access Token
+                deactivate JWT
+                TokenSvc-->>LoginHandler: Access Token
+                deactivate TokenSvc
+
+                LoginHandler->>TokenSvc: GenerateRefreshToken(user)
+                activate TokenSvc
+                TokenSvc->>JWT: GenerateJwt(...)
+                activate JWT
+                JWT-->>TokenSvc: Refresh Token
+                deactivate JWT
+                TokenSvc-->>LoginHandler: Refresh Token
+                deactivate TokenSvc
+
+                LoginHandler-->>Mediator: LoginPayload(userAccountId, username, refreshToken, accessToken)
+                deactivate LoginHandler
+                Mediator-->>API: LoginPayload
+                deactivate Mediator
+                API->>User: 200 OK {message: "Logged in successfully.", payload: {...}}
+            end
+        end
+    end
+    deactivate API

docs/web/diagrams/auth/refresh-token.md

@@ -0,0 +1,5 @@
+# User Authentication Flow — Refresh Token
+
+```mermaid
+--8<-- "web/diagrams/auth/refresh-token.mmd"
+```

docs/web/diagrams/auth/refresh-token.mmd

@@ -0,0 +1,77 @@
+sequenceDiagram
+    actor User
+    participant API as API Controller
+    participant Mediator as MediatR pipeline<br/>(ValidationBehavior)
+    box Handler Layer
+        participant RefreshHandler as RefreshTokenHandler
+        participant UserMgr as UserManager(ApplicationUser)
+        participant TokenSvc as TokenService
+    end
+    box Infrastructure Layer
+        participant JWT as JWT Infrastructure
+    end
+    box Repository / Cross-slice
+        participant UserStore as DapperUserStore<br/>(IUserStore/IUserPasswordStore/IUserEmailStore)
+    end
+    participant DB as SQL Server
+
+    User->>API: POST /api/auth/refresh<br/>Header: X-Refresh-Token: {token}
+    activate API
+    API->>Mediator: Send(RefreshTokenCommand(refreshToken))
+    activate Mediator
+    Note right of Mediator: ValidationBehavior runs RefreshTokenValidator — refreshToken must be non-empty. Anonymous endpoint, no Bearer token required.
+
+    alt Validation fails
+        Mediator->>API: throws FluentValidation.ValidationException
+        API->>User: 400 Bad Request {message, errors}
+    else Validation succeeds
+        Mediator->>RefreshHandler: Handle(command)
+        activate RefreshHandler
+
+        RefreshHandler->>TokenSvc: RefreshTokenAsync(refreshToken)
+        activate TokenSvc
+        TokenSvc->>JWT: ValidateRefreshTokenAsync(refreshToken)
+        activate JWT
+        Note right of JWT: Validates signature/expiry against the refresh token secret, extracts userId/username claims
+        JWT-->>TokenSvc: ValidatedToken or throws
+        deactivate JWT
+
+        alt Token invalid or expired
+            TokenSvc->>RefreshHandler: throw UnauthorizedException
+            RefreshHandler->>Mediator: propagate
+            Mediator->>API: propagate
+            API->>User: 401 Unauthorized
+        else Token valid
+            TokenSvc->>UserMgr: FindByIdAsync(validated.UserId)
+            activate UserMgr
+            UserMgr->>UserStore: FindByIdAsync(userId)
+            activate UserStore
+            UserStore->>DB: SELECT ... FROM UserAccount WHERE UserAccountID = @Id
+            activate DB
+            DB-->>UserStore: row or null
+            deactivate DB
+            UserStore-->>UserMgr: ApplicationUser or null
+            deactivate UserStore
+            UserMgr-->>TokenSvc: ApplicationUser or null
+            deactivate UserMgr
+
+            alt User not found
+                TokenSvc->>RefreshHandler: throw UnauthorizedException "User account not found"
+                RefreshHandler->>Mediator: propagate
+                Mediator->>API: propagate
+                API->>User: 401 Unauthorized
+            else User found
+                TokenSvc->>JWT: GenerateAccessToken(user) + GenerateRefreshToken(user)
+                JWT-->>TokenSvc: new access + refresh tokens
+                TokenSvc-->>RefreshHandler: RefreshTokenResult
+                deactivate TokenSvc
+
+                RefreshHandler-->>Mediator: LoginPayload(userId, username, refreshToken, accessToken)
+                deactivate RefreshHandler
+                Mediator-->>API: LoginPayload
+                deactivate Mediator
+                API->>User: 200 OK {message: "Token refreshed successfully.", payload: {...}}
+            end
+        end
+    end
+    deactivate API

docs/web/diagrams/auth/registration.md

@@ -0,0 +1,5 @@
+# User Authentication Flow — Registration
+
+```mermaid
+--8<-- "web/diagrams/auth/registration.mmd"
+```

docs/web/diagrams/auth/registration.mmd

@@ -0,0 +1,165 @@
+sequenceDiagram
+    actor User
+    participant API as API Controller
+    participant Mediator as MediatR pipeline<br/>(ValidationBehavior)
+    box Handler Layer
+        participant RegHandler as RegisterUserHandler
+        participant UserMgr as UserManager(ApplicationUser)
+        participant TokenSvc as TokenService
+    end
+    box Infrastructure Layer
+        participant Argon2 as Argon2PasswordHasher
+        participant JWT as JWT Infrastructure
+        participant SMTP as Email Provider
+        participant Template as Template Provider
+    end
+    box Repository / Cross-slice
+        participant UserStore as DapperUserStore<br/>(IUserStore/IUserPasswordStore/IUserEmailStore)
+        participant ProfileHandler as CreateUserProfileHandler<br/>(Profile slice)
+        participant EmailDispatcher as EmailDispatcher<br/>(Features.Emails)
+    end
+    participant DB as SQL Server
+
+    User->>API: POST /api/auth/register {username, firstName, lastName, email, dateOfBirth, password}
+    activate API
+    API->>Mediator: Send(RegisterUserCommand)
+    activate Mediator
+    Note right of Mediator: ValidationBehavior runs RegisterUserValidator — username 3-64 chars alphanumeric+[._-], valid email ≤128 chars, password min 8 chars with upper/lower/number/special, DateOfBirth 19+ years old
+
+    alt Validation fails
+        Mediator->>API: throws FluentValidation.ValidationException
+        API->>User: 400 Bad Request {message, errors}
+    else Validation succeeds
+        Mediator->>RegHandler: Handle(command)
+        activate RegHandler
+        RegHandler->>RegHandler: user = new UserAccount{...}.ToApplicationUser()
+
+        RegHandler->>UserMgr: CreateAsync(user, password)
+        activate UserMgr
+        UserMgr->>Argon2: HashPassword(user, password)
+        activate Argon2
+        Note right of Argon2: Argon2id — salt 16 bytes, memory 64MB, iterations 4, parallelism 2 (fixed, to avoid thread-pool exhaustion), hash output 32 bytes
+        Argon2-->>UserMgr: PHC string in Argon2id format (algorithm, version, memory/time/parallelism params, salt, hash)
+        deactivate Argon2
+
+        UserMgr->>UserStore: SetPasswordHashAsync(user, hash)
+        Note right of UserStore: user.Id is still empty here — only sets the in-memory hash — CreateAsync writes it to UserCredential itself
+
+        UserMgr->>UserStore: FindByNameAsync(username)
+        activate UserStore
+        UserStore->>DB: SELECT ... FROM UserAccount WHERE Username = @Username
+        activate DB
+        DB-->>UserStore: null (user doesn't exist)
+        deactivate DB
+        deactivate UserStore
+
+        UserMgr->>UserStore: FindByEmailAsync(email)
+        activate UserStore
+        UserStore->>DB: SELECT ... FROM UserAccount WHERE Email = @Email
+        activate DB
+        DB-->>UserStore: null (email doesn't exist)
+        deactivate DB
+        deactivate UserStore
+        Note right of UserMgr: Default UserManager validators check uniqueness before CreateAsync — DapperUserStore.CreateAsync also guards a genuine race via a caught duplicate-key SqlException (2601/2627)
+
+        UserMgr->>UserStore: CreateAsync(user)
+        activate UserStore
+        UserStore->>DB: BEGIN TRANSACTION
+        activate DB
+        UserStore->>DB: INSERT INTO UserAccount (...) OUTPUT INSERTED.UserAccountID
+        DB-->>UserStore: UserAccountId (GUID)
+        UserStore->>DB: INSERT INTO UserCredential (UserAccountId, Hash)
+        UserStore->>DB: COMMIT TRANSACTION
+        deactivate DB
+        Note right of UserStore: Both statements run via Dapper against a single DbTransaction
+
+        UserStore-->>UserMgr: IdentityResult.Success (user.Id set)
+        deactivate UserStore
+        UserMgr-->>RegHandler: IdentityResult
+        deactivate UserMgr
+
+        alt !result.Succeeded
+            RegHandler->>Mediator: throw ConflictException (DuplicateUserName/DuplicateEmail → "Username or email already exists", otherwise joined error descriptions)
+            Mediator->>API: propagate
+            API->>User: 409 Conflict "Username or email already exists"
+        else result.Succeeded
+            RegHandler->>Mediator: Send(CreateUserProfileCommand(user.Id, ""))
+            activate Mediator
+            Mediator->>ProfileHandler: Handle(command)
+            activate ProfileHandler
+            ProfileHandler->>DB: INSERT INTO UserProfile (UserAccountId, Biography)
+            activate DB
+            DB-->>ProfileHandler: UserProfileId
+            deactivate DB
+            ProfileHandler-->>Mediator: UserProfileId
+            deactivate ProfileHandler
+            Mediator-->>RegHandler: UserProfileId
+            deactivate Mediator
+
+            RegHandler->>TokenSvc: GenerateAccessToken(user)
+            activate TokenSvc
+            TokenSvc->>JWT: GenerateJwt(userId, username, expiry)
+            activate JWT
+            Note right of JWT: HS256, expires 1 hour, claims sub/unique_name/iat/jti
+            JWT->>JWT: Create JWT with claims, sign with secret key
+            JWT-->>TokenSvc: Access Token
+            deactivate JWT
+            TokenSvc-->>RegHandler: Access Token
+            deactivate TokenSvc
+
+            RegHandler->>TokenSvc: GenerateRefreshToken(user)
+            activate TokenSvc
+            TokenSvc->>JWT: GenerateJwt(userId, username, expiry)
+            activate JWT
+            Note right of JWT: Expires 21 days (504h), same structure as access token, signed with a separate secret
+            JWT-->>TokenSvc: Refresh Token
+            deactivate JWT
+            TokenSvc-->>RegHandler: Refresh Token
+            deactivate TokenSvc
+
+            RegHandler->>TokenSvc: GenerateConfirmationToken(user)
+            activate TokenSvc
+            TokenSvc->>JWT: GenerateJwt(userId, username, expiry)
+            activate JWT
+            Note right of JWT: Expires 30 minutes, signed with a third, separate secret
+            JWT-->>TokenSvc: Confirmation Token
+            deactivate JWT
+            TokenSvc-->>RegHandler: Confirmation Token
+            deactivate TokenSvc
+
+            RegHandler->>Mediator: Publish(UserRegisteredNotification)
+            activate Mediator
+            Note right of Mediator: Features.Emails has a direct ProjectReference on Features.Users and handles the notification via UserRegisteredNotificationHandler — the second of two cross-slice dispatches in this flow (profile creation is the first)
+            Mediator->>EmailDispatcher: SendRegistrationEmailAsync(firstName, email, confirmationToken)
+            activate EmailDispatcher
+
+            EmailDispatcher->>Template: RenderUserRegisteredEmailAsync(firstName, confirmationLink)
+            activate Template
+            Note right of Template: Razor component — header/branding, welcome message, confirmation button, footer
+            Template->>Template: Render Razor component to HTML
+            Template-->>EmailDispatcher: HTML email content
+            deactivate Template
+
+            EmailDispatcher->>SMTP: SendAsync(email, subject, body)
+            activate SMTP
+            Note right of SMTP: MailKit — host/port from SMTP_HOST/SMTP_PORT, StartTLS when SMTP_USE_SSL=true, optional username/password auth
+            SMTP->>SMTP: Build MIME message, connect, authenticate, send, disconnect
+            SMTP-->>EmailDispatcher: Success / throws
+            deactivate SMTP
+            deactivate EmailDispatcher
+
+            alt Email sent successfully
+                Note right of Mediator: UserRegisteredNotificationHandler completes normally
+            else EmailDispatcher throws
+                Note right of Mediator: UserRegisteredNotificationHandler catches and logs the exception — registration is unaffected
+            end
+            deactivate Mediator
+
+            RegHandler-->>Mediator: RegistrationPayload(userAccountId, username, refreshToken, accessToken)
+            deactivate RegHandler
+            Mediator-->>API: RegistrationPayload
+            deactivate Mediator
+            API->>User: 201 Created {message: "User registered successfully.", payload: {...}}
+        end
+    end
+    deactivate API

docs/web/diagrams/auth/resend-confirmation.md

@@ -0,0 +1,5 @@
+# User Authentication Flow — Resend Confirmation Email
+
+```mermaid
+--8<-- "web/diagrams/auth/resend-confirmation.mmd"
+```

docs/web/diagrams/auth/resend-confirmation.mmd

@@ -0,0 +1,78 @@
+sequenceDiagram
+    actor User
+    participant API as API Controller
+    participant Mediator as MediatR pipeline<br/>(ValidationBehavior)
+    box Handler Layer
+        participant ResendHandler as ResendConfirmationEmailHandler
+        participant UserMgr as UserManager(ApplicationUser)
+        participant TokenSvc as TokenService
+    end
+    box Infrastructure Layer
+        participant SMTP as Email Provider
+        participant Template as Template Provider
+    end
+    box Repository / Cross-slice
+        participant UserStore as DapperUserStore<br/>(IUserStore/IUserPasswordStore/IUserEmailStore)
+        participant EmailDispatcher as EmailDispatcher<br/>(Features.Emails)
+    end
+    participant DB as SQL Server
+
+    User->>API: POST /api/auth/confirm/resend?userId={id} (requires Bearer access token)
+    activate API
+    API->>Mediator: Send(ResendConfirmationEmailCommand(userId))
+    activate Mediator
+    Mediator->>ResendHandler: Handle(command)
+    activate ResendHandler
+
+    ResendHandler->>UserMgr: FindByIdAsync(userId)
+    activate UserMgr
+    UserMgr->>UserStore: FindByIdAsync(userId)
+    activate UserStore
+    UserStore->>DB: SELECT ... FROM UserAccount WHERE UserAccountID = @Id
+    activate DB
+    DB-->>UserStore: row or null
+    deactivate DB
+    UserStore-->>UserMgr: ApplicationUser or null
+    deactivate UserStore
+    UserMgr-->>ResendHandler: ApplicationUser or null
+    deactivate UserMgr
+
+    alt User not found
+        ResendHandler->>ResendHandler: return silently (prevents user enumeration)
+    else User found
+        ResendHandler->>UserMgr: IsEmailConfirmedAsync(user)
+        UserMgr-->>ResendHandler: bool
+
+        alt Already confirmed
+            ResendHandler->>ResendHandler: return silently (no-op)
+        else Not yet confirmed
+            ResendHandler->>TokenSvc: GenerateConfirmationToken(user)
+            activate TokenSvc
+            TokenSvc-->>ResendHandler: confirmation token
+            deactivate TokenSvc
+
+            ResendHandler->>Mediator: Publish(ConfirmationEmailResendRequestedNotification)
+            activate Mediator
+            Note right of Mediator: Features.Emails has a direct ProjectReference on Features.Users and handles the notification via ConfirmationEmailResendRequestedNotificationHandler
+            Mediator->>EmailDispatcher: SendResendConfirmationEmailAsync(firstName, email, confirmationToken)
+            activate EmailDispatcher
+            EmailDispatcher->>Template: Render email (same Razor pipeline as registration)
+            EmailDispatcher->>SMTP: SendAsync(email, subject, body)
+            deactivate EmailDispatcher
+
+            alt Email sent successfully
+                Note right of Mediator: ConfirmationEmailResendRequestedNotificationHandler completes normally
+            else EmailDispatcher throws
+                Note right of Mediator: ConfirmationEmailResendRequestedNotificationHandler catches and logs the exception — the resend request is unaffected
+            end
+            deactivate Mediator
+        end
+    end
+
+    ResendHandler-->>Mediator: (void)
+    deactivate ResendHandler
+    Mediator-->>API: (void)
+    deactivate Mediator
+    API->>User: 200 OK {message: "confirmation email has been resent"}
+    Note right of API: Always 200 OK regardless of outcome above — same user-enumeration precaution as a not-found user or an already-confirmed account
+    deactivate API

docs/web/diagrams/auth/update-email.md

@@ -0,0 +1,5 @@
+# User Authentication Flow — Update Email
+
+```mermaid
+--8<-- "web/diagrams/auth/update-email.mmd"
+```

docs/web/diagrams/auth/update-email.mmd

@@ -0,0 +1,64 @@
+sequenceDiagram
+    actor User
+    participant API as API Controller
+    participant Mediator as MediatR pipeline<br/>(ValidationBehavior)
+    box Handler Layer
+        participant UpdateEmailHandler
+        participant UserMgr as UserManager(ApplicationUser)
+    end
+    box Repository / Cross-slice
+        participant UserStore as DapperUserStore<br/>(IUserStore/IUserPasswordStore/IUserEmailStore)
+    end
+    participant DB as SQL Server
+
+    User->>API: PATCH /api/auth/email {newEmail} (requires Bearer access token)
+    activate API
+    API->>Mediator: Send(UpdateEmailCommand(GetAuthenticatedUserId(), newEmail))
+    activate Mediator
+    Note right of Mediator: ValidationBehavior runs UpdateEmailValidator (same format rules as registration)
+
+    alt Validation fails
+        Mediator->>API: throws FluentValidation.ValidationException
+        API->>User: 400 Bad Request
+    else Validation succeeds
+        Mediator->>UpdateEmailHandler: Handle(command)
+        activate UpdateEmailHandler
+
+        UpdateEmailHandler->>UserMgr: FindByIdAsync(userAccountId)
+        activate UserMgr
+        UserMgr->>UserStore: FindByIdAsync(userAccountId)
+        UserStore->>DB: SELECT ...
+        UserStore-->>UserMgr: ApplicationUser or null
+        UserMgr-->>UpdateEmailHandler: ApplicationUser or null
+        deactivate UserMgr
+
+        alt Account not found
+            UpdateEmailHandler->>Mediator: throw NotFoundException
+            Mediator->>API: propagate
+            API->>User: 404 Not Found
+        else Account found
+            UpdateEmailHandler->>UserMgr: SetEmailAsync(user, newEmail)
+            activate UserMgr
+            UserMgr->>UserStore: FindByEmailAsync(newEmail)
+            Note right of UserMgr: Uniqueness check. Also resets user.EmailConfirmed = false — caller must re-confirm via POST /api/auth/confirm/resend
+            UserMgr->>UserStore: UpdateAsync(user)
+            UserStore->>DB: UPDATE UserAccount SET Email = @Email, ...
+            UserStore->>DB: DELETE FROM UserVerification WHERE UserAccountID = @Id
+            UserStore-->>UserMgr: IdentityResult
+            UserMgr-->>UpdateEmailHandler: IdentityResult
+            deactivate UserMgr
+
+            alt !result.Succeeded
+                UpdateEmailHandler->>Mediator: throw ConflictException (DuplicateEmail → "Email address already exists")
+                Mediator->>API: propagate
+                API->>User: 409 Conflict
+            else result.Succeeded
+                UpdateEmailHandler-->>Mediator: UpdateEmailPayload(user.Id, user.Email, user.EmailConfirmed = false)
+                deactivate UpdateEmailHandler
+                Mediator-->>API: UpdateEmailPayload
+                deactivate Mediator
+                API->>User: 200 OK {message: "Email updated successfully.", payload: {...}}
+            end
+        end
+    end
+    deactivate API

docs/web/diagrams/auth/update-password.md

@@ -0,0 +1,5 @@
+# User Authentication Flow — Update Password
+
+```mermaid
+--8<-- "web/diagrams/auth/update-password.mmd"
+```

docs/web/diagrams/auth/update-password.mmd

@@ -0,0 +1,84 @@
+sequenceDiagram
+    actor User
+    participant API as API Controller
+    participant Mediator as MediatR pipeline<br/>(ValidationBehavior)
+    box Handler Layer
+        participant UpdatePasswordHandler
+        participant UserMgr as UserManager(ApplicationUser)
+    end
+    box Infrastructure Layer
+        participant Argon2 as Argon2PasswordHasher
+    end
+    box Repository / Cross-slice
+        participant UserStore as DapperUserStore<br/>(IUserStore/IUserPasswordStore/IUserEmailStore)
+    end
+    participant DB as SQL Server
+
+    User->>API: PATCH /api/auth/password {currentPassword, newPassword} (requires Bearer access token)
+    activate API
+    API->>Mediator: Send(UpdatePasswordCommand(GetAuthenticatedUserId(), currentPassword, newPassword))
+    activate Mediator
+    Note right of Mediator: ValidationBehavior runs UpdatePasswordValidator (same password strength rules as registration)
+
+    alt Validation fails
+        Mediator->>API: throws FluentValidation.ValidationException
+        API->>User: 400 Bad Request
+    else Validation succeeds
+        Mediator->>UpdatePasswordHandler: Handle(command)
+        activate UpdatePasswordHandler
+
+        UpdatePasswordHandler->>UserMgr: FindByIdAsync(userAccountId)
+        activate UserMgr
+        UserMgr->>UserStore: FindByIdAsync(userAccountId)
+        UserStore-->>UserMgr: ApplicationUser or null
+        UserMgr-->>UpdatePasswordHandler: ApplicationUser or null
+        deactivate UserMgr
+
+        alt Account not found
+            UpdatePasswordHandler->>Mediator: throw NotFoundException
+            Mediator->>API: propagate
+            API->>User: 404 Not Found
+        else Account found
+            UpdatePasswordHandler->>UserMgr: ChangePasswordAsync(user, currentPassword, newPassword)
+            activate UserMgr
+            UserMgr->>Argon2: VerifyHashedPassword(user, user.PasswordHash, currentPassword)
+            activate Argon2
+            Argon2-->>UserMgr: Success/Failed
+            deactivate Argon2
+
+            alt Current password mismatch
+                UserMgr-->>UpdatePasswordHandler: IdentityResult.Failed (PasswordMismatch)
+            else Current password matches
+                UserMgr->>Argon2: HashPassword(user, newPassword)
+                activate Argon2
+                Argon2-->>UserMgr: new hash
+                deactivate Argon2
+                UserMgr->>UserStore: SetPasswordHashAsync(user, newHash)
+                activate UserStore
+                UserStore->>DB: UPDATE UserCredential SET IsRevoked = 1, RevokedAt = GETDATE() WHERE UserAccountId = @Id AND IsRevoked = 0
+                UserStore->>DB: INSERT INTO UserCredential (UserAccountId, Hash)
+                Note right of UserStore: Revoke-then-insert runs inside one DbTransaction (credential rotation)
+                UserStore-->>UserMgr: (void)
+                deactivate UserStore
+                UserMgr-->>UpdatePasswordHandler: IdentityResult.Success
+            end
+            deactivate UserMgr
+
+            alt Current password is incorrect
+                UpdatePasswordHandler->>Mediator: throw UnauthorizedException "Current password is incorrect"
+                Mediator->>API: propagate
+                API->>User: 401 Unauthorized
+            else !result.Succeeded (other failure)
+                UpdatePasswordHandler->>Mediator: throw ConflictException
+                Mediator->>API: propagate
+                API->>User: 409 Conflict
+            else result.Succeeded
+                UpdatePasswordHandler-->>Mediator: UpdatePasswordPayload(user.Id, DateTime.UtcNow)
+                deactivate UpdatePasswordHandler
+                Mediator-->>API: UpdatePasswordPayload
+                deactivate Mediator
+                API->>User: 200 OK {message: "Password updated successfully.", payload: {...}}
+            end
+        end
+    end
+    deactivate API

docs/web/diagrams/auth/update-profile.md

@@ -0,0 +1,5 @@
+# User Authentication Flow — Update Profile
+
+```mermaid
+--8<-- "web/diagrams/auth/update-profile.mmd"
+```

docs/web/diagrams/auth/update-profile.mmd

@@ -0,0 +1,63 @@
+sequenceDiagram
+    actor User
+    participant API as API Controller
+    participant Mediator as MediatR pipeline<br/>(ValidationBehavior)
+    box Handler Layer
+        participant UpdateProfileHandler
+        participant UserMgr as UserManager(ApplicationUser)
+    end
+    box Repository / Cross-slice
+        participant UserStore as DapperUserStore<br/>(IUserStore/IUserPasswordStore/IUserEmailStore)
+    end
+    participant DB as SQL Server
+
+    User->>API: PATCH /api/auth/profile {firstName, lastName, dateOfBirth} (requires Bearer access token)
+    activate API
+    API->>Mediator: Send(UpdateProfileCommand(GetAuthenticatedUserId(), firstName, lastName, dateOfBirth))
+    activate Mediator
+    Note right of Mediator: ValidationBehavior runs UpdateProfileValidator (same name/DateOfBirth rules as registration)
+
+    alt Validation fails
+        Mediator->>API: throws FluentValidation.ValidationException
+        API->>User: 400 Bad Request
+    else Validation succeeds
+        Mediator->>UpdateProfileHandler: Handle(command)
+        activate UpdateProfileHandler
+
+        UpdateProfileHandler->>UserMgr: FindByIdAsync(userAccountId)
+        activate UserMgr
+        UserMgr->>UserStore: FindByIdAsync(userAccountId)
+        UserStore-->>UserMgr: ApplicationUser or null
+        UserMgr-->>UpdateProfileHandler: ApplicationUser or null
+        deactivate UserMgr
+
+        alt Account not found
+            UpdateProfileHandler->>Mediator: throw NotFoundException
+            Mediator->>API: propagate
+            API->>User: 404 Not Found
+        else Account found
+            UpdateProfileHandler->>UpdateProfileHandler: user.FirstName = ...<br/>user.LastName = ...<br/>user.DateOfBirth = ...
+            Note right of UpdateProfileHandler: First/last name and date of birth aren't tracked by any Identity store interface — mutated directly on the ApplicationUser, then saved via UserManager.UpdateAsync
+
+            UpdateProfileHandler->>UserMgr: UpdateAsync(user)
+            activate UserMgr
+            UserMgr->>UserStore: UpdateAsync(user)
+            UserStore->>DB: UPDATE UserAccount SET FirstName = @FirstName, LastName = @LastName, DateOfBirth = @DateOfBirth, ...
+            UserStore-->>UserMgr: IdentityResult
+            UserMgr-->>UpdateProfileHandler: IdentityResult
+            deactivate UserMgr
+
+            alt !result.Succeeded
+                UpdateProfileHandler->>Mediator: throw ConflictException
+                Mediator->>API: propagate
+                API->>User: 409 Conflict
+            else result.Succeeded
+                UpdateProfileHandler-->>Mediator: UpdateProfilePayload(user.Id, firstName, lastName, dateOfBirth)
+                deactivate UpdateProfileHandler
+                Mediator-->>API: UpdateProfilePayload
+                deactivate Mediator
+                API->>User: 200 OK {message: "Profile updated successfully.", payload: {...}}
+            end
+        end
+    end
+    deactivate API

docs/web/diagrams/auth/update-username.md

@@ -0,0 +1,5 @@
+# User Authentication Flow — Update Username
+
+```mermaid
+--8<-- "web/diagrams/auth/update-username.mmd"
+```

docs/web/diagrams/auth/update-username.mmd

@@ -0,0 +1,68 @@
+sequenceDiagram
+    actor User
+    participant API as API Controller
+    participant Mediator as MediatR pipeline<br/>(ValidationBehavior)
+    box Handler Layer
+        participant UpdateUsernameHandler
+        participant UserMgr as UserManager(ApplicationUser)
+    end
+    box Repository / Cross-slice
+        participant UserStore as DapperUserStore<br/>(IUserStore/IUserPasswordStore/IUserEmailStore)
+    end
+    participant DB as SQL Server
+
+    User->>API: PATCH /api/auth/username {newUsername} (requires Bearer access token)
+    activate API
+    API->>Mediator: Send(UpdateUsernameCommand(GetAuthenticatedUserId(), newUsername))
+    activate Mediator
+    Note right of Mediator: ValidationBehavior runs UpdateUsernameValidator (same format rules as registration)
+
+    alt Validation fails
+        Mediator->>API: throws FluentValidation.ValidationException
+        API->>User: 400 Bad Request
+    else Validation succeeds
+        Mediator->>UpdateUsernameHandler: Handle(command)
+        activate UpdateUsernameHandler
+
+        UpdateUsernameHandler->>UserMgr: FindByIdAsync(userAccountId)
+        activate UserMgr
+        UserMgr->>UserStore: FindByIdAsync(userAccountId)
+        activate UserStore
+        UserStore->>DB: SELECT ... FROM UserAccount WHERE UserAccountID = @Id
+        activate DB
+        DB-->>UserStore: row or null
+        deactivate DB
+        UserStore-->>UserMgr: ApplicationUser or null
+        deactivate UserStore
+        UserMgr-->>UpdateUsernameHandler: ApplicationUser or null
+        deactivate UserMgr
+
+        alt Account not found
+            UpdateUsernameHandler->>Mediator: throw NotFoundException
+            Mediator->>API: propagate
+            API->>User: 404 Not Found
+        else Account found
+            UpdateUsernameHandler->>UserMgr: SetUserNameAsync(user, newUsername)
+            activate UserMgr
+            UserMgr->>UserStore: FindByNameAsync(newUsername)
+            Note right of UserMgr: Uniqueness check before the UPDATE
+            UserMgr->>UserStore: UpdateAsync(user)
+            UserStore->>DB: UPDATE UserAccount SET Username = @UserName, ...
+            UserStore-->>UserMgr: IdentityResult
+            UserMgr-->>UpdateUsernameHandler: IdentityResult
+            deactivate UserMgr
+
+            alt !result.Succeeded
+                UpdateUsernameHandler->>Mediator: throw ConflictException (DuplicateUserName → "Username already exists")
+                Mediator->>API: propagate
+                API->>User: 409 Conflict
+            else result.Succeeded
+                UpdateUsernameHandler-->>Mediator: UpdateUsernamePayload(user.Id, user.UserName)
+                deactivate UpdateUsernameHandler
+                Mediator-->>API: UpdateUsernamePayload
+                deactivate Mediator
+                API->>User: 200 OK {message: "Username updated successfully.", payload: {...}}
+            end
+        end
+    end
+    deactivate API

docs/web/diagrams/database-schema.md

@@ -0,0 +1,47 @@
+# Database Schema
+
+Six diagrams, one per SQL Server schema — mirrors the `Auth` / `Geolocation` /
+`Media` / `Brewery` / `Beer` / `Social` schema split under
+`web/backend/Database/Database.Migrations/scripts/`. Every table also has a
+`RowVersion ROWVERSION` column (optimistic concurrency), omitted below for
+brevity. Tables marked `(*)` have no repository/feature slice yet.
+
+Boxes with no attribute list (e.g. `Photo` in the auth diagram) are owned by a
+different schema and shown only to keep the relationship visible; see the
+diagram named after that schema for its full definition.
+
+## Auth (`Auth`)
+
+```mermaid
+--8<-- "web/diagrams/database-schema/auth.mmd"
+```
+
+## Social (`Social`)
+
+```mermaid
+--8<-- "web/diagrams/database-schema/social.mmd"
+```
+
+## Media (`Media`)
+
+```mermaid
+--8<-- "web/diagrams/database-schema/media.mmd"
+```
+
+## Geolocation (`Geolocation`)
+
+```mermaid
+--8<-- "web/diagrams/database-schema/geolocation.mmd"
+```
+
+## Brewery (`Brewery`)
+
+```mermaid
+--8<-- "web/diagrams/database-schema/brewery.mmd"
+```
+
+## Beer (`Beer`)
+
+```mermaid
+--8<-- "web/diagrams/database-schema/beer.mmd"
+```

docs/web/diagrams/database-schema/auth.mmd

@@ -0,0 +1,44 @@
+---
+config:
+    layout: elk
+---
+
+erDiagram
+    User ||--o{ Cred : "has credentials"
+    User ||--o| Verify : "has verification"
+
+    %% Cross-schema: defined in full in social.mmd / media.mmd / brewery.mmd / beer.mmd
+    User ||--o| Profile : "has profile"
+    User ||--o{ Follow : "follows"
+    User ||--o{ Follow : "followed by"
+    User ||--o{ Photo : "uploads"
+    User ||--o{ Brewery : "posts"
+    User ||--o{ Beer : "posts"
+    User ||--o{ BeerComment : "comments"
+
+    User {
+        uniqueidentifier UserAccountID PK
+        varchar Username UK
+        nvarchar FirstName
+        nvarchar LastName
+        varchar Email UK
+        datetime CreatedAt
+        datetime UpdatedAt "nullable"
+        date DateOfBirth
+    }
+
+    Cred {
+        uniqueidentifier UserCredentialID PK
+        uniqueidentifier UserAccountID FK
+        datetime CreatedAt
+        datetime Expiry
+        nvarchar Hash
+        bit IsRevoked
+        datetime RevokedAt "nullable"
+    }
+
+    Verify {
+        uniqueidentifier UserVerificationID PK
+        uniqueidentifier UserAccountID "FK, UK"
+        datetime VerificationDateTime
+    }

docs/web/diagrams/database-schema/beer.mmd

@@ -0,0 +1,51 @@
+---
+config:
+    layout: elk
+---
+
+erDiagram
+    BeerStyle ||--o{ Beer : "categorizes"
+    Beer ||--o{ BeerPhoto : "has photos"
+    Beer ||--o{ BeerComment : "has comments"
+
+    %% Cross-schema: defined in full in auth.mmd / brewery.mmd / media.mmd
+    User ||--o{ Beer : "posts"
+    Brewery ||--o{ Beer : "brews"
+    User ||--o{ BeerComment : "comments"
+    BeerPhoto }o--|| Photo : "uses photo"
+
+    BeerStyle {
+        uniqueidentifier BeerStyleID PK
+        nvarchar StyleName UK
+        nvarchar Description "nullable"
+    }
+
+    Beer {
+        uniqueidentifier BeerPostID PK
+        nvarchar Name
+        nvarchar Description
+        decimal ABV
+        int IBU
+        uniqueidentifier PostedByID FK
+        uniqueidentifier BeerStyleID FK
+        uniqueidentifier BrewedByID FK
+        datetime CreatedAt
+        datetime UpdatedAt "nullable"
+    }
+
+    BeerComment {
+        uniqueidentifier BeerPostCommentID PK
+        nvarchar Comment
+        uniqueidentifier BeerPostID FK
+        uniqueidentifier CommentedByID FK
+        int Rating
+        datetime CreatedAt
+        datetime UpdatedAt "nullable"
+    }
+
+    BeerPhoto {
+        uniqueidentifier BeerPostPhotoID PK
+        uniqueidentifier BeerPostID FK
+        uniqueidentifier PhotoID FK
+        datetime LinkedAt
+    }

docs/web/diagrams/database-schema/brewery.mmd

@@ -0,0 +1,41 @@
+---
+config:
+    layout: elk
+---
+
+
+erDiagram
+    Brewery ||--o| BreweryLocation : "has location"
+    Brewery ||--o{ BreweryPhoto : "has photos"
+    Brewery ||--o{ Beer : "brews"
+
+    %% Cross-schema: defined in full in auth.mmd / geolocation.mmd / media.mmd / beer.mmd
+    User ||--o{ Brewery : "posts"
+    BreweryLocation }o--|| City : "located in"
+    BreweryPhoto }o--|| Photo : "uses photo"
+
+    Brewery {
+        uniqueidentifier BreweryPostID PK
+        nvarchar BreweryName
+        uniqueidentifier PostedByID FK
+        nvarchar Description
+        datetime CreatedAt
+        datetime UpdatedAt "nullable"
+    }
+
+    BreweryLocation {
+        uniqueidentifier BreweryPostLocationID PK
+        uniqueidentifier BreweryPostID "FK, UK"
+        nvarchar AddressLine1
+        nvarchar AddressLine2 "nullable"
+        nvarchar PostalCode
+        uniqueidentifier CityID FK
+        geography Coordinates "nullable"
+    }
+
+    BreweryPhoto {
+        uniqueidentifier BreweryPostPhotoID PK
+        uniqueidentifier BreweryPostID FK
+        uniqueidentifier PhotoID FK
+        datetime LinkedAt
+    }

docs/web/diagrams/database-schema/geolocation.mmd

@@ -0,0 +1,26 @@
+erDiagram
+    Country ||--o{ StateProvince : "has"
+    StateProvince ||--o{ City : "has"
+
+    %% Cross-schema: defined in full in brewery.mmd
+    City ||--o{ BreweryLocation : "located in"
+
+    Country {
+        uniqueidentifier CountryID PK
+        nvarchar CountryName
+        char ISO3166_1 UK
+    }
+
+    StateProvince {
+        uniqueidentifier StateProvinceID PK
+        nvarchar StateProvinceName
+        char ISO3166_2 UK
+        uniqueidentifier CountryID FK
+    }
+
+    %% CityName + StateProvinceID form a composite unique constraint (AK_CityStateProvince)
+    City {
+        uniqueidentifier CityID PK
+        nvarchar CityName UK
+        uniqueidentifier StateProvinceID FK,UK
+    }

docs/web/diagrams/database-schema/media.mmd

@@ -0,0 +1,19 @@
+---
+config:
+    layout: elk
+---
+
+erDiagram
+    User ||--o{ Photo : "uploads"
+
+    %% Cross-schema: defined in full in auth.mmd / social.mmd / brewery.mmd / beer.mmd
+    Avatar }o--|| Photo : "uses photo"
+    Photo ||--o{ BreweryPhoto : "used in"
+    Photo ||--o{ BeerPhoto : "used in"
+
+    Photo {
+        uniqueidentifier PhotoID PK
+        nvarchar Hyperlink "nullable"
+        uniqueidentifier UploadedByID FK
+        datetime UploadedAt
+    }

docs/web/diagrams/database-schema/social.mmd

@@ -0,0 +1,34 @@
+---
+config:
+    layout: elk
+---
+
+erDiagram
+    User ||--o| Profile : "has profile"
+    User ||--o{ Follow : "follows"
+    User ||--o{ Follow : "followed by"
+    Profile ||--o{ Avatar : "has avatar history"
+
+    %% Cross-schema: defined in full in auth.mmd / media.mmd
+    Avatar }o--|| Photo : "uses photo"
+
+    Profile {
+        uniqueidentifier UserProfileID PK
+        uniqueidentifier UserAccountID "FK, UK"
+        nvarchar Biography
+    }
+
+    Follow {
+        uniqueidentifier UserFollowID PK
+        uniqueidentifier UserAccountID FK
+        uniqueidentifier FollowingID FK
+        datetime CreatedAt
+    }
+
+    Avatar {
+        uniqueidentifier UserAvatarID PK
+        uniqueidentifier UserProfileID FK
+        uniqueidentifier PhotoID FK
+        datetime2 ValidFrom
+        datetime2 ValidTo "nullable; at most one row per UserProfileID has ValidTo IS NULL (active avatar)"
+    }

docs/web/diagrams/deployment.md

@@ -0,0 +1,48 @@
+# Docker Deployment Architecture
+
+Five diagrams, one per Compose file — mixing all five networks in one graph made
+it impossible to tell which containers actually talk to each other. Solid arrows
+are real container traffic; dashed arrows are `depends_on` startup gating with
+no data flowing over them.
+
+## Development (`docker-compose.dev.yaml`)
+
+```mermaid
+--8<-- "web/diagrams/deployment/dev.mmd"
+```
+
+## Test (`docker-compose.test.yaml`)
+
+```mermaid
+--8<-- "web/diagrams/deployment/test.mmd"
+```
+
+## Production (`docker-compose.prod.yaml`)
+
+```mermaid
+--8<-- "web/diagrams/deployment/prod.mmd"
+```
+
+## Database-only (`docker-compose.db.yaml`)
+
+```mermaid
+--8<-- "web/diagrams/deployment/db-only.mmd"
+```
+
+## Minimal (`docker-compose.min.yaml`)
+
+```mermaid
+--8<-- "web/diagrams/deployment/minimal.mmd"
+```
+
+## Notes
+
+| Environment                          | Details                                                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Dev network** (`devnet`, bridge)   | Internal DNS resolves service names such as `sqlserver` and `api.core`. Volumes: `sqlserverdata-dev`, `nuget-cache-dev`, `seaweedfsdata-dev`. Startup order: SQL Server (health check) → migrations (run-once) → seed (run-once, depends on `seaweedfs`) → API (long-running, depends on seed).                                                                 |
+| **Test network** (`testnet`, bridge) | All test components are isolated; fresh DB instance each run (`CLEAR_DATABASE=true`, ephemeral `sqlserverdata-test` / `seaweedfsdata-test` volumes). `api.specs`, `unit.tests`, and `frontend.tests` all run as separate containers, in parallel once seeding completes; results are aggregated.                                                                |
+| **Prod network** (`prodnet`, bridge, named `biergarten-prodnet`) | Isolated from dev/test networks. Volumes: `biergartendata-prod` and `seaweedfsdata-prod`, both external, so `down -v` keeps them. Startup order: SeaweedFS (health check) → API (health check) → frontend, with `frontend` the only service publishing a host port, bound to `127.0.0.1`. Migrating and seeding run on demand as their own run-once jobs joining `biergarten-prodnet`, so an `up` or a reboot replays neither.                                                                                                                                                                                                                                                 |
+| **Database-only environment**        | Same devnet volumes/images as `docker-compose.dev.yaml`, minus `api.core`, `frontend`, and `mailpit` — for working against the database (and object storage, since `seaweedfs` is still included) without running the API or website.                                                                                                                           |
+| **Minimal environment**              | Database + migrations + seed + `seaweedfs` + mailpit, no API or frontend container — for frontend development against an `API.Core` process run outside Docker.                                                                                                                                                                                                 |
+| `unit.tests`                         | Builds `Dockerfile.tests`, which restores/builds against `Biergarten.API.slnx` and then runs `dotnet test` for every `Features/*.Tests` project in turn (`Features.Users.Tests`, `Features.Breweries.Tests`, `Features.Emails.Tests`, `Features.PhotoUpload.Tests`), mocking each handler's repository/service dependencies with Moq — no real database needed. |
+| `.trx` results                       | Readable by Visual Studio, Azure DevOps, and GitHub Actions.                                                                                                                                                                                                                                                                                                    |

docs/web/diagrams/deployment/db-only.mmd

@@ -0,0 +1,13 @@
+sequenceDiagram
+    box Database-only Environment (docker-compose.db.yaml)
+    participant DbOnlyDB as SQL Server<br/>:1434
+    participant DbOnlySeaweedFS as seaweedfs<br/>S3-compatible object storage
+    participant DbOnlyMig as Migrations (run-once)
+    participant DbOnlySeed as Seed (run-once)
+    end
+
+    DbOnlyMig-->>DbOnlyDB: depends_on
+    DbOnlyMig->>DbOnlyDB: Run migrations
+    DbOnlySeed-->>DbOnlyMig: depends_on
+    DbOnlySeed-->>DbOnlySeaweedFS: depends_on
+    DbOnlySeed->>DbOnlyDB: Seed data

docs/web/diagrams/deployment/dev.mmd

@@ -0,0 +1,20 @@
+sequenceDiagram
+    actor Developer
+    participant Host as Docker Host
+    box Development Environment (docker-compose.dev.yaml)
+    participant DevDB as SQL Server 2022<br/>Biergarten Database<br/>:1434
+    participant DevMig as Migrations (run-once)<br/>Database.Migrations
+    participant DevSeed as Seed (run-once)<br/>Database.Seed
+    participant DevAPI as API Container<br/>ASP.NET Core 10<br/>:8080 HTTP / :8081 HTTPS
+    participant DevMailpit as Mailpit<br/>:8025 Web UI / :1025 SMTP
+    end
+
+    Developer->>Host: docker compose up
+    DevMig-->>DevDB: depends_on (healthy)
+    DevMig->>DevDB: Run migrations
+    DevSeed-->>DevMig: depends_on
+    DevSeed->>DevDB: Seed data
+    DevAPI-->>DevSeed: depends_on
+    DevAPI->>DevDB: Connect and serve
+    DevAPI-->>DevMailpit: SMTP_HOST/PORT
+    Host->>DevAPI: http://localhost:8080

docs/web/diagrams/deployment/minimal.mmd

@@ -0,0 +1,15 @@
+sequenceDiagram
+    box Minimal Environment (docker-compose.min.yaml)
+    participant MinDB as SQL Server<br/>:1433
+    participant MinSeaweedFS as seaweedfs<br/>S3-compatible object storage
+    participant MinMig as Migrations (run-once)
+    participant MinSeed as Seed (run-once)
+    participant MinMailpit as Mailpit<br/>:8025 / :1025
+    end
+
+    MinMig-->>MinDB: depends_on
+    MinMig->>MinDB: Run migrations
+    MinSeed-->>MinMig: depends_on
+    MinSeed-->>MinSeaweedFS: depends_on
+    MinSeed->>MinDB: Seed data
+    Note over MinDB,MinMailpit: consumed by an externally run API.Core process (not shown)

docs/web/diagrams/deployment/prod.mmd

@@ -0,0 +1,13 @@
+sequenceDiagram
+    box Production Environment (docker-compose.prod.yaml)
+    participant ProdDB as SQL Server 2022<br/>Biergarten Database<br/>no host port published
+    participant ProdS3 as SeaweedFS<br/>S3 gateway :8333<br/>no host port published
+    participant ProdAPI as API Container<br/>ASP.NET Core 10<br/>:8080 HTTP / :8081 HTTPS
+    participant ProdWeb as Frontend Container<br/>Express + React Router<br/>127.0.0.1:5656
+    end
+
+    ProdAPI-->>ProdS3: depends_on: seaweedfs healthy
+    ProdWeb-->>ProdAPI: depends_on: api.core healthy
+    ProdAPI->>ProdDB: Connect and serve
+    ProdAPI->>ProdS3: Store and read photos
+    Note over ProdDB: Migrating and seeding are separate run-once jobs,<br/>run at deploy time rather than by the stack

docs/web/diagrams/deployment/test.mmd

@@ -0,0 +1,29 @@
+sequenceDiagram
+    box Test Environment (docker-compose.test.yaml)
+    participant TestDB as SQL Server, isolated instance<br/>Biergarten Test Database<br/>no host port published
+    participant TestSeaweedFS as seaweedfs<br/>S3-compatible object storage
+    participant TestMig as Migrations (test)
+    participant TestSeed as Seed (test)<br/>minimal: test.user only
+    participant Specs as API.Specs<br/>Reqnroll + xUnit<br/>(integration tests)
+    participant UnitTests as unit.tests<br/>xUnit + Moq<br/>Features.*.Tests, one container
+    participant FrontendTests as frontend.tests<br/>Playwright/Vitest
+    end
+    participant Results as test-results/ (mounted volume)
+
+    TestMig-->>TestDB: depends_on
+    TestMig->>TestDB: Migrate
+    TestSeed-->>TestMig: depends_on
+    TestSeed-->>TestSeaweedFS: depends_on
+    TestSeed->>TestDB: Seed
+
+    par Specs
+        Specs-->>TestSeed: depends_on
+        Specs->>TestDB: Integration test
+        Specs->>Results: Export TRX
+    and unit.tests
+        UnitTests-->>TestSeed: depends_on
+        UnitTests-->>TestDB: depends_on (startup ordering only, no real connection)
+        UnitTests->>Results: Export TRX, one per slice
+    and frontend.tests
+        FrontendTests->>Results: Export results
+    end