remove unused code

remove misleading turn-token output guidance from the brewery prompt
extract the last balanced JSON object before validation
keep README model setup and run instructions aligned
preserve Gemma 4 sampling defaults and local model usage

.config/dotnet-tools.json

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

.csharpierrc.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json.schemastore.org/csharpier.json",
+
+  "printWidth": 80,
+  "useTabs": false,
+  "indentSize": 4,
+  "endOfLine": "lf",
+
+  "overrides": [
+    {
+      "files": "*.xml",
+      "indentSize": 2
+    },
+    {
+      "files": "*.csx",
+      "printWidth": 80
+    }
+  ]
+}

.env.example

@@ -0,0 +1,56 @@
+# ==============================================
+# Biergarten App - Environment Variables Template
+# ==============================================
+#
+# This file contains backend/Docker environment variables.
+# Copy this to create environment-specific files:
+#   - .env.dev (development)
+#   - .env.test (testing)
+#   - .env.prod (production)
+#
+# For frontend variables, create a separate .env.local file
+# in the Website/ directory. See README.md for complete docs.
+#
+# ==============================================
+
+# ======================
+# Database Configuration
+# ======================
+
+# SQL Server Connection Components (Recommended for Docker)
+# These are used to build connection strings dynamically
+DB_SERVER=sqlserver,1433
+DB_NAME=Biergarten
+DB_USER=sa
+DB_PASSWORD=YourStrong!Passw0rd
+
+# Alternative: Full Connection String (Local Development)
+# If set, this overrides the component-based configuration above
+# DB_CONNECTION_STRING=Server=localhost,1433;Database=Biergarten;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;
+
+# ======================
+# JWT Configuration
+# ======================
+
+# JWT Secret for signing tokens
+# IMPORTANT: Generate a secure secret (minimum 32 characters)
+# Command: openssl rand -base64 32
+ACCESS_TOKEN_SECRET=your-secure-jwt-secret-key
+REFRESH_TOKEN_SECRET=your-secure-jwt-refresh-secret-key
+CONFIRMATION_TOKEN_SECRET=your-secure-jwt-confirmation-secret-key
+
+
+# ======================
+# SMTP Configuration
+# ======================
+# SMTP settings for sending emails (e.g., password resets)
+# For development, you can use a local SMTP testing tool like Mailpit or MailHog
+# In production, set these to real SMTP server credentials from an email service
+# provider (e.g., SendGrid, Mailgun, Amazon SES).
+SMTP_HOST=mailpit
+SMTP_PORT=1025
+SMTP_USERNAME=
+SMTP_PASSWORD=
+SMTP_USE_SSL=false
+SMTP_FROM_EMAIL=noreply@thebiergarten.app
+SMTP_FROM_NAME=The Biergarten App

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,43 @@
+---
+name: Feature Request (BDD)
+about: Create a new feature using user story + BDD acceptance criteria
+title: "[Feature] "
+labels: ["feature", "BDD"]
+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)
+
+## Acceptance Criteria (BDD)
+
+### Scenario 1
+
+
+Given ...
+When ...
+Then ...
+
+
+### Scenario 2
+
+
+Given ...
+When ...
+Then ...
+
+
+### Scenario 3
+
+
+Given ...
+When ...
+Then ...
+
+
+## Subtasks
+- [ ] Task 1
+- [ ] Task 2
+- [ ] Task 3

.github/workflows/github-actions-demo.yml

@@ -1,19 +0,0 @@
-name: Node.js CI
-
-on: [push]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
-
-      - name: Use Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: 18
-
-      - name: Install dependencies
-        run: npm ci

.gitignore

@@ -15,6 +15,14 @@
 # production
 /build
 
+# project-specific build artifacts
+/src/Website/build/
+/src/Website/storybook-static/
+/src/Website/.react-router/
+/src/Website/playwright-report/
+/src/Website/test-results/
+/test-results/
+
 # misc
 .DS_Store
 *.pem
@@ -42,7 +50,454 @@ next-env.d.ts
 
 # vscode
 .vscode
+.idea/
+*.swp
+*.swo
 
 /cloudinary-images
 
 .obsidian
+## Ignore Visual Studio temporary files, build results, and
+## files generated by popular Visual Studio add-ons.
+##
+## Get latest from https://github.com/github/gitignore/blob/main/VisualStudio.gitignore
+
+# User-specific files
+*.rsuser
+*.suo
+*.user
+*.userosscache
+*.sln.docstates
+*.env
+
+# User-specific files (MonoDevelop/Xamarin Studio)
+*.userprefs
+
+# Mono auto generated files
+mono_crash.*
+
+# Build results
+[Dd]ebug/
+[Dd]ebugPublic/
+[Rr]elease/
+[Rr]eleases/
+
+[Dd]ebug/x64/
+[Dd]ebugPublic/x64/
+[Rr]elease/x64/
+[Rr]eleases/x64/
+bin/x64/
+obj/x64/
+
+[Dd]ebug/x86/
+[Dd]ebugPublic/x86/
+[Rr]elease/x86/
+[Rr]eleases/x86/
+bin/x86/
+obj/x86/
+
+[Ww][Ii][Nn]32/
+[Aa][Rr][Mm]/
+[Aa][Rr][Mm]64/
+[Aa][Rr][Mm]64[Ee][Cc]/
+bld/
+[Oo]bj/
+[Oo]ut/
+[Ll]og/
+[Ll]ogs/
+
+# Build results on 'Bin' directories
+**/[Bb]in/*
+# Uncomment if you have tasks that rely on *.refresh files to move binaries
+# (https://github.com/github/gitignore/pull/3736)
+#!**/[Bb]in/*.refresh
+
+# Visual Studio 2015/2017 cache/options directory
+.vs/
+# Uncomment if you have tasks that create the project's static files in wwwroot
+#wwwroot/
+
+# Visual Studio 2017 auto generated files
+Generated\ Files/
+
+# MSTest test Results
+[Tt]est[Rr]esult*/
+[Bb]uild[Ll]og.*
+*.trx
+
+# NUnit
+*.VisualState.xml
+TestResult.xml
+nunit-*.xml
+
+# Approval Tests result files
+*.received.*
+
+# Build Results of an ATL Project
+[Dd]ebugPS/
+[Rr]eleasePS/
+dlldata.c
+
+# Benchmark Results
+BenchmarkDotNet.Artifacts/
+
+# .NET Core
+project.lock.json
+project.fragment.lock.json
+artifacts/
+
+# ASP.NET Scaffolding
+ScaffoldingReadMe.txt
+
+# StyleCop
+StyleCopReport.xml
+
+# Files built by Visual Studio
+*_i.c
+*_p.c
+*_h.h
+*.ilk
+*.meta
+*.obj
+*.idb
+*.iobj
+*.pch
+*.pdb
+*.ipdb
+*.pgc
+*.pgd
+*.rsp
+# but not Directory.Build.rsp, as it configures directory-level build defaults
+!Directory.Build.rsp
+*.sbr
+*.tlb
+*.tli
+*.tlh
+*.tmp
+*.tmp_proj
+*_wpftmp.csproj
+*.log
+*.tlog
+*.vspscc
+*.vssscc
+.builds
+*.pidb
+*.svclog
+*.scc
+
+# Chutzpah Test files
+_Chutzpah*
+
+# Visual C++ cache files
+ipch/
+*.aps
+*.ncb
+*.opendb
+*.opensdf
+*.sdf
+*.cachefile
+*.VC.db
+*.VC.VC.opendb
+
+# Visual Studio profiler
+*.psess
+*.vsp
+*.vspx
+*.sap
+
+# Visual Studio Trace Files
+*.e2e
+
+# TFS 2012 Local Workspace
+$tf/
+
+# Guidance Automation Toolkit
+*.gpState
+
+# ReSharper is a .NET coding add-in
+_ReSharper*/
+*.[Rr]e[Ss]harper
+*.DotSettings.user
+
+# TeamCity is a build add-in
+_TeamCity*
+
+# DotCover is a Code Coverage Tool
+*.dotCover
+
+# AxoCover is a Code Coverage Tool
+.axoCover/*
+!.axoCover/settings.json
+
+# Coverlet is a free, cross platform Code Coverage Tool
+coverage*.json
+coverage*.xml
+coverage*.info
+
+# Visual Studio code coverage results
+*.coverage
+*.coveragexml
+
+# NCrunch
+_NCrunch_*
+.NCrunch_*
+.*crunch*.local.xml
+nCrunchTemp_*
+
+# MightyMoose
+*.mm.*
+AutoTest.Net/
+
+# Web workbench (sass)
+.sass-cache/
+
+# Installshield output folder
+[Ee]xpress/
+
+# DocProject is a documentation generator add-in
+DocProject/buildhelp/
+DocProject/Help/*.HxT
+DocProject/Help/*.HxC
+DocProject/Help/*.hhc
+DocProject/Help/*.hhk
+DocProject/Help/*.hhp
+DocProject/Help/Html2
+DocProject/Help/html
+
+# Click-Once directory
+publish/
+
+# Publish Web Output
+*.[Pp]ublish.xml
+*.azurePubxml
+# Note: Comment the next line if you want to checkin your web deploy settings,
+# but database connection strings (with potential passwords) will be unencrypted
+*.pubxml
+*.publishproj
+
+# Microsoft Azure Web App publish settings. Comment the next line if you want to
+# checkin your Azure Web App publish settings, but sensitive information contained
+# in these scripts will be unencrypted
+PublishScripts/
+
+# NuGet Packages
+*.nupkg
+# NuGet Symbol Packages
+*.snupkg
+# The packages folder can be ignored because of Package Restore
+**/[Pp]ackages/*
+# except build/, which is used as an MSBuild target.
+!**/[Pp]ackages/build/
+# Uncomment if necessary however generally it will be regenerated when needed
+#!**/[Pp]ackages/repositories.config
+# NuGet v3's project.json files produces more ignorable files
+*.nuget.props
+*.nuget.targets
+
+# Microsoft Azure Build Output
+csx/
+*.build.csdef
+
+# Microsoft Azure Emulator
+ecf/
+rcf/
+
+# Windows Store app package directories and files
+AppPackages/
+BundleArtifacts/
+Package.StoreAssociation.xml
+_pkginfo.txt
+*.appx
+*.appxbundle
+*.appxupload
+
+# Visual Studio cache files
+# files ending in .cache can be ignored
+*.[Cc]ache
+# but keep track of directories ending in .cache
+!?*.[Cc]ache/
+
+# Others
+ClientBin/
+~$*
+*~
+*.dbmdl
+*.dbproj.schemaview
+*.jfm
+*.pfx
+*.publishsettings
+orleans.codegen.cs
+
+# Including strong name files can present a security risk
+# (https://github.com/github/gitignore/pull/2483#issue-259490424)
+#*.snk
+
+# Since there are multiple workflows, uncomment next line to ignore bower_components
+# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622)
+#bower_components/
+
+# RIA/Silverlight projects
+Generated_Code/
+
+# Backup & report files from converting an old project file
+# to a newer Visual Studio version. Backup files are not needed,
+# because we have git ;-)
+_UpgradeReport_Files/
+Backup*/
+UpgradeLog*.XML
+UpgradeLog*.htm
+ServiceFabricBackup/
+*.rptproj.bak
+
+# SQL Server files
+*.mdf
+*.ldf
+*.ndf
+
+# Business Intelligence projects
+*.rdl.data
+*.bim.layout
+*.bim_*.settings
+*.rptproj.rsuser
+*- [Bb]ackup.rdl
+*- [Bb]ackup ([0-9]).rdl
+*- [Bb]ackup ([0-9][0-9]).rdl
+
+# Microsoft Fakes
+FakesAssemblies/
+
+# GhostDoc plugin setting file
+*.GhostDoc.xml
+
+# Node.js Tools for Visual Studio
+.ntvs_analysis.dat
+node_modules/
+
+# Visual Studio 6 build log
+*.plg
+
+# Visual Studio 6 workspace options file
+*.opt
+
+# Visual Studio 6 auto-generated workspace file (contains which files were open etc.)
+*.vbw
+
+# Visual Studio 6 workspace and project file (working project files containing files to include in project)
+*.dsw
+*.dsp
+
+# Visual Studio 6 technical files
+*.ncb
+*.aps
+
+# Visual Studio LightSwitch build output
+**/*.HTMLClient/GeneratedArtifacts
+**/*.DesktopClient/GeneratedArtifacts
+**/*.DesktopClient/ModelManifest.xml
+**/*.Server/GeneratedArtifacts
+**/*.Server/ModelManifest.xml
+_Pvt_Extensions
+
+# Paket dependency manager
+**/.paket/paket.exe
+paket-files/
+
+# FAKE - F# Make
+**/.fake/
+
+# CodeRush personal settings
+**/.cr/personal
+
+# Python Tools for Visual Studio (PTVS)
+**/__pycache__/
+*.pyc
+
+# Cake - Uncomment if you are using it
+#tools/**
+#!tools/packages.config
+
+# Tabs Studio
+*.tss
+
+# Telerik's JustMock configuration file
+*.jmconfig
+
+# BizTalk build output
+*.btp.cs
+*.btm.cs
+*.odx.cs
+*.xsd.cs
+
+# OpenCover UI analysis results
+OpenCover/
+
+# Azure Stream Analytics local run output
+ASALocalRun/
+
+# MSBuild Binary and Structured Log
+*.binlog
+MSBuild_Logs/
+
+# AWS SAM Build and Temporary Artifacts folder
+.aws-sam
+
+# NVidia Nsight GPU debugger configuration file
+*.nvuser
+
+# MFractors (Xamarin productivity tool) working folder
+**/.mfractor/
+
+# Local History for Visual Studio
+**/.localhistory/
+
+# Visual Studio History (VSHistory) files
+.vshistory/
+
+# BeatPulse healthcheck temp database
+healthchecksdb
+
+# Backup folder for Package Reference Convert tool in Visual Studio 2017
+MigrationBackup/
+
+# Ionide (cross platform F# VS Code tools) working folder
+**/.ionide/
+
+# Fody - auto-generated XML schema
+FodyWeavers.xsd
+
+# VS Code files for those working on multiple tools
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+# Windows Installer files from build outputs
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+.DS_Store
+
+*/data_source/other
+.fake
+.idea
+
+*.feature.cs
+
+.env
+.env.dev
+.env.test
+.env.prod
+
+*storybook.log
+storybook-static

README.md

@@ -1,219 +1,159 @@
 # The Biergarten App
 
-## About
+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 web application designed for beer lovers to share their favorite
-brews and breweries with like-minded people online.
+## Documentation
 
-This application's stack consists of Next.js, Prisma and Neon Postgres. I'm motivated to
-learn more about these technologies while exploring my passion for beer.
+- [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
 
-I've also incorporated different APIs into the application, such as the Cloudinary API for
-image uploading, the SparkPost API for email services as well as Mapbox for geolocation
-and map data.
+## Diagrams
 
-To handle serverless functions (API routes), I use the next-connect package.
+- [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
 
-On the client-side, I use Tailwind CSS, Headless UI and Daisy UI for styling to create a
-visually appealing and user-friendly interface.
+## Current Status
 
-I'm sharing my code publicly so that others can learn from it and use it as a reference
-for their own projects.
+Active areas in the repository:
 
-### Some beer terminology
+- .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
 
-In this app you will encounter various beer related terms. Here is a list of terms used in
-this app and their definitions.
+Legacy area retained for reference:
 
-#### ABV
+- `src/Website-v1` contains the archived Next.js frontend and is no longer the active website
 
-[Alcohol by volume](https://en.wikipedia.org/wiki/Alcohol_by_volume) (abbreviated as ABV)
-is a standard measure of how much alcohol (ethanol) is contained in a given volume of an
-alcoholic beverage (expressed as a volume percent).
+## Tech Stack
 
-#### IBU
+- **Backend**: .NET 10, ASP.NET Core, SQL Server 2022, DbUp
+- **Frontend**: React 19, React Router 7, Vite 7, Tailwind CSS 4, DaisyUI 5
+- **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
 
-The
-[International Bitterness Units](https://en.wikipedia.org/wiki/Beer_measurement#Bitterness)
-scale, or IBU, is used to approximately quantify the bitterness of beer. This scale is not
-measured on the perceived bitterness of the beer, but rather the amount of a component of
-beer known as iso-alpha acids.
+## Quick Start
 
-## Database Schema
-
-![Schema](./schema.svg)
-
-## Technologies
-
-### General
-
-- [Next.js](https://nextjs.org/)
-  - A React based framework for building web applications offering several features such
-    as server side rendering, static site generation and API routes.
-
-### Client
-
-- [SWR](https://swr.vercel.app/)
-  - A React Hooks library for fetching data with support for caching, revalidation and
-    error handling.
-- [Tailwind CSS](https://tailwindcss.com/)
-  - A popular open-source utility-first CSS framework that provides pre-defined classes to
-    style HTML elements.
-- [Headless UI](https://headlessui.dev/)
-  - A set of completely unstyled, fully accessible UI components, designed to integrate
-    beautifully with Tailwind CSS.
-- [Daisy UI](https://daisyui.com/)
-  - A component library for Tailwind CSS that provides ready-to-use components for
-    building user interfaces.
-
-### Server
-
-- [Prisma](https://www.prisma.io/)
-  - An open-source ORM for Node.js and TypeScript applications.
-- [Neon Postgres](https://neon.tech/)
-  - A managed PostgreSQL database service powered by Neon.
-- [Cloudinary](https://cloudinary.com/)
-  - A cloud-based image and video management service that provides developers with an easy
-    way to upload, store, and manipulate media assets.
-- [SparkPost](https://www.sparkpost.com/)
-  - A cloud-based email delivery service that provides developers with an easy way to send
-    transactional and marketing emails.
-- [Mapbox](https://www.mapbox.com/)
-  - A suite of open-source mapping tools that allows developers to add custom maps,
-    search, and navigation into their applications.
-- [next-connect](https://github.com/hoangvvo/next-connect#readme)
-  - A promise-based method routing and middleware layer for Next.js.
-
-## How to run locally
-
-### Prerequisites
-
-Before you can run this application locally, you will need to have the following installed
-on your machine:
-
-- [Node.js](https://nodejs.org/en/)
-- [npm (version 8 or higher)](https://www.npmjs.com/get-npm)
-
-You will also need to create a free account with the following services:
-
-- [Cloudinary](https://cloudinary.com/users/register/free)
-- [SparkPost](https://www.sparkpost.com/)
-- [Neon Postgres](https://neon.tech/)
-- [Mapbox](https://account.mapbox.com/auth/signup/)
-
-### Setup
-
-1. Clone this repository and navigate to the project directory.
+### Backend
 
 ```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
 ```
 
-2. Run the following command to install the dependencies.
+Backend access:
+
+- API Swagger: http://localhost:8080/swagger
+- Health Check: http://localhost:8080/health
+
+### Frontend
 
 ```bash
+cd src/Website
 npm install
+API_BASE_URL=http://localhost:8080 SESSION_SECRET=dev-secret npm run dev
 ```
 
-3. Run the following script to create a `.env` file in the root directory of the project
-   and add the following environment variables. Update these variables with your own
-   values.
+Optional frontend tools:
 
 ```bash
-echo "BASE_URL=
-NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME=
-CLOUDINARY_KEY=
-CLOUDINARY_SECRET=
-CONFIRMATION_TOKEN_SECRET=
-RESET_PASSWORD_TOKEN_SECRET=
-SESSION_SECRET=
-SESSION_TOKEN_NAME=
-SESSION_MAX_AGE=
-NODE_ENV=
-
-POSTGRES_PRISMA_URL=
-POSTGRES_URL_NON_POOLING=
-SHADOW_DATABASE_URL=
-
-ADMIN_PASSWORD=
-
-MAPBOX_ACCESS_TOKEN=
-
-SPARKPOST_API_KEY=
-SPARKPOST_SENDER_ADDRESS=" > .env
+cd src/Website
+npm run storybook
+npm run test:storybook
+npm run test:storybook:playwright
 ```
 
-### Explanation of environment variables
+## Repository Structure
 
-- `BASE_URL` is the base URL of the application.
-  - For example, if you are running the application locally, you can set this to
-    `http://localhost:3000`.
-- `NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME`, `CLOUDINARY_KEY`, and `CLOUDINARY_SECRET` are the
-  credentials for your Cloudinary account.
-  - You can create a free account [here](https://cloudinary.com/users/register/free).
-- `CONFIRMATION_TOKEN_SECRET` is the secret used to sign the confirmation token used for
-  email confirmation.
-  - You can generate a random string using the`openssl rand -base64 127` command.
-- `RESET_PASSWORD_TOKEN_SECRET` is the secret used to sign the reset password token.
-  - You can generate a random string using the `openssl rand -base64 127` command.
-- `SESSION_SECRET` is the secret used to sign the session cookie.
-  - Use the same command as above to generate a random string.
-- `SESSION_TOKEN_NAME` is the name of the session cookie.
-  - You can set this to `biergarten`.
-- `SESSION_MAX_AGE` is the maximum age of the session cookie in seconds.
-  - You can set this to `604800` (1 week).
-- `POSTGRES_PRISMA_URL`is a pooled connection string for your Neon Postgres database.
-- `POSTGRES_URL_NON_POOLING` is a non-pooled connection string for your Neon Postgres
-  database used for migrations.
-- `SHADOW_DATABASE_URL` is a connection string for a secondary database used for
-  migrations to detect schema drift.
-  - You can create a free account [here](https://neon.tech).
-  - Consult the [docs](https://neon.tech/docs/guides/prisma) for more information.
-- `MAPBOX_ACCESS_TOKEN` is the access token for your Mapbox account.
-  - You can create a free account [here](https://account.mapbox.com/auth/signup/).
-- `NODE_ENV` is the environment in which the application is running.
-  - You can set this to `development` or `production`.
-- `SPARKPOST_API_KEY` is the API key for your SparkPost account.
-  - You can create a free account [here](https://www.sparkpost.com/).
-- `SPARKPOST_SENDER_ADDRESS` is the email address that will be used to send emails.
-- `ADMIN_PASSWORD` is the password for the admin account created when seeding the
-  database.
+```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
+```
 
-1. Initialize the database and run the migrations.
+## 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:
 
 ```bash
-npx prisma generate
-npx prisma migrate dev
+docker compose -f docker-compose.test.yaml up --abort-on-container-exit
 ```
 
-5. Seed the database with some initial data.
+See [Testing](docs/testing.md) for the full command list.
 
-```bash
-npm run seed
-```
+## Configuration
 
-6. Start the application.
+Common active variables:
 
-```bash
-npm run dev
-```
+- 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`
 
-## License
+See [Environment Variables](docs/environment-variables.md) for details.
 
-The Biergarten App is licensed under the GNU General Public License v3.0. This means that
-anyone is free to use, modify, and distribute the code as long as they also distribute
-their modifications under the same license.
+## Contributing
 
-I encourage anyone who uses this code for educational purposes to attribute me as the
-original author, and to provide a link to this repository.
+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
 
-By contributing to this repository, you agree to license your contributions under the same
-license as the project.
+### Development Workflow
 
-If you have any questions or concerns about the license, please feel free to submit an
-issue to this repository.
+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`
 
-I hope that this project will be useful to other developers and beer enthusiasts who are
-interested in learning about web development with Next.js, Prisma, Postgres, and other
-technologies.
+## Support
+
+- **Documentation**: [docs/](docs/)
+- **Architecture**: See [Architecture Guide](docs/architecture.md)

docker-compose.db.yaml

@@ -0,0 +1,77 @@
+services:
+ sqlserver:
+    env_file: ".env.dev"
+    image: mcr.microsoft.com/mssql/server:2022-latest
+    platform: linux/amd64
+    container_name: dev-env-sqlserver
+    environment:
+      ACCEPT_EULA: "Y"
+      SA_PASSWORD: "${DB_PASSWORD}"
+      MSSQL_PID: "Express"
+    ports:
+      - "1433:1433"
+    volumes:
+      - sqlserverdata-dev:/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:
+      - devnet
+ database.migrations:
+    env_file: ".env.dev"
+    image: database.migrations
+    container_name: dev-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}"
+      CLEAR_DATABASE: "true"
+    restart: "no"
+    networks:
+      - devnet
+
+ database.seed:
+    env_file: ".env.dev"
+    image: database.seed
+    container_name: dev-env-database-seed
+    depends_on:
+      database.migrations:
+        condition: service_completed_successfully
+    build:
+      context: ./src/Core
+      dockerfile: Database/Database.Seed/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:
+      - devnet
+volumes:
+  sqlserverdata-dev:
+    driver: local
+  nuget-cache-dev:
+    driver: local
+
+networks:
+  devnet:
+    driver: bridge

docker-compose.dev.yaml

@@ -0,0 +1,125 @@
+services:
+  sqlserver:
+    env_file: ".env.dev"
+    image: mcr.microsoft.com/mssql/server:2022-latest
+    platform: linux/amd64
+    container_name: dev-env-sqlserver
+    environment:
+      ACCEPT_EULA: "Y"
+      SA_PASSWORD: "${DB_PASSWORD}"
+      MSSQL_PID: "Express"
+    ports:
+      - "1433:1433"
+    volumes:
+      - sqlserverdata-dev:/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:
+      - devnet
+  database.migrations:
+    env_file: ".env.dev"
+    image: database.migrations
+    container_name: dev-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}"
+      CLEAR_DATABASE: "true"
+    restart: "no"
+    networks:
+      - devnet
+
+  database.seed:
+    env_file: ".env.dev"
+    image: database.seed
+    container_name: dev-env-database-seed
+    depends_on:
+      database.migrations:
+        condition: service_completed_successfully
+    build:
+      context: ./src/Core
+      dockerfile: Database/Database.Seed/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:
+      - devnet
+
+  api.core:
+    env_file: ".env.dev"
+    image: api.core
+    container_name: dev-env-api-core
+    depends_on:
+      database.seed:
+        condition: service_completed_successfully
+    build:
+      context: ./src/Core
+      dockerfile: API/API.Core/Dockerfile
+      args:
+        BUILD_CONFIGURATION: Release
+        APP_UID: 1000
+    ports:
+      - "8080:8080"
+      - "8081:8081"
+    environment:
+      ASPNETCORE_ENVIRONMENT: "Development"
+      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:
+      - devnet
+    volumes:
+      - nuget-cache-dev:/root/.nuget/packages
+
+  mailpit:
+    image: axllent/mailpit:latest
+    container_name: dev-env-mailpit
+    ports:
+      - "8025:8025" # Web UI
+      - "1025:1025" # SMTP server
+
+    restart: unless-stopped
+    environment:
+      MP_SMTP_AUTH_ACCEPT_ANY: 1
+      MP_SMTP_AUTH_ALLOW_INSECURE: 1
+    networks:
+      - devnet
+volumes:
+  sqlserverdata-dev:
+    driver: local
+  nuget-cache-dev:
+    driver: local
+
+networks:
+  devnet:
+    driver: bridge

docker-compose.min.yaml

@@ -0,0 +1,91 @@
+services:
+  sqlserver:
+    env_file: ".env.local"
+    image: mcr.microsoft.com/mssql/server:2022-latest
+    platform: linux/amd64
+    container_name: dev-env-sqlserver
+    environment:
+      ACCEPT_EULA: "Y"
+      SA_PASSWORD: "${DB_PASSWORD}"
+      MSSQL_PID: "Express"
+    ports:
+      - "1433:1433"
+    volumes:
+      - sqlserverdata-dev:/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:
+      - devnet
+  database.migrations:
+    env_file: ".env.local"
+    image: database.migrations
+    container_name: dev-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}"
+      CLEAR_DATABASE: "true"
+    restart: "no"
+    networks:
+      - devnet
+
+  mailpit:
+    image: axllent/mailpit:latest
+    container_name: dev-env-mailpit
+    ports:
+      - "8025:8025" # Web UI
+      - "1025:1025" # SMTP server
+
+    restart: unless-stopped
+    environment:
+      MP_SMTP_AUTH_ACCEPT_ANY: 1
+      MP_SMTP_AUTH_ALLOW_INSECURE: 1
+    networks:
+      - devnet
+
+  database.seed:
+    env_file: ".env.local"
+    image: database.seed
+    container_name: dev-env-database-seed
+    depends_on:
+      database.migrations:
+        condition: service_completed_successfully
+    build:
+      context: ./src/Core
+      dockerfile: Database/Database.Seed/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:
+      - devnet
+volumes:
+  sqlserverdata-dev:
+    driver: local
+  nuget-cache-dev:
+    driver: local
+
+networks:
+  devnet:
+    driver: bridge

docker-compose.prod.yaml

@@ -0,0 +1,87 @@
+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

docker-compose.test.yaml

@@ -0,0 +1,144 @@
+services:
+  sqlserver:
+    env_file: ".env.test"
+    image: mcr.microsoft.com/mssql/server:2022-latest
+    platform: linux/amd64
+    container_name: test-env-sqlserver
+    environment:
+      ACCEPT_EULA: "Y"
+      SA_PASSWORD: "${DB_PASSWORD}"
+      MSSQL_PID: "Express"
+      DOTNET_RUNNING_IN_CONTAINER: "true"
+    volumes:
+      - sqlserverdata-test:/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:
+      - testnet
+
+  database.migrations:
+    env_file: ".env.test"
+    image: database.migrations
+    container_name: test-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}"
+      CLEAR_DATABASE: "true"
+    restart: "no"
+    networks:
+      - testnet
+
+  database.seed:
+    env_file: ".env.test"
+    image: database.seed
+    container_name: test-env-database-seed
+    depends_on:
+      database.migrations:
+        condition: service_completed_successfully
+    build:
+      context: ./src/Core
+      dockerfile: Database/Database.Seed/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:
+      - testnet
+
+  api.specs:
+    env_file: ".env.test"
+    image: api.specs
+    container_name: test-env-api-specs
+    depends_on:
+      database.seed:
+        condition: service_completed_successfully
+    build:
+      context: ./src/Core
+      dockerfile: API/API.Specs/Dockerfile
+      args:
+        BUILD_CONFIGURATION: Release
+    environment:
+      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}"
+    volumes:
+      - ./test-results:/app/test-results
+    restart: "no"
+    networks:
+      - testnet
+
+  repository.tests:
+    env_file: ".env.test"
+    image: repository.tests
+    container_name: test-env-repository-tests
+    depends_on:
+      database.seed:
+        condition: service_completed_successfully
+    build:
+      context: ./src/Core
+      dockerfile: Infrastructure/Infrastructure.Repository.Tests/Dockerfile
+      args:
+        BUILD_CONFIGURATION: Release
+    environment:
+      DOTNET_RUNNING_IN_CONTAINER: "true"
+    volumes:
+      - ./test-results:/app/test-results
+    restart: "no"
+    networks:
+      - testnet
+
+  service.auth.tests:
+    env_file: ".env.test"
+    image: service.auth.tests
+    container_name: test-env-service-auth-tests
+    depends_on:
+      database.seed:
+        condition: service_completed_successfully
+    build:
+      context: ./src/Core
+      dockerfile: Service/Service.Auth.Tests/Dockerfile
+      args:
+        BUILD_CONFIGURATION: Release
+    environment:
+      DOTNET_RUNNING_IN_CONTAINER: "true"
+    volumes:
+      - ./test-results:/app/test-results
+    restart: "no"
+    networks:
+      - testnet
+
+volumes:
+  sqlserverdata-test:
+    driver: local
+
+networks:
+  testnet:
+    driver: bridge

docs/architecture.md

@@ -0,0 +1,427 @@
+# 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

@@ -0,0 +1,56 @@
+# 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

@@ -0,0 +1,75 @@
+@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

@@ -0,0 +1,298 @@
+@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

@@ -0,0 +1,104 @@
+@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

@@ -0,0 +1,227 @@
+@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

@@ -0,0 +1,327 @@
+# 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

@@ -0,0 +1,304 @@
+# 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

@@ -0,0 +1,138 @@
+# 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/testing.md

@@ -0,0 +1,340 @@
+# 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

@@ -0,0 +1,205 @@
+# 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)

misc/raw-data/breweries.csv

@@ -0,0 +1,559 @@
+,name,city,state
+0,NorthGate Brewing ,Minneapolis, MN
+1,Against the Grain Brewery,Louisville, KY
+2,Jack's Abby Craft Lagers,Framingham, MA
+3,Mike Hess Brewing Company,San Diego, CA
+4,Fort Point Beer Company,San Francisco, CA
+5,COAST Brewing Company,Charleston, SC
+6,Great Divide Brewing Company,Denver, CO
+7,Tapistry Brewing,Bridgman, MI
+8,Big Lake Brewing,Holland, MI
+9,The Mitten Brewing Company,Grand Rapids, MI
+10,Brewery Vivant,Grand Rapids, MI
+11,Petoskey Brewing,Petoskey, MI
+12,Blackrocks Brewery,Marquette, MI
+13,Perrin Brewing Company,Comstock Park, MI
+14,Witch's Hat Brewing Company,South Lyon, MI
+15,Founders Brewing Company,Grand Rapids, MI
+16,Flat 12 Bierwerks,Indianapolis, IN
+17,Tin Man Brewing Company,Evansville, IN
+18,Black Acre Brewing Co.,Indianapolis, IN
+19,Brew Link Brewing,Plainfield, IN
+20,Bare Hands Brewery,Granger, IN
+21,Three Pints Brewing,Martinsville, IN
+22,Four Fathers Brewing ,Valparaiso, IN
+23,Indiana City Brewing,Indianapolis, IN
+24,Burn 'Em Brewing,Michigan City, IN
+25,Sun King Brewing Company,Indianapolis, IN
+26,Evil Czech Brewery,Mishawaka, IN
+27,450 North Brewing Company,Columbus, IN
+28,Taxman Brewing Company,Bargersville, IN
+29,Cedar Creek Brewery,Seven Points, TX
+30,SanTan Brewing Company,Chandler, AZ
+31,Boulevard Brewing Company,Kansas City, MO
+32,James Page Brewing Company,Stevens Point, WI
+33,The Dudes' Brewing Company,Torrance, CA
+34,Ballast Point Brewing Company,San Diego, CA
+35,Anchor Brewing Company,San Francisco, CA
+36,Figueroa Mountain Brewing Company,Buellton, CA
+37,Avery Brewing Company,Boulder, CO
+38,Twisted X Brewing Company,Dripping Springs, TX
+39,Gonzo's BiggDogg Brewing,Kalamazoo, MI
+40,Big Muddy Brewing,Murphysboro, IL
+41,Lost Nation Brewing,East Fairfield, VT
+42,Rising Tide Brewing Company,Portland, ME
+43,Rivertowne Brewing Company,Export, PA
+44,Revolution Brewing Company,Chicago, IL
+45,Tallgrass Brewing Company,Manhattan, KS
+46,Sixpoint Craft Ales,Brooklyn, NY
+47,White Birch Brewing,Hooksett, NH
+48,Firestone Walker Brewing Company,Paso Robles, CA
+49,SweetWater Brewing Company,Atlanta, GA
+50,Flying Mouse Brewery,Troutville, VA
+51,Upslope Brewing Company,Boulder, CO
+52,Pipeworks Brewing Company,Chicago, IL
+53,Bent Brewstillery,Roseville, MN
+54,Flesk Brewing Company,Lombard, IL
+55,Pollyanna Brewing Company,Lemont, IL
+56,BuckleDown Brewing,Lyons, IL
+57,Destihl Brewery,Bloomington, IL
+58,Summit Brewing Company,St. Paul, MN
+59,Latitude 42 Brewing Company,Portage, MI
+60,4 Hands Brewing Company,Saint Louis, MO
+61,Surly Brewing Company,Brooklyn Center, MN
+62,Against The Grain Brewery,Louisville, KY
+63,Crazy Mountain Brewing Company,Edwards, CO
+64,SlapShot Brewing Company,Chicago, IL
+65,Mikerphone Brewing,Chicago, IL
+66,Freetail Brewing Company,San Antonio, TX
+67,3 Daughters Brewing,St Petersburg, FL
+68,Red Shedman Farm Brewery and Hop...,Mt. Airy, MD
+69,Appalachian Mountain Brewery,Boone, NC
+70,Birdsong Brewing Company,Charlotte, NC
+71,Union Craft Brewing,Baltimore, MD
+72,Atwater Brewery,Detroit, MI
+73,Ale Asylum,Madison, WI
+74,Two Brothers Brewing Company,Warrenville, IL
+75,Bent Paddle Brewing Company,Duluth, MN
+76,Bell's Brewery,Kalamazoo, MI
+77,Blue Owl Brewing,Austin, TX
+78,Speakasy Ales & Lagers,San Francisco, CA
+79,Black Tooth Brewing Company,Sheridan, WY
+80,Hopworks Urban Brewery,Portland, OR
+81,Epic Brewing,Denver, CO
+82,New Belgium Brewing Company,Fort Collins, CO
+83,Sierra Nevada Brewing Company,Chico, CA
+84,Keweenaw Brewing Company,Houghton, MI
+85,Brewery Terra Firma,Traverse City, MI
+86,Grey Sail Brewing Company,Westerly, RI
+87,Kirkwood Station Brewing Company,Kirkwood, MO
+88,Goose Island Brewing Company,Chicago, IL
+89,Broad Brook Brewing LLC,East Windsor, CT
+90,The Lion Brewery,Wilkes-Barre, PA
+91,Madtree Brewing Company,Cincinnati, OH
+92,Jackie O's Pub & Brewery,Athens, OH
+93,Rhinegeist Brewery,Cincinnati, OH
+94,Warped Wing Brewing Company,Dayton, OH
+95,Blackrocks Brewery,Marquette, MA
+96,Catawba Valley Brewing Company,Morganton, NC
+97,Tröegs Brewing Company,Hershey, PA
+98,Mission Brewery,San Diego, CA
+99,Christian Moerlein Brewing Company,Cincinnati, OH
+100,West Sixth Brewing,Lexington, KY
+101,Coastal Extreme Brewing Company,Newport, RI
+102,King Street Brewing Company,Anchorage, AK
+103,Beer Works Brewery,Lowell, MA
+104,Lone Tree Brewing Company,Lone Tree, CO
+105,Four String Brewing Company,Columbus, OH
+106,Glabrous Brewing Company,Pineland, ME
+107,Bonfire Brewing Company,Eagle, CO
+108,Thomas Hooker Brewing Company,Bloomfield, CT
+109,"Woodstock Inn, Station & Brewery",North Woodstock, NH
+110,Renegade Brewing Company,Denver, CO
+111,Mother Earth Brew Company,Vista, CA
+112,Black Market Brewing Company,Temecula, CA
+113,Vault Brewing Company,Yardley, PA
+114,Jailbreak Brewing Company,Laurel, MD
+115,Smartmouth Brewing Company,Norfolk, VA
+116,Base Camp Brewing Co.,Portland, OR
+117,Alameda Brewing,Portland, OR
+118,Southern Star Brewing Company,Conroe, TX
+119,Steamworks Brewing Company,Durango, CO
+120,Horny Goat Brew Pub,Milwaukee, WI
+121,Cheboygan Brewing Company,Cheboygan, MI
+122,Center of the Universe Brewing C...,Ashland, VA
+123,Ipswich Ale Brewery,Ipswich, MA
+124,Griffin Claw Brewing Company,Birmingham, MI
+125,Karbach Brewing Company,Houston, TX
+126,Uncle Billy's Brewery and Smokeh...,Austin, TX
+127,Deep Ellum Brewing Company,Dallas, TX
+128,Real Ale Brewing Company,Blanco, TX
+129,Straub Brewery,St Mary's, PA
+130,Shebeen Brewing Company,Wolcott, CT
+131,Stevens Point Brewery,Stevens Point, WI
+132,Weston Brewing Company,Weston, MO
+133,Southern Prohibition Brewing Com...,Hattiesburg, MS
+134,Minhas Craft Brewery,Monroe, WI
+135,Pug Ryan's Brewery,Dillon, CO
+136,Hops & Grains Brewing Company,Austin, TX
+137,Sietsema Orchards and Cider Mill,Ada, MI
+138,Summit Brewing Company,St Paul, MN
+139,Core Brewing & Distilling Company,Springdale, AR
+140,Independence Brewing Company,Austin, TX
+141,Cigar City Brewing Company,Tampa, FL
+142,Third Street Brewhouse,Cold Spring, MN
+143,Narragansett Brewing Company,Providence, RI
+144,Grimm Brothers Brewhouse,Loveland, CO
+145,Cisco Brewers,Nantucket, MA
+146,Angry Minnow,Hayward, WI
+147,Platform Beer Company,Cleveland, OH
+148,Odyssey Beerwerks,Arvada, CO
+149,Lonerider Brewing Company,Raleigh, NC
+150,Oakshire Brewing,Eugene, OR
+151,Fort Pitt Brewing Company,Latrobe, PA
+152,Tin Roof Brewing Company,Baton Rouge, LA
+153,Three Creeks Brewing,Sisters, OR
+154,2 Towns Ciderhouse,Corvallis, OR
+155,Caldera Brewing Company,Ashland, OR
+156,Greenbrier Valley Brewing Company,Lewisburg, WV
+157,Phoenix Ale Brewery,Phoenix, AZ
+158,Lumberyard Brewing Company,Flagstaff, AZ
+159,Uinta Brewing Company,Salt Lake City, UT
+160,Four Peaks Brewing Company,Tempe, AZ
+161,Martin House Brewing Company,Fort Worth, TX
+162,Right Brain Brewery,Traverse City, MI
+163,Sly Fox Brewing Company,Phoenixville, PA
+164,Round Guys Brewing,Lansdale, PA
+165,Great Crescent Brewery,Aurora, IN
+166,Oskar Blues Brewery,Longmont, CO
+167,Boxcar Brewing Company,West Chester, PA
+168,High Hops Brewery,Windsor, CO
+169,Crooked Fence Brewing Company,Garden City, ID
+170,Everybody's Brewing,White Salmon, WA
+171,Anderson Valley Brewing Company,Boonville, CA
+172,Fiddlehead Brewing Company,Shelburne, VT
+173,Evil Twin Brewing,Brooklyn, NY
+174,New Orleans Lager & Ale Brewing ...,New Orleans, LA
+175,Spiteful Brewing Company,Chicago, IL
+176,Rahr & Sons Brewing Company,Fort Worth, TX
+177,18th Street Brewery,Gary, IN
+178,Cambridge Brewing Company,Cambridge, MA
+179,Carolina Brewery,Pittsboro, NC
+180,Frog Level Brewing Company,Waynesville, NC
+181,Wild Wolf Brewing Company,Nellysford, VA
+182,COOP Ale Works,Oklahoma City, OK
+183,Seventh Son Brewing Company,Columbus, OH
+184,Oasis Texas Brewing Company,Austin, TX
+185,Vander Mill Ciders,Spring Lake, MI
+186,St. Julian Winery,Paw Paw, MI
+187,Pedernales Brewing Company,Fredericksburg, TX
+188,Mother's Brewing,Springfield, MO
+189,Modern Monks Brewery,Lincoln, NE
+190,Two Beers Brewing Company,Seattle, WA
+191,Snake River Brewing Company,Jackson, WY
+192,Capital Brewery,Middleton, WI
+193,Anthem Brewing Company,Oklahoma City, OK
+194,Goodlife Brewing Co.,Bend, OR
+195,Breakside Brewery,Portland, OR
+196,Goose Island Brewery Company,Chicago, IL
+197,Burnside Brewing Co.,Portland, OR
+198,Hop Valley Brewing Company,Springfield, OR
+199,Worthy Brewing Company,Bend, OR
+200,Occidental Brewing Company,Portland, OR
+201,Fearless Brewing Company,Estacada, OR
+202,Upland Brewing Company,Bloomington, IN
+203,Mehana Brewing Co.,Hilo, HI
+204,Hawai'i Nui Brewing Co.,Hilo, HI
+205,People's Brewing Company,Lafayette, IN
+206,Fort George Brewery,Astoria, OR
+207,Branchline Brewing Company,San Antonio, TX
+208,Kalona Brewing Company,Kalona, IA
+209,Modern Times Beer,San Diego, CA
+210,Temperance Beer Company,Evanston, IL
+211,Wisconsin Brewing Company,Verona, WI
+212,Crow Peak Brewing Company,Spearfish, SD
+213,Grapevine Craft Brewery,Farmers Branch, TX
+214,Buffalo Bayou Brewing Company,Houston, TX
+215,Texian Brewing Co.,Richmond, TX
+216,Orpheus Brewing,Atlanta, GA
+217,Forgotten Boardwalk,Cherry Hill, NJ
+218,Laughing Dog Brewing Company,Ponderay, ID
+219,Bozeman Brewing Company,Bozeman, MT
+220,Big Choice Brewing,Broomfield, CO
+221,Big Storm Brewing Company,Odessa, FL
+222,Carton Brewing Company,Atlantic Highlands, NJ
+223,Midnight Sun Brewing Company,Anchorage, AK
+224,Fat Head's Brewery,Middleburg Heights, OH
+225,Refuge Brewery,Temecula, CA
+226,Chatham Brewing,Chatham, NY
+227,DC Brau Brewing Company,Washington, DC
+228,Geneva Lake Brewing Company,Lake Geneva, WI
+229,Rochester Mills Brewing Company,Rochester, MI
+230,Cape Ann Brewing Company,Gloucester, MA
+231,Borderlands Brewing Company,Tucson, AZ
+232,College Street Brewhouse and Pub,Lake Havasu City, AZ
+233,Joseph James Brewing Company,Henderson, NV
+234,Harpoon Brewery,Boston, MA
+235,Back East Brewing Company,Bloomfield, CT
+236,Champion Brewing Company,Charlottesville, VA
+237,Devil's Backbone Brewing Company,Lexington, VA
+238,Newburgh Brewing Company,Newburgh, NY
+239,Wiseacre Brewing Company,Memphis, TN
+240,Golden Road Brewing,Los Angeles, CA
+241,New Republic Brewing Company,College Station, TX
+242,Infamous Brewing Company,Austin, TX
+243,Two Henrys Brewing Company,Plant City, FL
+244,Lift Bridge Brewing Company,Stillwater, MN
+245,Lucky Town Brewing Company,Jackson, MS
+246,Quest Brewing Company,Greenville, SC
+247,Creature Comforts,Athens, GA
+248,Half Full Brewery,Stamford, CT
+249,Southampton Publick House,Southampton, NY
+250,Chapman's Brewing,Angola, IN
+251,Barrio Brewing Company,Tucson, AZ
+252,Santa Cruz Mountain Brewing,Santa Cruz, CA
+253,Frankenmuth Brewery,Frankenmuth, MI
+254,Meckley's Cidery,Somerset Center, MI
+255,Stillwater Artisanal Ales,Baltimore, MD
+256,Finch's Beer Company,Chicago, IL
+257,South Austin Brewery,South Austin, TX
+258,Bauhaus Brew Labs,Minneapolis, MN
+259,Ozark Beer Company,Rogers, AR
+260,Mountain Town Brewing Company ,Mount Pleasant, MI
+261,Otter Creek Brewing,Waterbury, VT
+262,The Brewer's Art,Baltimore, MD
+263,Denver Beer Company,Denver, CO
+264,Ska Brewing Company,Durango, CO
+265,Tractor Brewing Company,Albuquerque, NM
+266,Peak Organic Brewing Company,Portland, ME
+267,Cape Cod Beer,Hyannis, MA
+268,Long Trail Brewing Company,Bridgewater Corners, VT
+269,Great Raft Brewing Company,Shreveport, LA
+270,Alaskan Brewing Company,Juneau, AK
+271,Notch Brewing Company,Ipswich, MA
+272,The Alchemist,Waterbury, VT
+273,Three Notch'd Brewing Company,Charlottesville, VA
+274,Portside Brewery,Cleveland, OH
+275,Otter Creek Brewing,Middlebury, VT
+276,Montauk Brewing Company,Montauk, NY
+277,Indeed Brewing Company,Minneapolis, MN
+278,Berkshire Brewing Company,South Deerfield, MA
+279,Foolproof Brewing Company,Pawtucket, RI
+280,Headlands Brewing Company,Mill Valley, CA
+281,Bolero Snort Brewery,Ridgefield Park, NJ
+282,Thunderhead Brewing Company,Kearney, NE
+283,Defiance Brewing Company,Hays, KS
+284,Milwaukee Brewing Company,Milwaukee, WI
+285,Catawba Island Brewing,Port Clinton, OH
+286,Back Forty Beer Company,Gadsden, AL
+287,Four Corners Brewing Company,Dallas, TX
+288,Saint Archer Brewery,San Diego, CA
+289,Rogue Ales,Newport, OR
+290,Hale's Ales,Seattle, WA
+291,Tommyknocker Brewery,Idaho Springs, CO
+292,Baxter Brewing Company,Lewiston, ME
+293,Northampton Brewery,Northamtpon, MA
+294,Black Shirt Brewing Company,Denver, CO
+295,Wachusett Brewing Company,Westminster, MA
+296,Widmer Brothers Brewing Company,Portland, OR
+297,Hop Farm Brewing Company,Pittsburgh, PA
+298,Liquid Hero Brewery,York, PA
+299,Matt Brewing Company,Utica, NY
+300,Boston Beer Company,Boston, MA
+301,Old Forge Brewing Company,Danville, PA
+302,Utah Brewers Cooperative,Salt Lake City, UT
+303,Magic Hat Brewing Company,South Burlington, VT
+304,Blue Hills Brewery,Canton, MA
+305,Night Shift Brewing,Everett, MA
+306,Beach Brewing Company,Virginia Beach, VA
+307,Payette Brewing Company,Garden City, ID
+308,Brew Bus Brewing,Tampa, FL
+309,Sockeye Brewing Company,Boise, ID
+310,Pine Street Brewery,San Francisco, CA
+311,Dirty Bucket Brewing Company,Woodinville, WA
+312,Jackalope Brewing Company,Nashville, TN
+313,Slanted Rock Brewing Company,Meridian, ID
+314,Piney River Brewing Company,Bucryus, MO
+315,Cutters Brewing Company,Avon, IN
+316,Iron Hill Brewery & Restaurant,Wilmington, DE
+317,Marshall Wharf Brewing Company,Belfast, ME
+318,Banner Beer Company,Williamsburg, MA
+319,Dick's Brewing Company,Centralia, WA
+320,Claremont Craft Ales,Claremont, CA
+321,Rivertown Brewing Company,Lockland, OH
+322,Voodoo Brewery,Meadville, PA
+323,D.L. Geary Brewing Company,Portland, ME
+324,Pisgah Brewing Company,Black Mountain, NC
+325,Neshaminy Creek Brewing Company,Croydon, PA
+326,Morgan Street Brewery,Saint Louis, MO
+327,Half Acre Beer Company,Chicago, IL
+328,The Just Beer Project,Burlington, VT
+329,The Bronx Brewery,Bronx, NY
+330,Dead Armadillo Craft Brewing,Tulsa, OK
+331,Catawba Brewing Company,Morganton, NC
+332,La Cumbre Brewing Company,Albuquerque, NM
+333,David's Ale Works,Diamond Springs, CA
+334,The Traveler Beer Company,Burlington, VT
+335,Fargo Brewing Company,Fargo, ND
+336,Big Sky Brewing Company,Missoula, MT
+337,Nebraska Brewing Company,Papillion, NE
+338,Uncle John's Fruit House Winery,St. John's, MI
+339,Wormtown Brewery,Worcester, MA
+340,Due South Brewing Company,Boynton Beach, FL
+341,Palisade Brewing Company,Palisade, CO
+342,KelSo Beer Company,Brooklyn, NY
+343,Hardywood Park Craft Brewery,Richmond, VA
+344,Wolf Hills Brewing Company,Abingdon, VA
+345,Lavery Brewing Company,Erie, PA
+346,Manzanita Brewing Company,Santee, CA
+347,Fullsteam Brewery,Durham, NC
+348,Four Horsemen Brewing Company,South Bend, IN
+349,Hinterland Brewery,Green Bay, WI
+350,Central Coast Brewing Company,San Luis Obispo, CA
+351,Westfield River Brewing Company,Westfield, MA
+352,Elevator Brewing Company,Columbus, OH
+353,Aslan Brewing Company,Bellingham, WA
+354,Kulshan Brewery,Bellingham, WA
+355,Pikes Peak Brewing Company,Monument, CO
+356,Manayunk Brewing Company,Philadelphia, PA
+357,Buckeye Brewing,Cleveland, OH
+358,Daredevil Brewing Company,Shelbyville, IN
+359,NoDa Brewing Company,Charlotte, NC
+360,Aviator Brewing Company,Fuquay-Varina, NC
+361,Wild Onion Brewing Company,Lake Barrington, IL
+362,Hilliard's Beer,Seattle, WA
+363,Mikkeller,Pottstown, PA
+364,Bohemian Brewery,Midvale, UT
+365,Great River Brewery,Davenport, IA
+366,Mustang Brewing Company,Mustang, OK
+367,Airways Brewing Company,Kent, WA
+368,21st Amendment Brewery,San Francisco, CA
+369,Eddyline Brewery & Restaurant,Buena Vista, CO
+370,Pizza Port Brewing Company,Carlsbad, CA
+371,Sly Fox Brewing Company,Pottstown, PA
+372,Spring House Brewing Company,Conestoga, PA
+373,7venth Sun,Dunedin, FL
+374,Astoria Brewing Company,Astoria, OR
+375,Maui Brewing Company,Lahaina, HI
+376,RoughTail Brewing Company,Midwest City, OK
+377,Lucette Brewing Company,Menominee, WI
+378,Bold City Brewery,Jacksonville, FL
+379,Grey Sail Brewing of Rhode Island,Westerly, RI
+380,Blue Blood Brewing Company,Lincoln, NE
+381,Swashbuckler Brewing Company,Manheim, PA
+382,Blue Mountain Brewery,Afton, VA
+383,Starr Hill Brewery,Crozet, VA
+384,Westbrook Brewing Company,Mt. Pleasant, SC
+385,Shipyard Brewing Company,Portland, ME
+386,Revolution Brewing,Paonia, CO
+387,Natian Brewery,Portland, OR
+388,Alltech's Lexington Brewing Company,Lexington, KY
+389,Oskar Blues Brewery (North Carol...,Brevard, NC
+390,Orlison Brewing Company,Airway Heights, WA
+391,Breckenridge Brewery,Denver, CO
+392,Santa Fe Brewing Company,Santa Fe, NM
+393,Miami Brewing Company,Miami, FL
+394,Schilling & Company,Seattle, WA
+395,Hops & Grain Brewery,Austin, TX
+396,White Flame Brewing Company,Hudsonville, MI
+397,Ruhstaller Beer Company,Sacramento, CA
+398,Saugatuck Brewing Company,Douglas, MI
+399,Moab Brewery,Moab, UT
+400,Macon Beer Company,Macon, GA
+401,Amnesia Brewing Company,Washougal, WA
+402,Wolverine State Brewing Company,Ann Arbor, MI
+403,Red Tank Cider Company,Bend, OR
+404,Cascadia Ciderworks United,Portland, OR
+405,Fate Brewing Company,Boulder, CO
+406,Lazy Monk Brewing,Eau Claire, WI
+407,Bitter Root Brewing,Hamilton, MT
+408,10 Barrel Brewing Company,Bend, OR
+409,Tamarack Brewing Company,Lakeside, MT
+410,New England Brewing Company,Woodbridge, CT
+411,Seattle Cider Company,Seattle, WA
+412,Straight to Ale,Huntsville, AL
+413,Austin Beerworks,Austin, TX
+414,Blue Mountain Brewery,Arrington, VA
+415,Coastal Empire Beer Company,Savannah, GA
+416,Jack's Hard Cider (Hauser Estate...,Biglerville, PA
+417,Boulder Beer Company,Boulder, CO
+418,Coalition Brewing Company,Portland, OR
+419,Sanitas Brewing Company,Boulder, CO
+420,Gore Range Brewery,Edwards, CO
+421,Redstone Meadery,Boulder, CO
+422,Blue Dog Mead,Eugene, OR
+423,Hess Brewing Company,San Diego, CA
+424,Wynkoop Brewing Company,Denver, CO
+425,Ciderboys,Stevens Point, WI
+426,Armadillo Ale Works,Denton, TX
+427,Roanoke Railhouse Brewery,Roanoke, VA
+428,Schlafly Brewing Company,Saint Louis, MO
+429,Asher Brewing Company,Boulder, CO
+430,Lost Rhino Brewing Company,Ashburn, VA
+431,North Country Brewing Company,Slippery Rock, PA
+432,Seabright Brewery,Santa Cruz, CA
+433,French Broad Brewery,Asheville, NC
+434,Angry Orchard Cider Company,Cincinnati, OH
+435,Two Roads Brewing Company,Stratford, CT
+436,Southern Oregon Brewing Company,Medford, OR
+437,Brooklyn Brewery,Brooklyn, NY
+438,The Right Brain Brewery,Traverse City, MI
+439,Kona Brewing Company,Kona, HI
+440,MillKing It Productions,Royal Oak, MI
+441,Pateros Creek Brewing Company,Fort Collins, CO
+442,O'Fallon Brewery,O'Fallon, MO
+443,Marble Brewery,Albuquerque, NM
+444,Big Wood Brewery,Vadnais Heights, MN
+445,Howard Brewing Company,Lenoir, NC
+446,Downeast Cider House,Leominster, MA
+447,Swamp Head Brewery,Gainesville, FL
+448,Mavericks Beer Company,Half Moon Bay, CA
+449,TailGate Beer,San Diego, CA
+450,Northwest Brewing Company,Pacific, WA
+451,Dad & Dude's Breweria,Aurora, CO
+452,Centennial Beer Company,Edwards, CO
+453,Denali Brewing Company,Talkeetna, AK
+454,Deschutes Brewery,Bend, OR
+455,Sunken City Brewing Company,Hardy, VA
+456,Lucette Brewing Company,Menominie, WI
+457,The Black Tooth Brewing Company,Sheridan, WY
+458,Kenai River Brewing Company,Soldotna, AK
+459,River North Brewery,Denver, CO
+460,Fremont Brewing Company,Seattle, WA
+461,Armstrong Brewing Company,South San Francisco, CA
+462,AC Golden Brewing Company,Golden, CO
+463,Big Bend Brewing Company,Alpine, TX
+464,Good Life Brewing Company,Bend, OR
+465,Engine 15 Brewing,Jacksonville Beach, FL
+466,Green Room Brewing,Jacksonville, FL
+467,Brindle Dog Brewing Company,Tampa Bay, FL
+468,Peace Tree Brewing Company,Knoxville, IA
+469,Terrapin Brewing Company,Athens, GA
+470,Pete's Brewing Company,San Antonio, TX
+471,Okoboji Brewing Company,Spirit Lake, IA
+472,Crystal Springs Brewing Company,Boulder, CO
+473,Engine House 9,Tacoma, WA
+474,Tonka Beer Company,Minnetonka, MN
+475,Red Hare Brewing Company,Marietta, GA
+476,Hangar 24 Craft Brewery,Redlands, CA
+477,Big Elm Brewing,Sheffield, MA
+478,Good People Brewing Company,Birmingham, AL
+479,Heavy Seas Beer,Halethorpe, MD
+480,Telluride Brewing Company,Telluride, CO
+481,7 Seas Brewing Company,Gig Harbor, WA
+482,Confluence Brewing Company,Des Moines, IA
+483,Bale Breaker Brewing Company,Yakima, WA
+484,The Manhattan Brewing Company,New York, NY
+485,MacTarnahans Brewing Company,Portland, OR
+486,Stillmank Beer Company,Green Bay, WI
+487,Redhook Brewery,Woodinville, WA
+488,Dock Street Brewery,Philadelphia, PA
+489,Blue Point Brewing Company,Patchogue, NY
+490,Tampa Bay Brewing Company,Tampa, FL
+491,Devil's Canyon Brewery,Belmont, CA
+492,Stone Coast Brewing Company,Portland, ME
+493,Broken Tooth Brewing Company,Anchorage, AK
+494,Seven Brides Brewery,Silverton, OR
+495,Newburyport Brewing Company,Newburyport, MA
+496,Dry Dock Brewing Company,Aurora, CO
+497,Cans Bar and Canteen,Charlotte, NC
+498,Sprecher Brewing Company,Glendale, WI
+499,Wildwood Brewing Company,Stevensville, MT
+500,High Noon Saloon And Brewery,Leavenworth, KS
+501,Woodchuck Hard Cider,Middlebury, VT
+502,Sea Dog Brewing Company,Portland, ME
+503,Oskar Blues Brewery,Lyons, CO
+504,Carolina Beer & Beverage,Mooresville, NC
+505,Krebs Brewing Company (Pete's Pl...,Krebs, OK
+506,Warbird Brewing Company,Fort Wayne, IN
+507,Mudshark Brewing Company,Lake Havasu City, AZ
+508,Spilker Ales,Cortland, NE
+509,Wingman Brewers,Tacoma, WA
+510,Kettle House Brewing Company,Missoula, MT
+511,Sherwood Forest Brewers,Marlborough, MA
+512,Cottrell Brewing,Pawcatuck, CT
+513,Arctic Craft Brewery,Colorado Springs, CO
+514,Monkey Paw Pub & Brewery,San Diego, CA
+515,Crabtree Brewing Company,Greeley, CO
+516,Emerald City Beer Company,Seattle, WA
+517,Butcher's Brewing,Carlsbad, CA
+518,New South Brewing Company,Myrtle Beach, SC
+519,Big River Brewing Company,Chattanooga, TN
+520,Twisted Pine Brewing Company,Boulder, CO
+521,Flying Dog Brewery,Frederick, MD
+522,Uncommon Brewers,Santa Cruz, CA
+523,Aspen Brewing Company,Aspen, CO
+524,Triangle Brewing Company,Durham, NC
+525,Bomb Beer Company,New York, NY
+526,Churchkey Can Company,Seattle, WA
+527,Intuition Ale Works,Jacksonville, FL
+528,Asheville Brewing Company,Asheville, NC
+529,Northwoods Brewpub,Eau Claire, WI
+530,Buckbean Brewing Company,Reno, NV
+531,Dolores River Brewery,Dolores, CO
+532,Flat Rock Brewing Company,Smithton, PA
+533,Abita Brewing Company,Abita Springs, LA
+534,Mammoth Brewing Company,Mammoth Lakes, CA
+535,Harvest Moon Brewing Company,Belt, MT
+536,Grand Canyon Brewing Company,Williams, AZ
+537,Lewis and Clark Brewing Company,Helena, MT
+538,Dundee Brewing Company,Rochester, NY
+539,Twin Lakes Brewing Company,Greenville, DE
+540,Mother Earth Brewing Company,Kinston, NC
+541,Arcadia Brewing Company,Battle Creek, MI
+542,Angry Minnow Brewing Company,Hayward, WI
+543,Great Northern Brewing Company,Whitefish, MT
+544,Pyramid Breweries,Seattle, WA
+545,Lancaster Brewing Company,Lancaster, PA
+546,Upstate Brewing Company,Elmira, NY
+547,Moat Mountain Smoke House & Brew...,North Conway, NH
+548,Prescott Brewing Company,Prescott, AZ
+549,Mogollon Brewing Company,Flagstaff, AZ
+550,Wind River Brewing Company,Pinedale, WY
+551,Silverton Brewery,Silverton, CO
+552,Mickey Finn's Brewery,Libertyville, IL
+553,Covington Brewhouse,Covington, LA
+554,Dave's Brewfarm,Wilson, WI
+555,Ukiah Brewing Company,Ukiah, CA
+556,Butternuts Beer and Ale,Garrattsville, NY
+557,Sleeping Lady Brewing Company,Anchorage, AK

misc/raw-data/ontariobreweries.json

@@ -0,0 +1,578 @@
+[
+  {
+    "text": "100 Acre Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/100-acre-brewing-company/"
+  },
+  {
+    "text": "All My Friends Beer Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/all-my-friends-beer-co/"
+  },
+  {
+    "text": "All or Nothing Brewhouse",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/all-or-nothing-brewhouse/"
+  },
+  {
+    "text": "Anderson Craft Ales",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/anderson-craft-ales/"
+  },
+  {
+    "text": "Badlands Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/badlands-brewing-company/"
+  },
+  {
+    "text": "Bancroft Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/bancroft-brewing-co/"
+  },
+  {
+    "text": "Banded Goose Brewing Comany",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/banded-goose-brewing-comany/"
+  },
+  {
+    "text": "Beau’s Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/beaus-brewery/"
+  },
+  {
+    "text": "BeerLab! London",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/beerlab-london/"
+  },
+  {
+    "text": "Bellwoods Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/bellwoods-brewery/"
+  },
+  {
+    "text": "Bench Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/bench-brewing/"
+  },
+  {
+    "text": "Beyond The Pale Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/beyond-the-pale-brewing-co/"
+  },
+  {
+    "text": "Bicycle Craft Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/bicycle-craft-brewery/"
+  },
+  {
+    "text": "Big Rig Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/big-rig-brewery/"
+  },
+  {
+    "text": "Big Rock Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/big-rock-brewery/"
+  },
+  {
+    "text": "Black Gold Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/black-gold-brewery/"
+  },
+  {
+    "text": "Black Oak Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/black-oak-brewing-co/"
+  },
+  {
+    "text": "Block 3 Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/block-3-brewing-co/"
+  },
+  {
+    "text": "Blood Brothers Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/blood-brothers-brewing/"
+  },
+  {
+    "text": "Bobcaygeon Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/bobcaygeon-brewing-company/"
+  },
+  {
+    "text": "Boshkung Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/boshkung-brewing-co/"
+  },
+  {
+    "text": "Brauwerk Hoffman – Rockland",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/brauwerk-hoffman-rockland/"
+  },
+  {
+    "text": "Bridge Masters Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/bridge-masters-brewing-co/"
+  },
+  {
+    "text": "Broadhead Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/broadhead-brewery/"
+  },
+  {
+    "text": "Broken Rail Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/broken-rail-brewing/"
+  },
+  {
+    "text": "Burdock Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/burdock-brewery/"
+  },
+  {
+    "text": "C’est What Durham Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/cest-what-durham-brewing-company/"
+  },
+  {
+    "text": "Calabogie Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/calabogie-brewing/"
+  },
+  {
+    "text": "Cameron’s Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/camerons-brewing-company/"
+  },
+  {
+    "text": "Canvas Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/canvas-brewing-co/"
+  },
+  {
+    "text": "Caps Off Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/caps-off-brewing/"
+  },
+  {
+    "text": "Century Barn Brewing & Beverage Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/century-barn-brewing-and-beverage-company/"
+  },
+  {
+    "text": "Chronicle Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/chronicle-brewing-company/"
+  },
+  {
+    "text": "Clifford Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/clifford-brewing-co/"
+  },
+  {
+    "text": "Cold Bear Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/cold-bear-brewing-co/"
+  },
+  {
+    "text": "Collective Arts Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/collective-arts-brewing-ltd/"
+  },
+  {
+    "text": "Common Good Beer Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/common-good-beer-co/"
+  },
+  {
+    "text": "Couchiching Craft Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/couchiching-craft-brewing-company/"
+  },
+  {
+    "text": "Cowbell Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/cowbell-brewing-co/"
+  },
+  {
+    "text": "Cured Craft Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/cured-craft-brewing-co/"
+  },
+  {
+    "text": "Daft Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/daft-brewing-company/"
+  },
+  {
+    "text": "Dog House Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/dog-house-brewing-company/"
+  },
+  {
+    "text": "Dominion City Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/dominion-city-brewing-co/"
+  },
+  {
+    "text": "Eastbound Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/eastbound-brewing-co/"
+  },
+  {
+    "text": "Equals Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/equals-brewing-company/"
+  },
+  {
+    "text": "Fairweather Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/fairweather-brewing-company/"
+  },
+  {
+    "text": "Farm League Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/farm-league-brewing/"
+  },
+  {
+    "text": "Fixed Gear Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/fixed-gear-brewing-co/"
+  },
+  {
+    "text": "Flying Monkeys Craft Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/flying-monkeys-craft-brewery/"
+  },
+  {
+    "text": "Focal Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/focal-brewing-co/"
+  },
+  {
+    "text": "Foundry Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/foundry-brewing/"
+  },
+  {
+    "text": "Four Fathers Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/four-fathers-brewing-co/"
+  },
+  {
+    "text": "Frank Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/frank-brewing-co/"
+  },
+  {
+    "text": "Freddy’s",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/freddys/"
+  },
+  {
+    "text": "Full Beard Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/1068-2/"
+  },
+  {
+    "text": "Furnace Room Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/furnace-room-brewery/"
+  },
+  {
+    "text": "Gateway City Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/gateway-city-brewery/"
+  },
+  {
+    "text": "Glasstown Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/glasstown-brewing-company/"
+  },
+  {
+    "text": "Godspeed Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/godspeed-brewery/"
+  },
+  {
+    "text": "Goldenfield Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/goldenfield-brewing/"
+  },
+  {
+    "text": "Grand River Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/grand-river-brewery/"
+  },
+  {
+    "text": "Granite Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/granite-brewery/"
+  },
+  {
+    "text": "Great Lakes Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/great-lakes-brewery/"
+  },
+  {
+    "text": "Haliburton Highlands Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/haliburton-highlands-brewery/"
+  },
+  {
+    "text": "Imperial City Brew House",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/imperial-city-brew-house/"
+  },
+  {
+    "text": "Indie Ale House",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/indie-ale-house/"
+  },
+  {
+    "text": "Jobsite Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/jobsite-brewing-co/"
+  },
+  {
+    "text": "Kichesippi Beer Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/kichesippi-beer-co/"
+  },
+  {
+    "text": "Kick and Push Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/kick-and-push-brewing-company/"
+  },
+  {
+    "text": "Lake of Bays Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/lake-of-bays-brewing-co/"
+  },
+  {
+    "text": "Lake Of The Woods Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/lake-of-the-woods-brewing-company/"
+  },
+  {
+    "text": "Left Field Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/left-field-brewery/"
+  },
+  {
+    "text": "Lightcaster Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/lightcaster-brewery/"
+  },
+  {
+    "text": "MacKinnon Brothers Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/mackinnon-brothers-brewing-co/"
+  },
+  {
+    "text": "Maclean’s Ales Inc.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/macleans-ales-inc/"
+  },
+  {
+    "text": "Magnotta Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/magnotta-brewery/"
+  },
+  {
+    "text": "Market Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/market-brewing/"
+  },
+  {
+    "text": "Mascot Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/mascot-brewery/"
+  },
+  {
+    "text": "Matron Fine Beer",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/matron-fine-beer/"
+  },
+  {
+    "text": "Meyers Creek Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/meyers-creek-brewing-company/"
+  },
+  {
+    "text": "Midtown Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/midtown-brewing-co/"
+  },
+  {
+    "text": "Miski Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/miski-brewing/"
+  },
+  {
+    "text": "Muddy York Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/muddy-york-brewing-co/"
+  },
+  {
+    "text": "Muskoka Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/muskoka-brewery/"
+  },
+  {
+    "text": "Natterjack Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/natterjack-brewing-company/"
+  },
+  {
+    "text": "Newark Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/newark-brewing-co/"
+  },
+  {
+    "text": "Niagara Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/niagara-brewing-company/"
+  },
+  {
+    "text": "Niagara College Teaching Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/niagara-college-teaching-brewery/"
+  },
+  {
+    "text": "Niagara Oast House Brewers",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/niagara-oast-house-brewers/"
+  },
+  {
+    "text": "Nickel Brook Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/nickel-brook-brewing-co/"
+  },
+  {
+    "text": "Northern Superior Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/northern-superior-brewing-co/"
+  },
+  {
+    "text": "Old Credit Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/old-credit-brewing-co/"
+  },
+  {
+    "text": "Old Flame Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/1239-2/"
+  },
+  {
+    "text": "Orléans Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/orleans-brewing-co/"
+  },
+  {
+    "text": "Overflow Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/overflow-brewing-co/"
+  },
+  {
+    "text": "Parsons Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/parsons-brewing-company/"
+  },
+  {
+    "text": "Perth Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/perth-brewery/"
+  },
+  {
+    "text": "Prince Eddy’s Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/prince-eddys-brewing-company/"
+  },
+  {
+    "text": "Quayle’s Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/quayles-brewery/"
+  },
+  {
+    "text": "Quetico Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/quetico-brewing-company/"
+  },
+  {
+    "text": "Railway City Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/railway-city-brewing-co/"
+  },
+  {
+    "text": "Ramblin’ Road Brewery Farm",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/ramblin-road-brewery-farm/"
+  },
+  {
+    "text": "Red Barn Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/red-barn-brewing-company/"
+  },
+  {
+    "text": "Refined Fool Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/refined-fool-brewing-co/"
+  },
+  {
+    "text": "Rouge River Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/rouge-river-brewing/"
+  },
+  {
+    "text": "Royal City Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/royal-city-brewing-co/"
+  },
+  {
+    "text": "Sassy Britches Brewing Co Ltd",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/sassy-britches-brewing-co-ltd/"
+  },
+  {
+    "text": "Sawdust City Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/sawdust-city-brewing/"
+  },
+  {
+    "text": "Shawn & Ed Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/shawn-ed-brewing-co/"
+  },
+  {
+    "text": "Silversmith Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/silversmith-brewing-company/"
+  },
+  {
+    "text": "Slake Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/slake-brewing/"
+  },
+  {
+    "text": "Sleeping Giant Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/sleeping-giant-brewing-co/"
+  },
+  {
+    "text": "Something in the Water Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/something-in-the-water-brewing-co/"
+  },
+  {
+    "text": "Sonnen Hill Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/sonnen-hill-brewing/"
+  },
+  {
+    "text": "Sons of Kent Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/sons-of-kent-brewing-company/"
+  },
+  {
+    "text": "Spark Beer",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/spark-beer/"
+  },
+  {
+    "text": "Split Rail Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/split-rail-brewing-company/"
+  },
+  {
+    "text": "Stack Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/stack-brewing/"
+  },
+  {
+    "text": "Steam Whistle Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/steam-whistle-brewing/"
+  },
+  {
+    "text": "Steel Wheel Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/steel-wheel-brewery/"
+  },
+  {
+    "text": "Stonehooker Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/stonehooker-brewing-company/"
+  },
+  {
+    "text": "Stonepicker Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/stonepicker-brewery/"
+  },
+  {
+    "text": "Stray Dog Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/stray-dog-brewing-company/"
+  },
+  {
+    "text": "The Exchange Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/the-exchange-brewery/"
+  },
+  {
+    "text": "The Grove Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/the-grove-brewing-company/"
+  },
+  {
+    "text": "The Second Wedge Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/the-second-wedge-brewing-co/"
+  },
+  {
+    "text": "Thornbury Village Craft Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/thornbury-village-craft-brewery/"
+  },
+  {
+    "text": "Three Sheets Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/three-sheets-brewing/"
+  },
+  {
+    "text": "Tooth and Nail Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/tooth-and-nail-brewing-company/"
+  },
+  {
+    "text": "Torched Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/torched-brewing/"
+  },
+  {
+    "text": "Town Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/town-brewery/"
+  },
+  {
+    "text": "Trestle Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/trestle-brewing-company/"
+  },
+  {
+    "text": "True History Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/true-history-brewing/"
+  },
+  {
+    "text": "Upper Thames Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/upper-thames-brewing-co/"
+  },
+  {
+    "text": "Vimy Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/vimy-brewing-company/"
+  },
+  {
+    "text": "Walkerville Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/walkerville-brewery/"
+  },
+  {
+    "text": "Wave Maker Craft Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/wave-maker-craft-brewery/"
+  },
+  {
+    "text": "Wellington Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/wellington-brewery/"
+  },
+  {
+    "text": "Whiprsnapr Brewing Co.",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/whiprsnapr-brewing-co/"
+  },
+  {
+    "text": "Whiskeyjack Beer Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/whiskeyjack-beer-company/"
+  },
+  {
+    "text": "Whitewater Brewing Company",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/whitewater-brewing-company/"
+  },
+  {
+    "text": "Willibald Farm Distillery & Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/willibald-farm-distillery-brewery/"
+  },
+  {
+    "text": "Windmill Brewery",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/windmill-brewery/"
+  },
+  {
+    "text": "Wishbone Brewing",
+    "href": "https://ontariocraftbrewers.com/brewery-profile/wishbone-brewing/"
+  }
+]

pipeline/.clang-format

@@ -0,0 +1,5 @@
+---
+BasedOnStyle: Google
+ColumnLimit: 80
+IndentWidth: 3
+...

pipeline/.clang-tidy

@@ -0,0 +1,37 @@
+Checks: >
+  -*,
+  bugprone-*,
+  google-*,
+  modernize-*,
+  readability-*,
+  cppcoreguidelines-*,
+  -modernize-use-trailing-return-type,
+  -google-runtime-references
+
+CheckOptions:
+  # Enforce Google Naming Conventions
+  - key: readability-identifier-naming.ClassMemberCase
+    value: snake_case
+  - key: readability-identifier-naming.ClassMemberSuffix
+    value: _
+  - key: readability-identifier-naming.ClassCase
+    value: PascalCase
+  - key: readability-identifier-naming.FunctionCase
+    value: PascalCase
+  - key: readability-identifier-naming.StructCase
+    value: PascalCase
+  - key: readability-identifier-naming.VariableCase
+    value: snake_case
+  - key: readability-identifier-naming.GlobalConstantCase
+    value: kPascalCase
+
+  # Ensure C++20 Modernization
+  - key: modernize-make-unique.MakeSmartPtrFunction
+    value: std::make_unique
+  - key: modernize-make-shared.MakeSmartPtrFunction
+    value: std::make_shared
+  - key: modernize-use-override.IgnoreDestructors
+    value: "false"
+
+# Warnings as Errors to ensure compliance during build
+WarningsAsErrors: "*"

pipeline/.gitignore

@@ -0,0 +1,6 @@
+dist
+build
+data
+models
+*.gguf
+BiergartenPipeline.png

pipeline/CMakeLists.txt

@@ -0,0 +1,150 @@
+cmake_minimum_required(VERSION 3.24)
+project(biergarten-pipeline)
+
+# Boost.DI still declares a very old minimum CMake version, which newer CMake
+# releases reject unless a policy version floor is provided.
+set(CMAKE_POLICY_VERSION_MINIMUM 3.5 CACHE STRING "" FORCE)
+
+# =============================================================================
+# 1. Platform & GPU Detection (Windows explicitly NOT supported)
+# =============================================================================
+if(WIN32)
+    message(FATAL_ERROR "[biergarten] Windows is currently not supported. Please use Linux (Fedora 43) or macOS (M1 Pro).")
+endif()
+
+if(APPLE)
+    if(CMAKE_SYSTEM_PROCESSOR MATCHES "arm64")
+        message(STATUS "[biergarten] Apple Silicon detected — enabling Metal acceleration.")
+        set(GGML_METAL ON CACHE BOOL "Enable Metal for Apple Silicon" FORCE)
+    else()
+        message(STATUS "[biergarten] Intel Mac detected — using CPU / Accelerate framework.")
+        set(GGML_METAL OFF CACHE BOOL "Disable Metal for Intel Macs" FORCE)
+    endif()
+elseif(UNIX AND NOT APPLE)
+    find_package(CUDAToolkit QUIET)
+    find_package(HIP QUIET)
+
+    if(CUDAToolkit_FOUND)
+        message(STATUS "[biergarten] NVIDIA GPU detected — enabling CUDA acceleration.")
+        set(GGML_CUDA ON CACHE BOOL "Enable CUDA for NVIDIA GPUs" FORCE)
+        set(CMAKE_CUDA_ARCHITECTURES native)
+    elseif(HIP_FOUND OR EXISTS "/opt/rocm")
+        message(STATUS "[biergarten] AMD GPU detected — enabling HIP/ROCm acceleration.")
+        set(GGML_HIPBLAS ON CACHE BOOL "Enable HIP for AMD GPUs" FORCE)
+    else()
+        message(STATUS "[biergarten] No NVIDIA or AMD GPU found — falling back to CPU.")
+    endif()
+endif()
+
+# =============================================================================
+# 2. Project-wide Settings (Standard & Optimization)
+# =============================================================================
+
+# Downgrade to C++20 as per Google Style Guide
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+# GCC/Clang specific settings (warnings as errors)
+add_compile_options(-Wall -Wextra -Werror -Wpedantic)
+
+# Release Build Optimization: Aggressive (-O3), Arch-specific, and LTO
+set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -O3 -march=native -flto")
+
+# Debug Build Optimization: Fast and debuggable (-Og)
+set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -Og -g")
+
+# =============================================================================
+# 3. Dependencies
+# =============================================================================
+include(FetchContent)
+
+find_package(CURL QUIET)
+if(NOT CURL_FOUND)
+    message(FATAL_ERROR "[biergarten] libcurl not found. Install it (e.g. 'sudo dnf install libcurl-devel').")
+endif()
+
+# Require system Boost for JSON and Program Options to speed up build times
+find_package(Boost REQUIRED COMPONENTS json program_options)
+
+FetchContent_Declare(
+    llama-cpp
+    GIT_REPOSITORY https://github.com/ggml-org/llama.cpp.git
+    GIT_TAG        b8739
+)
+FetchContent_MakeAvailable(llama-cpp)
+
+FetchContent_Declare(
+    boost-di
+    GIT_REPOSITORY https://github.com/boost-ext/di.git
+    GIT_TAG        v1.3.0
+)
+FetchContent_MakeAvailable(boost-di)
+if(TARGET Boost.DI AND NOT TARGET boost::di)
+    add_library(boost::di ALIAS Boost.DI)
+endif()
+
+FetchContent_Declare(
+    spdlog
+    GIT_REPOSITORY https://github.com/gabime/spdlog.git
+    GIT_TAG        v1.15.3
+)
+FetchContent_MakeAvailable(spdlog)
+
+# =============================================================================
+# 4. Sources
+# =============================================================================
+set(SOURCES
+    src/main.cpp
+    src/biergarten_data_generator/biergarten_data_generator.cpp
+    src/biergarten_data_generator/run.cpp
+    src/biergarten_data_generator/query_cities_with_countries.cpp
+    src/biergarten_data_generator/generate_breweries.cpp
+    src/biergarten_data_generator/log_results.cpp
+    src/services/wikipedia/wikipedia_service.cpp
+    src/services/wikipedia/get_summary.cpp
+    src/services/wikipedia/fetch_extract.cpp
+    src/web_client/curl_global_state.cpp
+    src/web_client/curl_web_client_get.cpp
+    src/web_client/curl_web_client_utils.cpp
+    src/web_client/curl_web_client_url_encode.cpp
+    src/data_generation/llama/llama_generator.cpp
+    src/data_generation/llama/generate_brewery.cpp
+    src/data_generation/llama/generate_user.cpp
+    src/data_generation/llama/helpers.cpp
+    src/data_generation/llama/infer.cpp
+    src/data_generation/llama/load.cpp
+    src/data_generation/llama/load_brewery_prompt.cpp
+    src/data_generation/mock/data.cpp
+    src/data_generation/mock/deterministic_hash.cpp
+    src/data_generation/mock/generate_brewery.cpp
+    src/data_generation/mock/generate_user.cpp
+    src/json_handling/json_loader.cpp
+)
+
+# =============================================================================
+# 5. Target
+# =============================================================================
+add_executable(${PROJECT_NAME} ${SOURCES})
+target_include_directories(${PROJECT_NAME} PRIVATE
+    includes
+    ${llama-cpp_SOURCE_DIR}/include
+    ${llama-cpp_SOURCE_DIR}/common
+)
+target_link_libraries(${PROJECT_NAME} PRIVATE
+    llama
+    boost::di
+    Boost::json
+    Boost::program_options
+    spdlog::spdlog
+    CURL::libcurl
+)
+
+# =============================================================================
+# 6. Runtime Assets
+# =============================================================================
+configure_file(
+    ${CMAKE_SOURCE_DIR}/locations.json
+    ${CMAKE_BINARY_DIR}/locations.json
+    COPYONLY
+)

pipeline/README.md

@@ -0,0 +1,106 @@
+# Biergarten Pipeline
+
+Biergarten Pipeline is a C++20 command-line tool that reads a local city list, resolves contextual enrichment for each sampled city through an injected service, and generates brewery names and descriptions. The current code samples up to four locations per run, then uses either Gemma 4 or the mock generator to produce the output.
+
+## Tested Hardware & OS
+
+### 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**: 32GB
+- **Model**: Gemma 4 E4B: efficient local reasoning; released Apr 2, 2026.
+- **Inference**: llama.cpp with CUDA 12.x support
+
+### ARM MacOS, M1 Pro
+
+- **Host**: MacBook Pro 14" (2021)
+- **CPU**: Apple M1 Pro (8-core)
+- **GPU**: Apple M1 Pro (14-core) [Integrated]
+- **Memory**: 16GB
+- **Model**: Gemma 4 E4B: efficient local reasoning; released Apr 2, 2026.
+- **Inference**: llama.cpp with Metal (MPS) support
+
+## Pipeline
+
+| Stage    | What happens                                                            |
+| -------- | ----------------------------------------------------------------------- |
+| Load     | Reads `locations.json` and picks up to four city/country pairs.         |
+| Enrich   | Calls the injected enrichment service for each sampled city.            |
+| Generate | Passes the city, country, and gathered context to the active generator. |
+| Log      | Writes the generated breweries and any warnings through `spdlog`.       |
+
+If an enrichment lookup throws, the pipeline skips that city and keeps going. If the lookup returns an empty string, the city stays in the pipeline and is still passed to the generator.
+
+## Core Components
+
+| Component               | Role                                                                   |
+| ----------------------- | ---------------------------------------------------------------------- |
+| BiergartenDataGenerator | Orchestrates loading, enrichment lookup, generation, and logging.      |
+| IEnrichmentService      | Abstraction for location-context providers.                            |
+| WikipediaService        | Default enrichment provider backed by Wikipedia and in-memory caching. |
+| LlamaGenerator          | Runs local GGUF inference and validates output.                        |
+| MockGenerator           | Produces deterministic fallback data without a model.                  |
+| JsonLoader              | Parses the local `locations.json` file.                                |
+| CURLWebClient           | Handles HTTP requests to Wikipedia.                                    |
+
+## Build
+
+| Requirement          | Notes                                                                      |
+| -------------------- | -------------------------------------------------------------------------- |
+| C++23 compiler       | GCC 13+ or Clang 16+ are good starting points.                             |
+| CMake                | Version 3.24 or newer.                                                     |
+| libcurl              | Required for Wikipedia requests.                                           |
+| Optional GPU tooling | CUDA on NVIDIA, HIP/ROCm on supported AMD systems, Metal on Apple Silicon. |
+
+Boost, Boost.DI, spdlog, and llama.cpp are fetched by CMake. On Apple Silicon, Metal is enabled automatically. On Linux, the build looks for CUDA or HIP/ROCm when the matching toolkit is present. There are no plans to support Windows.
+
+```bash
+cmake -S . -B build
+cmake --build build
+```
+
+If the dependency build fails on macOS, check the repo build notes.
+
+## Model
+
+Create a `models/` directory and download the GGUF file there before running the app.
+
+```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 the executable from the build directory so the copied `locations.json` is available.
+
+```bash
+./biergarten-pipeline --mocked
+./biergarten-pipeline --model models/google_gemma-4-E4B-it-Q6_K.gguf --temperature 1.0 --top-p 0.95 --top-k 64 --n-ctx 8192 --seed -1
+```
+
+| Flag            | Purpose                                                                      |
+| --------------- | ---------------------------------------------------------------------------- |
+| `--mocked`      | Uses the mock generator instead of a model.                                  |
+| `--model, -m`   | Path to a GGUF model file, such as `models/google_gemma-4-E4B-it-Q6_K.gguf`. |
+| `--temperature` | Sampling temperature. Default: `1.0`.                                        |
+| `--top-p`       | Nucleus sampling parameter. Default: `0.95`.                                 |
+| `--top-k`       | Top-k sampling parameter. Default: `64`.                                     |
+| `--n-ctx`       | Context window size. Default: `8192`.                                        |
+| `--seed`        | Random seed. Default: `-1`.                                                  |
+| `--help, -h`    | Prints usage.                                                                |
+
+`--mocked` and `--model` are mutually exclusive. If neither is set, the program exits with an error. The sampling flags only matter when a model is loaded. The enrichment step is sequential now, and empty context is allowed.
+
+## Layout
+
+| Path             | Use                                         |
+| ---------------- | ------------------------------------------- |
+| `includes/`      | Public headers.                             |
+| `src/`           | Implementation files.                       |
+| `locations.json` | Input city list copied into the build tree. |
+| `prompts/`       | Prompt text used by the model path.         |

pipeline/beer-styles.json

@@ -0,0 +1,902 @@
+[
+  {
+    "name": "Gose",
+    "description": "A historic warm-fermented beer originating from Goslar, Germany. It is brewed with at least 50% malted wheat and characterized by the addition of coriander and salt, resulting in a crisp, sour, salty, and herbal flavor profile.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Gose",
+    "min_abv": 4.2,
+    "max_abv": 4.8,
+    "min_ibu": 5,
+    "max_ibu": 15
+  },
+  {
+    "name": "Rauchbier",
+    "description": "A traditional German style originating in Bamberg, Franconia. The malt is dried over an open beechwood fire, imparting a distinctive, intense smoky flavor that balances with a rich, malty lager base.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Smoked_beer",
+    "min_abv": 4.8,
+    "max_abv": 6.0,
+    "min_ibu": 20,
+    "max_ibu": 30
+  },
+  {
+    "name": "Lambic",
+    "description": "A uniquely Belgian beer originating in the Senne river valley near Brussels. Instead of carefully cultivated brewer's yeast, it is fermented spontaneously by wild yeasts and bacteria native to the region, creating a dry, cidery, and profoundly sour profile.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Lambic",
+    "min_abv": 5.0,
+    "max_abv": 6.5,
+    "min_ibu": 0,
+    "max_ibu": 10
+  },
+  {
+    "name": "Sahti",
+    "description": "An ancient Finnish farmhouse ale brewed with a variety of grains (often including rye) and filtered through juniper twigs instead of relying heavily on hops for bittering. It is historically fermented with baker's yeast, yielding strong banana and clove esters.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Sahti",
+    "min_abv": 7.0,
+    "max_abv": 8.5,
+    "min_ibu": 0,
+    "max_ibu": 15
+  },
+  {
+    "name": "Kvass",
+    "description": "A traditional Slavic and Baltic fermented beverage commonly made from rye bread. It is typically extremely low in alcohol and features a sweet, bready, slightly tart flavor, often flavored with fruits or herbs like mint.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Kvass",
+    "min_abv": 0.5,
+    "max_abv": 2.0,
+    "min_ibu": 0,
+    "max_ibu": 5
+  },
+  {
+    "name": "Berliner Weisse",
+    "description": "A cloudy, sour, white beer originating in Berlin. Fermented with a mixture of yeast and lactic acid bacteria, it is sharply tart and highly carbonated. Historically, it is often served with a dash of raspberry or woodruff syrup to cut the acidity.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Berliner_Weisse",
+    "min_abv": 2.8,
+    "max_abv": 3.8,
+    "min_ibu": 3,
+    "max_ibu": 8
+  },
+  {
+    "name": "Eisbock",
+    "description": "A specialty German beer created by partially freezing a doppelbock and removing the water ice. This freeze-distillation process concentrates the flavor, malt richness, and alcohol content, creating a heavy, syrupy, and warming brew.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Bock#Eisbock",
+    "min_abv": 9.0,
+    "max_abv": 14.0,
+    "min_ibu": 25,
+    "max_ibu": 35
+  },
+  {
+    "name": "Altbier",
+    "description": "A German style originating in Düsseldorf that straddles the line between ale and lager. It is top-fermented at moderate temperatures but then cold-conditioned (lagered), resulting in a clean, crisp beer with a firm, balanced maltiness and notable hop bitterness.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Altbier",
+    "min_abv": 4.3,
+    "max_abv": 5.5,
+    "min_ibu": 25,
+    "max_ibu": 50
+  },
+  {
+    "name": "Kölsch",
+    "description": "A light, brilliantly clear, top-fermented beer strictly associated with Cologne, Germany. Like Altbier, it is warm-fermented and cold-conditioned, yielding a delicate, soft, and slightly fruity pale beer with a dry, crisp finish.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/K%C3%B6lsch_(beer)",
+    "min_abv": 4.4,
+    "max_abv": 5.2,
+    "min_ibu": 20,
+    "max_ibu": 30
+  },
+  {
+    "name": "Oud Bruin",
+    "description": "A Flanders Brown Ale characterized by a long aging process—often up to a year—in stainless steel rather than oak. It undergoes a secondary fermentation with lactic acid bacteria, resulting in a dark, malty, dark-fruit-forward profile with a mild to moderate sourness.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Oud_bruin",
+    "min_abv": 4.0,
+    "max_abv": 8.0,
+    "min_ibu": 20,
+    "max_ibu": 25
+  },
+  {
+    "name": "Saison",
+    "description": "A pale ale originally brewed in the Wallonia region of Belgium for farm workers during the harvest season. Highly carbonated, fruity, spicy, and often dry, it frequently employs distinctive yeast strains and sometimes wild bacteria or spices.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Saison",
+    "min_abv": 5.0,
+    "max_abv": 7.0,
+    "min_ibu": 20,
+    "max_ibu": 35
+  },
+  {
+    "name": "Roggenbier",
+    "description": "A historical German beer brewed with up to 50% rye malt. It shares the yeast strains used in Bavarian Hefeweizen, offering banana and clove notes, but the rye provides a distinctly earthy, spicy character and a dense, viscous mouthfeel.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Roggenbier",
+    "min_abv": 4.5,
+    "max_abv": 6.0,
+    "min_ibu": 10,
+    "max_ibu": 20
+  },
+  {
+    "name": "Schwarzbier",
+    "description": "Germany's 'black beer' is a dark lager that balances roasted malt flavors with moderate hop bitterness. Unlike a stout or porter, it uses debittered roasted malts to achieve a very smooth, clean, and crisp dark beer without heavy astringency.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Schwarzbier",
+    "min_abv": 4.4,
+    "max_abv": 5.4,
+    "min_ibu": 20,
+    "max_ibu": 30
+  },
+  {
+    "name": "Mild Ale",
+    "description": "A historic British style originally meaning young or unaged beer, it evolved into a low-gravity, malt-focused session ale. Usually dark brown, it features notes of caramel, chocolate, and mild roast, with very low hop presence.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Mild_ale",
+    "min_abv": 3.0,
+    "max_abv": 3.8,
+    "min_ibu": 10,
+    "max_ibu": 25
+  },
+  {
+    "name": "Baltic Porter",
+    "description": "Originating in countries bordering the Baltic Sea, this style adapted the strong, sweet British export porters to local ingredients and cold bottom-fermenting lager yeasts. It is dark, robust, and complex with rich dark fruit and molasses notes.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Porter_(beer)#Baltic_porter",
+    "min_abv": 6.5,
+    "max_abv": 9.5,
+    "min_ibu": 20,
+    "max_ibu": 40
+  },
+  {
+    "name": "California Common",
+    "description": "Also known as Steam Beer, this uniquely American style was born out of necessity during the Gold Rush. It is brewed with a special strain of lager yeast that ferments optimally at warmer, ale-like temperatures, resulting in a rustic, woody, and minty flavor profile.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Steam_beer",
+    "min_abv": 4.5,
+    "max_abv": 5.5,
+    "min_ibu": 30,
+    "max_ibu": 45
+  },
+  {
+    "name": "Kellerbier",
+    "description": "An unfiltered, unpasteurized German lager that is traditionally served directly from the lagering vessel ('Keller' means cellar). Because it retains its yeast, it is cloudy, naturally carbonated, and features a soft, bready, and highly aromatic profile.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Kellerbier",
+    "min_abv": 4.7,
+    "max_abv": 5.4,
+    "min_ibu": 20,
+    "max_ibu": 40
+  },
+  {
+    "name": "Faro",
+    "description": "A traditional, low-alcohol sweet beer from Belgium made by blending lambic with a much lighter, freshly brewed beer (or water) and adding brown sugar or candi sugar. The sugar provides sweetness to balance the lambic's tartness.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Faro_(beer)",
+    "min_abv": 4.0,
+    "max_abv": 5.5,
+    "min_ibu": 0,
+    "max_ibu": 10
+  },
+  {
+    "name": "Grodziskie",
+    "description": "A highly carbonated, low-alcohol Polish beer nicknamed 'Polish Champagne.' It is brewed entirely from oak-smoked wheat malt, resulting in a pale, effervescent, brilliantly clear beer that combines crisp wheat tartness with a distinct smoky aroma.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Grodziskie",
+    "min_abv": 2.5,
+    "max_abv": 3.3,
+    "min_ibu": 20,
+    "max_ibu": 35
+  },
+  {
+    "name": "Lichtenhainer",
+    "description": "A nearly extinct historical German style originating from Thuringia. It is a lightly sour, smoked wheat beer. Think of it as a cross between a Berliner Weisse and a Rauchbier—refreshingly tart with a gentle wood-smoke character.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Smoked_beer",
+    "min_abv": 3.5,
+    "max_abv": 4.7,
+    "min_ibu": 5,
+    "max_ibu": 12
+  },
+  {
+    "name": "Irish Dry Stout",
+    "description": "A very dark, roasty, bitter, creamy ale that gained global fame through breweries in Dublin. It relies heavily on roasted barley for its espresso-like bite and bone-dry finish, often served via a nitrogen draught system for a dense, pillowy head.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Stout#Dry_stout",
+    "min_abv": 4.0,
+    "max_abv": 5.0,
+    "min_ibu": 30,
+    "max_ibu": 45
+  },
+  {
+    "name": "English Barleywine",
+    "description": "A showcase of malty richness and complex, intense flavors. This strong ale boasts a deep caramel to dark amber color with massive notes of dark fruit, toffee, and molasses, meant to be sipped and often aged for years like wine.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Barley_wine",
+    "min_abv": 8.0,
+    "max_abv": 12.0,
+    "min_ibu": 35,
+    "max_ibu": 70
+  },
+  {
+    "name": "Belgian Tripel",
+    "description": "A remarkably pale, strong, and highly carbonated Belgian ale forged by Trappist monks. Despite its high alcohol content, it hides its strength well behind a complex profile of spicy yeast phenols, fruity esters, and a surprisingly dry finish.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Tripel",
+    "min_abv": 7.5,
+    "max_abv": 9.5,
+    "min_ibu": 20,
+    "max_ibu": 40
+  },
+  {
+    "name": "Doppelbock",
+    "description": "A stronger and maltier version of a traditional German bock, originally brewed by monks in Munich as 'liquid bread' for sustenance during fasting. It is exceptionally rich, dark, and heavy with flavors of toasted bread and dark fruit.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Bock#Doppelbock",
+    "min_abv": 7.0,
+    "max_abv": 10.0,
+    "min_ibu": 16,
+    "max_ibu": 26
+  },
+  {
+    "name": "Wee Heavy",
+    "description": "Also known as Strong Scotch Ale, this malty, copper-to-brown beer undergoes a long boil that caramelizes the wort, producing deep, sweet flavors of plum, toffee, and roasted nuts, historically fermented at cooler temperatures for a clean profile.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Scotch_ale",
+    "min_abv": 6.5,
+    "max_abv": 10.0,
+    "min_ibu": 17,
+    "max_ibu": 35
+  },
+  {
+    "name": "New England IPA",
+    "description": "An American IPA featuring intense, tropical fruit-centric hop aroma and flavor with heavily reduced bitterness. It is deliberately hazy or opaque—often resembling fruit juice—and has a soft, pillowy mouthfeel achieved through oats and wheat.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/New_England_IPA",
+    "min_abv": 6.0,
+    "max_abv": 9.0,
+    "min_ibu": 25,
+    "max_ibu": 60
+  },
+  {
+    "name": "Flanders Red Ale",
+    "description": "Often referred to as the 'Burgundy of Belgium,' this complex sour ale is aged for up to two years in massive oak vats. The result is an intensely fruity, wine-like beer with sharp acetic sourness balanced by notes of black cherry, plum, and red currant.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Flanders_red_ale",
+    "min_abv": 4.6,
+    "max_abv": 6.5,
+    "min_ibu": 10,
+    "max_ibu": 25
+  },
+  {
+    "name": "Witbier",
+    "description": "A 400-year-old Belgian beer style that was revived from near extinction. It is a pale, hazy, unfiltered wheat beer spiced gracefully with crushed coriander seed and bitter orange peel, resulting in a lively, zesty, and highly refreshing profile.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Witbier",
+    "min_abv": 4.5,
+    "max_abv": 5.5,
+    "min_ibu": 10,
+    "max_ibu": 20
+  },
+  {
+    "name": "Imperial Stout",
+    "description": "An intensely-flavored, big, dark ale with a wide range of flavor balances and regional interpretations. Originally brewed in England for export to the Russian imperial court, it features massive roasted malt character, dark fruit notes, and a warming alcohol presence.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Stout#Imperial_stout",
+    "min_abv": 8.0,
+    "max_abv": 12.0,
+    "min_ibu": 50,
+    "max_ibu": 90
+  },
+  {
+    "name": "Hefeweizen",
+    "description": "A traditional, unfiltered Bavarian wheat beer featuring a uniquely expressive yeast strain. The yeast provides its signature flavors of clove and banana, while the high wheat content creates a fluffy, long-lasting head and a bready, refreshing body.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Wheat_beer#Hefeweizen",
+    "min_abv": 4.3,
+    "max_abv": 5.6,
+    "min_ibu": 8,
+    "max_ibu": 15
+  },
+  {
+    "name": "American Pale Ale",
+    "description": "An American adaptation of the English pale ale, revolutionized by the use of indigenous ingredients. It is defined by the bold, piney, and citrus-forward aromas of American hops (like Cascade) riding on a clean, supportive malt backbone.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/American_pale_ale",
+    "min_abv": 4.5,
+    "max_abv": 6.2,
+    "min_ibu": 30,
+    "max_ibu": 50
+  },
+  {
+    "name": "Bière de Garde",
+    "description": "A sturdy artisanal farmhouse ale from Northern France traditionally brewed in early spring and kept in cold cellars for consumption in warmer months. It is characterized by a toasted malt sweetness, earthy yeast character, and a dry finish.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Bi%C3%A8re_de_Garde",
+    "min_abv": 6.0,
+    "max_abv": 8.5,
+    "min_ibu": 18,
+    "max_ibu": 28
+  },
+  {
+    "name": "Vienna Lager",
+    "description": "Developed in 1841 in Austria, this elegant amber lager relies on Vienna malt to provide a soft, complex, and lightly toasted malt profile. It maintains a crisp, clean lager finish with just enough noble hop bitterness to balance the malt sweetness.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Vienna_lager",
+    "min_abv": 4.7,
+    "max_abv": 5.5,
+    "min_ibu": 18,
+    "max_ibu": 30
+  },
+  {
+    "name": "Gueuze",
+    "description": "A complex, tart Belgian beer created by blending one-, two-, and three-year-old lambics. The young lambic provides fermentable sugars for secondary bottle fermentation, creating a highly carbonated, bone-dry, deeply sour beer with a distinct 'barnyard' funk.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Gueuze",
+    "min_abv": 5.0,
+    "max_abv": 8.0,
+    "min_ibu": 0,
+    "max_ibu": 10
+  },
+  {
+    "name": "Dunkelweizen",
+    "description": "A dark, Bavarian wheat beer that marries the spicy, fruity yeast character of a Hefeweizen with the rich, bready, and caramel-driven malt profile of a Munich Dunkel. The result is a highly aromatic, dark but refreshing ale.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Wheat_beer#Dark_wheat_beer",
+    "min_abv": 4.3,
+    "max_abv": 5.6,
+    "min_ibu": 10,
+    "max_ibu": 18
+  },
+  {
+    "name": "Maibock",
+    "description": "Also known as a Helles Bock, this strong, pale Bavarian lager is traditionally brewed for spring festivals. It is paler and more hop-forward than a traditional bock, delivering a warming alcoholic strength wrapped in a crisp, bready malt body.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Bock#Maibock",
+    "min_abv": 6.3,
+    "max_abv": 7.4,
+    "min_ibu": 23,
+    "max_ibu": 35
+  },
+  {
+    "name": "Extra Special Bitter",
+    "description": "The strongest and maltiest of the traditional English Bitter family. An ESB features an aggressive balance of earthy, floral English hops and a rich, biscuit-like malt backbone, traditionally served via cask conditioning at cellar temperatures.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Bitter_(beer)#Extra_Special_Bitter",
+    "min_abv": 4.6,
+    "max_abv": 6.2,
+    "min_ibu": 30,
+    "max_ibu": 50
+  },
+  {
+    "name": "Cream Ale",
+    "description": "A clean, well-attenuated, and highly carbonated American 'lawnmower' beer. It is brewed with ale yeast but sometimes cold-conditioned or blended with lager, using corn adjuncts to lighten the body and create an incredibly crisp, refreshing finish.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Cream_ale",
+    "min_abv": 4.2,
+    "max_abv": 5.6,
+    "min_ibu": 15,
+    "max_ibu": 20
+  },
+  {
+    "name": "Irish Red Ale",
+    "description": "An approachable, malt-focused Irish ale characterized by an amber-to-red color. It features mild caramel sweetness, very low hop bitterness, and a signature dry, slightly roasted finish courtesy of a small addition of roasted barley.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Irish_red_ale",
+    "min_abv": 4.0,
+    "max_abv": 6.0,
+    "min_ibu": 15,
+    "max_ibu": 30
+  },
+  {
+    "name": "Munich Helles",
+    "description": "Created in Munich in 1894 to compete with the rising popularity of Czech Pilsners. It is a clean, malty, gold-colored lager that showcases a soft, bready malt sweetness with just enough spicy German hops to provide a balanced finish.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Helles",
+    "min_abv": 4.7,
+    "max_abv": 5.4,
+    "min_ibu": 16,
+    "max_ibu": 22
+  },
+  {
+    "name": "American IPA",
+    "description": "A decidedly hoppy and bitter, moderately strong American pale ale. It showcases modern American or New World hop varieties with intense fruit, citrus, pine, or floral aromatics.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/India_pale_ale#American_IPA",
+    "min_abv": 5.5,
+    "max_abv": 7.5,
+    "min_ibu": 40,
+    "max_ibu": 70
+  },
+  {
+    "name": "English IPA",
+    "description": "A hoppy, moderately strong English pale ale that features the earthy, floral, and spicy characteristics of traditional English hops, supported by a solid biscuit or caramel malt backbone.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/India_pale_ale#England",
+    "min_abv": 5.0,
+    "max_abv": 7.5,
+    "min_ibu": 40,
+    "max_ibu": 60
+  },
+  {
+    "name": "Double IPA",
+    "description": "An intensely hoppy, fairly strong pale ale designed to showcase hop character without being overly harsh. It features a massive hop profile supported by a clean alcohol warmth and enough malt to prevent it from feeling thin.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Double_India_Pale_Ale",
+    "min_abv": 7.5,
+    "max_abv": 10.0,
+    "min_ibu": 60,
+    "max_ibu": 120
+  },
+  {
+    "name": "Session IPA",
+    "description": "A highly hop-forward ale that delivers the aroma and flavor intensity of an IPA but with a much lower alcohol content, making it highly drinkable over an extended session.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/India_pale_ale#Session_IPA",
+    "min_abv": 3.7,
+    "max_abv": 5.0,
+    "min_ibu": 40,
+    "max_ibu": 55
+  },
+  {
+    "name": "Black IPA",
+    "description": "A beer with the dryness, hop-forward balance, and flavor characteristics of an American IPA, but with a dark color and a restrained roasted malt character that doesn't clash with the hops.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Black_IPA",
+    "min_abv": 5.5,
+    "max_abv": 9.0,
+    "min_ibu": 50,
+    "max_ibu": 90
+  },
+  {
+    "name": "Belgian IPA",
+    "description": "An IPA that marries the fruity, spicy yeast character of a Belgian ale with the assertive hop profile of an American IPA. It is typically lighter in body and highly carbonated.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/India_pale_ale#Belgian_IPA",
+    "min_abv": 6.2,
+    "max_abv": 9.5,
+    "min_ibu": 50,
+    "max_ibu": 100
+  },
+  {
+    "name": "White IPA",
+    "description": "A fruity, spicy, and refreshing hybrid style that combines the crisp, wheat-based body and spice additions of a Belgian Witbier with the pronounced hop aroma and bitterness of an American IPA.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/India_pale_ale#White_IPA",
+    "min_abv": 5.5,
+    "max_abv": 7.0,
+    "min_ibu": 40,
+    "max_ibu": 70
+  },
+  {
+    "name": "American Stout",
+    "description": "A hoppy, bitter, strongly roasted dark ale. It features the bold, aggressive flavor of American hops alongside intense roasted malt, coffee, and dark chocolate notes.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Stout#American_stout",
+    "min_abv": 5.0,
+    "max_abv": 7.0,
+    "min_ibu": 35,
+    "max_ibu": 60
+  },
+  {
+    "name": "Oatmeal Stout",
+    "description": "A very dark, full-bodied, roasty, malty ale featuring a complementary oatmeal addition. The oats provide a smooth, rich, and slightly oily texture that balances the roasted grain astringency.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Stout#Oatmeal_stout",
+    "min_abv": 4.2,
+    "max_abv": 5.9,
+    "min_ibu": 25,
+    "max_ibu": 40
+  },
+  {
+    "name": "Sweet Stout",
+    "description": "Also known as Milk Stout. A very dark, sweet, full-bodied, slightly roasty ale. Historically sweetened with lactose, an unfermentable milk sugar, it has a creamy texture and espresso-and-cream-like flavor.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Stout#Milk_stout",
+    "min_abv": 4.0,
+    "max_abv": 6.0,
+    "min_ibu": 15,
+    "max_ibu": 40
+  },
+  {
+    "name": "Foreign Extra Stout",
+    "description": "A darker and sweeter stout originally brewed for export to tropical markets. It is moderately strong and features pronounced roasted grain, chocolate, and dark fruit flavors.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Stout#Foreign_Extra_Stout",
+    "min_abv": 6.3,
+    "max_abv": 8.0,
+    "min_ibu": 50,
+    "max_ibu": 70
+  },
+  {
+    "name": "English Porter",
+    "description": "A moderate-strength brown beer with a restrained roasty character and bitterness. It features a complex malt profile with notes of chocolate, caramel, and nuts, without the burnt flavors of a stout.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Porter_(beer)",
+    "min_abv": 4.0,
+    "max_abv": 5.4,
+    "min_ibu": 18,
+    "max_ibu": 35
+  },
+  {
+    "name": "American Porter",
+    "description": "A substantial, malty dark beer with a complex and flavorful dark malt character. Compared to English Porter, it is generally stronger, more aggressively hopped, and features more roasted barley character.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Porter_(beer)#American_porter",
+    "min_abv": 4.8,
+    "max_abv": 6.5,
+    "min_ibu": 25,
+    "max_ibu": 50
+  },
+  {
+    "name": "Robust Porter",
+    "description": "A stronger, more bitter, and more roasted version of a porter. It bridges the gap between brown porter and stout, offering intense cocoa and dark caramel notes with a sharp roasted finish.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Porter_(beer)",
+    "min_abv": 5.1,
+    "max_abv": 6.6,
+    "min_ibu": 25,
+    "max_ibu": 50
+  },
+  {
+    "name": "American Brown Ale",
+    "description": "A malty but hoppy beer with prominent chocolate and caramel flavors. The hop character is noticeably American, providing a citrusy or piney contrast to the rich malt backbone.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Brown_ale#American_Brown_Ale",
+    "min_abv": 4.3,
+    "max_abv": 6.2,
+    "min_ibu": 20,
+    "max_ibu": 40
+  },
+  {
+    "name": "English Brown Ale",
+    "description": "A malty, brown caramel-centric British ale without the roasted flavors of a porter. It is known for its nutty, toffee, and light chocolate notes, paired with a subtle, earthy hop presence.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Brown_ale",
+    "min_abv": 4.2,
+    "max_abv": 5.4,
+    "min_ibu": 20,
+    "max_ibu": 30
+  },
+  {
+    "name": "Belgian Dubbel",
+    "description": "A deep reddish-copper, moderately strong, malty, complex Trappist ale. It features rich, malty flavors, dark fruit esters like plum and raisin, and mild phenolic spiciness from the Belgian yeast.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Dubbel",
+    "min_abv": 6.0,
+    "max_abv": 7.6,
+    "min_ibu": 15,
+    "max_ibu": 25
+  },
+  {
+    "name": "Belgian Quadrupel",
+    "description": "A massively strong, dark, rich, and complex Belgian ale. It pushes the boundaries of the Dubbel style, offering intense dark fruit, caramel, and peppery yeast spice with a smooth, warming alcohol finish.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Quadrupel",
+    "min_abv": 9.0,
+    "max_abv": 14.0,
+    "min_ibu": 20,
+    "max_ibu": 35
+  },
+  {
+    "name": "Belgian Blonde Ale",
+    "description": "A moderate-strength golden ale with a subtle fruity-spicy Belgian yeast complexity, slightly sweet malty flavor, and a dry finish. It is highly approachable and brilliantly clear.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Blonde_ale#Belgian_blonde_ale",
+    "min_abv": 6.0,
+    "max_abv": 7.5,
+    "min_ibu": 15,
+    "max_ibu": 30
+  },
+  {
+    "name": "Belgian Pale Ale",
+    "description": "A moderately malty, somewhat fruity, easy-drinking, copper-colored Belgian ale. It is less aggressive in yeast character than other Belgian styles, focusing on a balanced, biscuity malt and earthy hop profile.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Pale_ale#Belgian_pale_ale",
+    "min_abv": 4.8,
+    "max_abv": 5.5,
+    "min_ibu": 20,
+    "max_ibu": 30
+  },
+  {
+    "name": "Belgian Strong Golden Ale",
+    "description": "A pale, complex, effervescent, strong Belgian-style ale. It is highly attenuated and features fruity and hoppy notes in preference to phenolics, often with a surprisingly light body for its strength.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Strong_ale#Belgian_strong_ale",
+    "min_abv": 7.5,
+    "max_abv": 10.5,
+    "min_ibu": 22,
+    "max_ibu": 35
+  },
+  {
+    "name": "Belgian Strong Dark Ale",
+    "description": "A dark, complex, very strong Belgian ale with a delicious blend of malt richness, dark fruit flavors, and spicy elements. It is deep, warming, and often beautifully conditioned.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Strong_ale#Belgian_strong_ale",
+    "min_abv": 8.0,
+    "max_abv": 11.0,
+    "min_ibu": 20,
+    "max_ibu": 35
+  },
+  {
+    "name": "Trappist Single",
+    "description": "A pale, bitter, highly attenuated and well-carbonated Trappist ale. Historically brewed for the monks' daily consumption (patersbier), it is dry, refreshing, and features prominent fruity and spicy yeast character.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Trappist_beer",
+    "min_abv": 4.8,
+    "max_abv": 6.0,
+    "min_ibu": 25,
+    "max_ibu": 45
+  },
+  {
+    "name": "Grisette",
+    "description": "A low-alcohol, light-bodied, and refreshing farmhouse ale historically brewed for miners in the Hainaut province of Belgium. It is similar to a Saison but typically lower in gravity and lacking strong tartness.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Grisette_(beer)",
+    "min_abv": 3.5,
+    "max_abv": 5.0,
+    "min_ibu": 15,
+    "max_ibu": 30
+  },
+  {
+    "name": "Weizenbock",
+    "description": "A strong, malty, fruity, wheat-based ale combining the best flavors of a dunkelweizen and the rich strength and dark fruit of a bock. It is robust, bready, and highly aromatic.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Bock#Weizenbock",
+    "min_abv": 6.5,
+    "max_abv": 9.0,
+    "min_ibu": 15,
+    "max_ibu": 30
+  },
+  {
+    "name": "Kristalweizen",
+    "description": "A filtered version of the traditional Bavarian Hefeweizen. By removing the yeast, the beer becomes brilliantly clear, offering a sharper, cleaner interpretation of the classic banana and clove flavors.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Wheat_beer#Kristalweizen",
+    "min_abv": 4.3,
+    "max_abv": 5.6,
+    "min_ibu": 8,
+    "max_ibu": 15
+  },
+  {
+    "name": "Wheatwine",
+    "description": "A richly textured, high-alcohol ale made with a significant portion of wheat malt. It features a soft, bready maltiness with complex caramel and fruity notes, aging beautifully much like a barleywine.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Barley_wine#Wheatwine",
+    "min_abv": 8.5,
+    "max_abv": 12.2,
+    "min_ibu": 45,
+    "max_ibu": 85
+  },
+  {
+    "name": "American Wheat Beer",
+    "description": "A pale, refreshing American ale brewed with a large proportion of wheat. Unlike German versions, it uses a clean-fermenting yeast, allowing the bready wheat malt and bright American hops to shine without clove or banana notes.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Wheat_beer#American_wheat_beer",
+    "min_abv": 4.0,
+    "max_abv": 5.5,
+    "min_ibu": 15,
+    "max_ibu": 30
+  },
+  {
+    "name": "Traditional Bock",
+    "description": "A dark, strong, malty German lager. It is rich and complex, boasting robust flavors of toasted bread, caramel, and dark fruit, with very little hop bitterness and a smooth, clean lager finish.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Bock",
+    "min_abv": 6.3,
+    "max_abv": 7.2,
+    "min_ibu": 20,
+    "max_ibu": 27
+  },
+  {
+    "name": "Munich Dunkel",
+    "description": "A classic brown Bavarian lager that celebrates the rich, complex flavors of Munich malt. It features deep, bready, and toast-like caramel qualities without any harsh or burnt roasted malt flavors.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Dunkel",
+    "min_abv": 4.5,
+    "max_abv": 5.6,
+    "min_ibu": 18,
+    "max_ibu": 28
+  },
+  {
+    "name": "Festbier",
+    "description": "A smooth, clean, pale German lager with a moderately strong malty flavor and a light hop character. This is the modern beer served at the Munich Oktoberfest, lighter in color and body than a traditional Märzen.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Oktoberfestbier",
+    "min_abv": 5.8,
+    "max_abv": 6.3,
+    "min_ibu": 18,
+    "max_ibu": 25
+  },
+  {
+    "name": "Märzen",
+    "description": "An elegant, malty German amber lager with a clean, rich, toasty and bready malt flavor, restrained bitterness, and a dry finish. Historically brewed in March and lagered in cold caves over the summer.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/M%C3%A4rzen",
+    "min_abv": 5.8,
+    "max_abv": 6.3,
+    "min_ibu": 18,
+    "max_ibu": 24
+  },
+  {
+    "name": "Czech Pale Lager",
+    "description": "A lighter, sessionable version of the famous Czech premium lagers. It features a prominent but soft Saaz hop spiciness balanced by a bready, slightly sweet malt backbone.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Beer_in_the_Czech_Republic",
+    "min_abv": 3.0,
+    "max_abv": 4.1,
+    "min_ibu": 20,
+    "max_ibu": 35
+  },
+  {
+    "name": "Czech Premium Pale Lager",
+    "description": "The original Pilsner style. It is a crisp, complex, and well-rounded pale lager featuring a rich, bready maltiness perfectly balanced by the pronounced, spicy bitterness of Saaz hops.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Pilsner",
+    "min_abv": 4.2,
+    "max_abv": 5.8,
+    "min_ibu": 30,
+    "max_ibu": 45
+  },
+  {
+    "name": "Czech Amber Lager",
+    "description": "A malt-driven amber lager with a balanced hop bitterness. It combines the rich, caramel and toasted malt flavors of a Vienna lager with the characteristic spicy hop profile of Czech brewing.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Beer_in_the_Czech_Republic",
+    "min_abv": 4.4,
+    "max_abv": 5.8,
+    "min_ibu": 20,
+    "max_ibu": 35
+  },
+  {
+    "name": "Czech Dark Lager",
+    "description": "A rich, dark, and highly drinkable Czech lager. It balances a roasted, chocolatey, and caramel malt sweetness with a gentle but noticeable hop bitterness, maintaining a smooth lager finish.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Beer_in_the_Czech_Republic",
+    "min_abv": 4.4,
+    "max_abv": 5.8,
+    "min_ibu": 18,
+    "max_ibu": 34
+  },
+  {
+    "name": "International Pale Lager",
+    "description": "A highly attenuated pale lager without strong flavors, typically well-balanced and highly carbonated. It serves as a thirst-quenching, mass-market style with a very clean, neutral profile.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Pale_lager",
+    "min_abv": 4.6,
+    "max_abv": 6.0,
+    "min_ibu": 18,
+    "max_ibu": 25
+  },
+  {
+    "name": "International Dark Lager",
+    "description": "A darker, somewhat sweeter version of an international pale lager. It features mild caramel or roasted malt notes, low hop bitterness, and a crisp, clean lager finish.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Dark_beer",
+    "min_abv": 4.2,
+    "max_abv": 6.0,
+    "min_ibu": 8,
+    "max_ibu": 20
+  },
+  {
+    "name": "American Lager",
+    "description": "A very pale, highly carbonated, light-bodied, well-attenuated lager. It is brewed with up to 40% corn or rice adjuncts to lighten the body and flavor, creating an extremely crisp and refreshing thirst-quencher.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Beer_in_the_United_States#American_Lager",
+    "min_abv": 4.2,
+    "max_abv": 5.3,
+    "min_ibu": 8,
+    "max_ibu": 18
+  },
+  {
+    "name": "American Light Lager",
+    "description": "A lighter, lower-calorie version of an American lager. It is highly attenuated and very neutral in flavor, designed for extreme drinkability without bitterness or heavy malt character.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Light_beer",
+    "min_abv": 2.8,
+    "max_abv": 4.2,
+    "min_ibu": 8,
+    "max_ibu": 12
+  },
+  {
+    "name": "American Amber Ale",
+    "description": "A hoppy, moderately strong American ale featuring a caramel malt backbone. It strikes a balance between the citrusy, piney notes of American hops and a rich, toasted malt sweetness.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Amber_ale",
+    "min_abv": 4.5,
+    "max_abv": 6.2,
+    "min_ibu": 25,
+    "max_ibu": 40
+  },
+  {
+    "name": "American Strong Ale",
+    "description": "A broad category for strong, intensely flavored American ales that don't quite fit into the barleywine or double IPA categories. They are typically aggressively hopped with a massive malt foundation.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Strong_ale#American_strong_ale",
+    "min_abv": 7.0,
+    "max_abv": 11.9,
+    "min_ibu": 50,
+    "max_ibu": 100
+  },
+  {
+    "name": "American Barleywine",
+    "description": "A well-hopped American interpretation of the richest and strongest of the English ales. The hop character is assertive and bitter, balancing a massive, complex, and intensely sweet malt body.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Barley_wine#American_Barleywine",
+    "min_abv": 8.0,
+    "max_abv": 12.0,
+    "min_ibu": 50,
+    "max_ibu": 100
+  },
+  {
+    "name": "Blonde Ale",
+    "description": "An easy-drinking, approachable, malt-oriented American craft beer. It has a light to medium body, gentle hop bitterness, and a clean, slightly sweet malt profile, often acting as a gateway to craft beer.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Blonde_ale",
+    "min_abv": 3.8,
+    "max_abv": 5.5,
+    "min_ibu": 15,
+    "max_ibu": 28
+  },
+  {
+    "name": "Scottish Light",
+    "description": "A traditional Scottish session ale. It is malt-focused, utilizing cool fermentation temperatures to produce a clean profile that emphasizes caramel and toffee notes over hop bitterness.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Beer_in_Scotland#Light",
+    "min_abv": 2.5,
+    "max_abv": 3.2,
+    "min_ibu": 10,
+    "max_ibu": 20
+  },
+  {
+    "name": "Scottish Heavy",
+    "description": "A slightly stronger version of the Scottish Light. It maintains the malt-forward, caramel-heavy profile and clean fermentation character, with just enough bitterness to prevent it from being cloying.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Beer_in_Scotland#Heavy",
+    "min_abv": 3.2,
+    "max_abv": 3.9,
+    "min_ibu": 10,
+    "max_ibu": 20
+  },
+  {
+    "name": "Scottish Export",
+    "description": "The strongest of the standard Scottish session ales. It features a deep, complex maltiness with rich caramel, toffee, and occasionally faint roasted notes, perfectly balanced for drinkability.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Beer_in_Scotland#Export",
+    "min_abv": 3.9,
+    "max_abv": 6.0,
+    "min_ibu": 15,
+    "max_ibu": 30
+  },
+  {
+    "name": "English Pale Ale",
+    "description": "A classic British ale with a balanced profile of earthy, floral hops and a biscuity, caramel-tinged malt base. It is moderate in strength and highly sessionable.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Pale_ale",
+    "min_abv": 4.5,
+    "max_abv": 5.5,
+    "min_ibu": 20,
+    "max_ibu": 40
+  },
+  {
+    "name": "Ordinary Bitter",
+    "description": "A low-gravity, low-alcohol, and highly drinkable British session ale. Despite its name, it focuses on a balance of biscuity malt and earthy hop flavor, traditionally served on cask.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Bitter_(beer)",
+    "min_abv": 3.2,
+    "max_abv": 3.8,
+    "min_ibu": 25,
+    "max_ibu": 35
+  },
+  {
+    "name": "Best Bitter",
+    "description": "A moderately strong British bitter that provides a slightly richer malt backbone and more pronounced hop character than an Ordinary Bitter, while maintaining exceptional sessionability.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Bitter_(beer)",
+    "min_abv": 3.8,
+    "max_abv": 4.6,
+    "min_ibu": 25,
+    "max_ibu": 40
+  },
+  {
+    "name": "Old Ale",
+    "description": "A traditional English ale of moderate to significant strength, typically aged. It develops complex, sweet, and nutty malt flavors, often acquiring slight tartness or dark fruit notes from extended cellar maturation.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Old_ale",
+    "min_abv": 5.5,
+    "max_abv": 9.0,
+    "min_ibu": 30,
+    "max_ibu": 60
+  },
+  {
+    "name": "Brett Beer",
+    "description": "Any beer fermented primarily or secondarily with Brettanomyces yeast. It is characterized by complex, funky, rustic, and 'barnyard' or leather-like aromas, rather than outright sourness.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Brettanomyces",
+    "min_abv": 5.0,
+    "max_abv": 8.5,
+    "min_ibu": 10,
+    "max_ibu": 30
+  },
+  {
+    "name": "Mixed-Fermentation Sour Beer",
+    "description": "A sour ale fermented with a combination of brewer's yeast, Brettanomyces, and lactic acid bacteria. It offers a complex, deeply tart profile layered with rustic funk and fruity esters.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Sour_beer",
+    "min_abv": 4.0,
+    "max_abv": 8.0,
+    "min_ibu": 5,
+    "max_ibu": 20
+  },
+  {
+    "name": "Wild Ale",
+    "description": "A beer fermented with wild yeast or bacteria native to a specific environment, rather than cultivated strains. The result is uniquely tied to its terroir, often profoundly tart and funk-forward.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Sour_beer#American_wild_ale",
+    "min_abv": 5.0,
+    "max_abv": 8.0,
+    "min_ibu": 5,
+    "max_ibu": 30
+  },
+  {
+    "name": "Fruit Beer",
+    "description": "A harmonious marriage of fruit and beer, where the fruit character complements the underlying beer style without overwhelming it. The base can range from light wheat beers to heavy stouts.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Fruit_beer",
+    "min_abv": 4.0,
+    "max_abv": 8.0,
+    "min_ibu": 5,
+    "max_ibu": 45
+  },
+  {
+    "name": "Spice/Herb/Vegetable Beer",
+    "description": "A beer that incorporates culinary spices, herbs, or vegetables to enhance the flavor profile. The additions are meant to be noticeable but balanced with the base beer style.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Vegetable_beer",
+    "min_abv": 4.0,
+    "max_abv": 8.0,
+    "min_ibu": 5,
+    "max_ibu": 40
+  },
+  {
+    "name": "Pumpkin Ale",
+    "description": "A quintessential American seasonal beer brewed with pumpkin or winter squash and a blend of traditional autumn spices like cinnamon, nutmeg, ginger, and cloves, evoking the flavor of pumpkin pie.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Pumpkin_ale",
+    "min_abv": 4.0,
+    "max_abv": 7.5,
+    "min_ibu": 10,
+    "max_ibu": 35
+  },
+  {
+    "name": "Winter Warmer",
+    "description": "A traditional holiday seasonal ale. It is typically malty, dark, and strong, often featuring warming spices and a pronounced alcohol presence to combat the winter chill.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Old_ale#Winter_warmer",
+    "min_abv": 5.5,
+    "max_abv": 8.0,
+    "min_ibu": 20,
+    "max_ibu": 50
+  },
+  {
+    "name": "Bière Brut",
+    "description": "A highly specialized, effervescent Belgian beer style brewed using the méthode champenoise. It is extremely dry, highly carbonated, and features complex fruity and spicy yeast notes, resembling a fine sparkling wine.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Beer_in_Belgium",
+    "min_abv": 8.0,
+    "max_abv": 11.5,
+    "min_ibu": 15,
+    "max_ibu": 30
+  },
+  {
+    "name": "Kentucky Common",
+    "description": "A historical American style originating in Louisville. It is a fast-fermenting, dark, slightly sweet, and lightly roasty ale brewed with a large proportion of corn, intended to be consumed fresh.",
+    "wikipedia_link": "https://en.wikipedia.org/wiki/Kentucky_common_beer",
+    "min_abv": 4.0,
+    "max_abv": 5.5,
+    "min_ibu": 15,
+    "max_ibu": 30
+  }
+]

pipeline/biergarten_pipeline.puml

@@ -0,0 +1,169 @@
+@startuml BiergartenPipeline
+title Biergarten Pipeline - Class and Composition Diagram
+
+left to right direction
+skinparam shadowing false
+skinparam classAttributeIconSize 0
+skinparam packageStyle rectangle
+
+package "Composition root" {
+  class Main <<entrypoint>> {
+    +main(argc: int, argv: char**): int
+  }
+
+  class CurlGlobalState {
+    +CurlGlobalState()
+    +~CurlGlobalState()
+  }
+
+  note right of Main
+    Binds with Boost.DI:
+    - WebClient -> CURLWebClient
+    - IEnrichmentService -> WikipediaService
+    - DataGenerator -> MockGenerator or LlamaGenerator
+    - LlamaGenerator receives ApplicationOptions and model_path directly
+  end note
+}
+
+package "Core orchestration" {
+  class BiergartenDataGenerator {
+    -context_service_: std::shared_ptr<IEnrichmentService>
+    -generator_: std::unique_ptr<DataGenerator>
+    -generated_breweries_: std::vector<GeneratedBrewery>
+    +BiergartenDataGenerator(context_service: std::shared_ptr<IEnrichmentService>, generator: std::unique_ptr<DataGenerator>)
+    +Run(): bool
+    -QueryCitiesWithCountries(): std::vector<Location>
+    -GenerateBreweries(cities: std::vector<EnrichedCity>): void
+    -LogResults(): void
+  }
+}
+
+package "Data models" {
+  class ApplicationOptions <<struct>> {
+    +model_path: std::string
+    +use_mocked: bool
+    +temperature: float
+    +top_p: float
+    +top_k: uint32_t
+    +n_ctx: uint32_t
+    +seed: int
+  }
+
+  class BreweryLocation <<struct>> {
+    +city_name: std::string_view
+    +country_name: std::string_view
+  }
+
+  class Location <<struct>> {
+    +city: std::string
+    +state_province: std::string
+    +iso3166_2: std::string
+    +country: std::string
+    +iso3166_1: std::string
+    +latitude: double
+    +longitude: double
+  }
+
+  class BreweryResult <<struct>> {
+    +name: std::string
+    +description: std::string
+  }
+
+  class UserResult <<struct>> {
+    +username: std::string
+    +bio: std::string
+  }
+
+  class EnrichedCity <<struct>> {
+    +location: Location
+    +region_context: std::string
+  }
+
+  class GeneratedBrewery <<struct>> {
+    +location: Location
+    +brewery: BreweryResult
+  }
+}
+
+package "Generation" {
+  interface DataGenerator {
+    +GenerateBrewery(location: BreweryLocation, region_context: std::string): BreweryResult
+    +GenerateUser(locale: std::string): UserResult
+  }
+
+  class MockGenerator {
+    +GenerateBrewery(location: BreweryLocation, region_context: std::string): BreweryResult
+    +GenerateUser(locale: std::string): UserResult
+  }
+
+  class LlamaGenerator {
+    +LlamaGenerator(options: ApplicationOptions, model_path: std::string)
+    +GenerateBrewery(location: BreweryLocation, region_context: std::string): BreweryResult
+    +GenerateUser(locale: std::string): UserResult
+  }
+}
+
+package "HTTP" {
+  interface WebClient {
+    +DownloadToFile(url: std::string, file_path: std::string): void
+    +Get(url: std::string): std::string
+    +UrlEncode(value: std::string): std::string
+  }
+
+  class CURLWebClient {
+    +CURLWebClient()
+    +~CURLWebClient()
+    +DownloadToFile(url: std::string, file_path: std::string): void
+    +Get(url: std::string): std::string
+    +UrlEncode(value: std::string): std::string
+  }
+}
+
+package "JSON handling" {
+  class JsonLoader {
+    {static} +LoadLocations(filepath: std::string): std::vector<Location>
+  }
+}
+
+package "Wikipedia" {
+  interface IEnrichmentService {
+    +GetLocationContext(loc: Location): std::string
+  }
+
+  class WikipediaService {
+    +WikipediaService(client: std::shared_ptr<WebClient>)
+    +GetLocationContext(loc: Location): std::string
+  }
+}
+
+Main --> CurlGlobalState
+Main --> ApplicationOptions
+Main --> BiergartenDataGenerator
+Main ..> IEnrichmentService : DI binding
+Main ..> DataGenerator : DI factory
+Main ..> CURLWebClient : DI binding
+
+BiergartenDataGenerator *-- EnrichedCity
+BiergartenDataGenerator *-- GeneratedBrewery
+BiergartenDataGenerator ..> JsonLoader : LoadLocations()
+BiergartenDataGenerator --> IEnrichmentService : context lookup
+BiergartenDataGenerator --> DataGenerator : brewery generation
+BiergartenDataGenerator ..> Location
+BiergartenDataGenerator ..> BreweryResult
+
+DataGenerator <|.. MockGenerator
+DataGenerator <|.. LlamaGenerator
+WebClient <|.. CURLWebClient
+IEnrichmentService <|.. WikipediaService
+
+WikipediaService --> WebClient : shared_ptr
+
+note right of BiergartenDataGenerator
+Current behavior:
+samples up to four locations per run.
+Enrichment runs once per sampled city.
+If a lookup throws, that city is skipped.
+Empty context is retained and still passed to the generator.
+end note
+
+@enduml

pipeline/includes/biergarten_data_generator.h

@@ -0,0 +1,76 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_DATA_GENERATOR_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_DATA_GENERATOR_H_
+
+/**
+ * @file biergarten_data_generator.h
+ * @brief Core orchestration class for pipeline data generation.
+ */
+
+#include <memory>
+#include <vector>
+
+#include "data_generation/data_generator.h"
+#include "data_model/enriched_city.h"
+#include "data_model/generated_brewery.h"
+#include "data_model/location.h"
+#include "services/enrichment_service.h"
+
+/**
+ * @brief Main data generator class for the Biergarten pipeline.
+ *
+ * This class encapsulates the core logic for generating brewery data.
+ * It handles location loading, city enrichment, and brewery generation.
+ */
+class BiergartenDataGenerator {
+  public:
+   /**
+    * @brief Construct a BiergartenDataGenerator with injected dependencies.
+    *
+    * @param context_service Context provider for sampled locations.
+    * @param generator Brewery and user data generator.
+    */
+   BiergartenDataGenerator(std::shared_ptr<IEnrichmentService> context_service,
+                           std::unique_ptr<DataGenerator> generator);
+
+   /**
+    * @brief Run the data generation pipeline.
+    *
+    * Performs the following steps:
+    * 1. Load curated locations from JSON
+    * 2. Resolve context for each city using the injected context service
+    * 3. Generate brewery data for sampled cities
+    *
+    * @return true if successful, false if not
+    */
+   bool Run();
+
+  private:
+   /// @brief Shared context provider dependency.
+   std::shared_ptr<IEnrichmentService> context_service_;
+
+   /// @brief Generator dependency selected in the composition root.
+   std::unique_ptr<DataGenerator> generator_;
+
+   /**
+    * @brief Load locations from JSON and sample cities.
+    *
+    * @return Vector of sampled locations capped at 4 entries.
+    */
+   static std::vector<Location> QueryCitiesWithCountries();
+
+   /**
+    * @brief Generate breweries for enriched cities.
+    *
+    * @param cities Vector of enriched city data.
+    */
+   void GenerateBreweries(const std::vector<EnrichedCity>& cities);
+
+   /**
+    * @brief Log the generated brewery results.
+    */
+   void LogResults() const;
+
+   /// @brief Stores generated brewery data.
+   std::vector<GeneratedBrewery> generated_breweries_;
+};
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_DATA_GENERATOR_H_

pipeline/includes/data_generation/data_generator.h

@@ -0,0 +1,42 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_DATA_GENERATOR_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_DATA_GENERATOR_H_
+
+/**
+ * @file data_generation/data_generator.h
+ * @brief Shared generator interfaces and result models.
+ */
+
+#include <string>
+
+#include "data_model/brewery_location.h"
+#include "data_model/brewery_result.h"
+#include "data_model/user_result.h"
+
+/**
+ * @brief Interface for data generator implementations.
+ */
+class DataGenerator {
+  public:
+   /// @brief Virtual destructor for polymorphic cleanup.
+   virtual ~DataGenerator() = default;
+
+   /**
+    * @brief Generates brewery data for a location.
+    *
+    * @param location City and country names.
+    * @param region_context Additional regional context text.
+    * @return Brewery generation result.
+    */
+   virtual BreweryResult GenerateBrewery(const BreweryLocation& location,
+                                         const std::string& region_context) = 0;
+
+   /**
+    * @brief Generates a user profile for a locale.
+    *
+    * @param locale Locale hint used by generator.
+    * @return User generation result.
+    */
+   virtual UserResult GenerateUser(const std::string& locale) = 0;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_DATA_GENERATOR_H_

pipeline/includes/data_generation/llama_generator.h

@@ -0,0 +1,122 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_LLAMA_GENERATOR_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_LLAMA_GENERATOR_H_
+
+/**
+ * @file data_generation/llama_generator.h
+ * @brief Llama.cpp-backed implementation of DataGenerator.
+ */
+
+#include <cstdint>
+#include <random>
+#include <string>
+#include <string_view>
+
+#include "data_generation/data_generator.h"
+#include "data_model/application_options.h"
+
+struct llama_model;
+struct llama_context;
+
+/**
+ * @brief Data generator implementation backed by llama.cpp.
+ */
+class LlamaGenerator final : public DataGenerator {
+  public:
+   /**
+    * @brief Constructs a generator using parsed application options and loads
+    * the configured model immediately.
+    *
+    * @param options Parsed application options.
+    * @param model_path Filesystem path to GGUF model assets.
+    */
+   LlamaGenerator(const ApplicationOptions& options,
+                  const std::string& model_path);
+
+   /// @brief Releases model/context resources.
+   ~LlamaGenerator() override;
+
+   /**
+    * @brief Generates brewery data for a specific location.
+    *
+    * @param location City and country names.
+    * @param region_context Additional regional context.
+    * @return Generated brewery result.
+    */
+   BreweryResult GenerateBrewery(const BreweryLocation& location,
+                                 const std::string& region_context) override;
+
+   /**
+    * @brief Generates a user profile for the provided locale.
+    *
+    * @param locale Locale hint.
+    * @return Generated user profile.
+    */
+   UserResult GenerateUser(const std::string& locale) override;
+
+  private:
+   /**
+    * @brief Loads model and prepares inference context.
+    *
+    * @param model_path Filesystem path to GGUF model.
+    */
+   void Load(const std::string& model_path);
+
+   /**
+    * @brief Infers text from a user prompt.
+    *
+    * @param prompt User prompt.
+    * @param max_tokens Maximum tokens to generate.
+    * @return Generated text.
+    */
+   std::string Infer(const std::string& prompt, int max_tokens = 10000);
+
+   /**
+    * @brief Infers text from separate system and user prompts.
+    *
+    * This helps chat-capable models preserve system-role behavior instead of
+    * concatenating system text into user input.
+    *
+    * @param system_prompt System role prompt.
+    * @param prompt User prompt.
+    * @param max_tokens Maximum tokens to generate.
+    * @return Generated text.
+    */
+   std::string Infer(const std::string& system_prompt,
+                     const std::string& prompt, int max_tokens = 10000);
+
+   /**
+    * @brief Runs inference on an already-formatted prompt.
+    *
+    * @param formatted_prompt Prompt preformatted for model chat template.
+    * @param max_tokens Maximum tokens to generate.
+    * @return Generated text.
+    */
+   std::string InferFormatted(const std::string& formatted_prompt,
+                              int max_tokens = 10000);
+
+   /**
+    * @brief Loads the brewery system prompt from disk.
+    *
+    * @param prompt_file_path Prompt file path to try first.
+    * @return Loaded prompt text or fallback prompt.
+    */
+   std::string LoadBrewerySystemPrompt(const std::string& prompt_file_path);
+
+   /**
+    * @brief Returns a built-in fallback system prompt.
+    *
+    * @return Fallback prompt text.
+    */
+   std::string GetFallbackBreweryPrompt();
+
+   llama_model* model_ = nullptr;
+   llama_context* context_ = nullptr;
+   float sampling_temperature_ = 1.0F;
+   float sampling_top_p_ = 0.95F;
+   uint32_t sampling_top_k_ = 64;
+   std::mt19937 rng_;
+   uint32_t n_ctx_ = 8192;
+   std::string brewery_system_prompt_;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_LLAMA_GENERATOR_H_

pipeline/includes/data_generation/llama_generator_helpers.h

@@ -0,0 +1,90 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_LLAMA_GENERATOR_HELPERS_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_LLAMA_GENERATOR_HELPERS_H_
+
+/**
+ * @file data_generation/llama_generator_helpers.h
+ * @brief Shared helper APIs used by LlamaGenerator translation units.
+ */
+
+#include <cstddef>
+#include <string>
+#include <string_view>
+#include <utility>
+
+struct llama_model;
+struct llama_vocab;
+typedef int llama_token;
+
+/**
+ * @brief Normalizes and truncates regional context.
+ *
+ * @param region_context Input regional context text.
+ * @param max_chars Maximum output length.
+ * @return Processed region context.
+ */
+std::string PrepareRegionContextPublic(std::string_view region_context,
+                                       std::size_t max_chars = 2000);
+
+/**
+ * @brief Parses a response expected to contain two logical lines.
+ *
+ * @param raw Raw model output.
+ * @param error_message Error message thrown on parse failure.
+ * @return Pair containing first and second parsed fields.
+ */
+std::pair<std::string, std::string> ParseTwoLineResponsePublic(
+    const std::string& raw, const std::string& error_message);
+
+/**
+ * @brief Applies model chat template to a user-only prompt.
+ *
+ * @param model Loaded llama model.
+ * @param user_prompt User prompt text.
+ * @return Model-formatted prompt.
+ */
+std::string ToChatPromptPublic(const llama_model* model,
+                               const std::string& user_prompt);
+
+/**
+ * @brief Applies model chat template to system and user prompts.
+ *
+ * @param model Loaded llama model.
+ * @param system_prompt System prompt text.
+ * @param user_prompt User prompt text.
+ * @return Model-formatted prompt.
+ */
+std::string ToChatPromptPublic(const llama_model* model,
+                               const std::string& system_prompt,
+                               const std::string& user_prompt);
+
+/**
+ * @brief Decodes a sampled token and appends it to output text.
+ *
+ * @param vocab Model vocabulary.
+ * @param token Sampled token id.
+ * @param output Output text buffer.
+ */
+void AppendTokenPiecePublic(const llama_vocab* vocab, llama_token token,
+                            std::string& output);
+
+/**
+ * @brief Validates and parses brewery JSON output.
+ *
+ * @param raw Raw model output.
+ * @param name_out Parsed brewery name.
+ * @param description_out Parsed brewery description.
+ * @return Empty string on success, or validation error message.
+ */
+std::string ValidateBreweryJsonPublic(const std::string& raw,
+                                      std::string& name_out,
+                                      std::string& description_out);
+
+/**
+ * @brief Extracts the last balanced JSON object from text.
+ *
+ * @param text Input text.
+ * @return Extracted JSON object or an empty string if none exists.
+ */
+std::string ExtractLastJsonObjectPublic(const std::string& text);
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_LLAMA_GENERATOR_HELPERS_H_

pipeline/includes/data_generation/mock_generator.h

@@ -0,0 +1,54 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_MOCK_GENERATOR_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_MOCK_GENERATOR_H_
+
+/**
+ * @file data_generation/mock_generator.h
+ * @brief Deterministic mock implementation of DataGenerator.
+ */
+
+#include <string>
+#include <string_view>
+#include <vector>
+
+#include "data_generation/data_generator.h"
+
+/**
+ * @brief Mock generator used for deterministic, model-free outputs.
+ */
+class MockGenerator final : public DataGenerator {
+  public:
+   /**
+    * @brief Generates deterministic brewery data for a location.
+    *
+    * @param location City and country names.
+    * @param region_context Unused for mock generation.
+    * @return Generated brewery result.
+    */
+   BreweryResult GenerateBrewery(const BreweryLocation& location,
+                                 const std::string& region_context) override;
+
+   /**
+    * @brief Generates deterministic user data for a locale.
+    *
+    * @param locale Locale hint.
+    * @return Generated user result.
+    */
+   UserResult GenerateUser(const std::string& locale) override;
+
+  private:
+   /**
+    * @brief Combines two strings into a stable hash value.
+    *
+    * @param location City and country names.
+    * @return Deterministic hash value.
+    */
+   static std::size_t DeterministicHash(const BreweryLocation& location);
+
+   static const std::vector<std::string> kBreweryAdjectives;
+   static const std::vector<std::string> kBreweryNouns;
+   static const std::vector<std::string> kBreweryDescriptions;
+   static const std::vector<std::string> kUsernames;
+   static const std::vector<std::string> kBios;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_MOCK_GENERATOR_H_

pipeline/includes/data_model/application_options.h

@@ -0,0 +1,42 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_APPLICATION_OPTIONS_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_APPLICATION_OPTIONS_H_
+
+/**
+ * @file data_model/application_options.h
+ * @brief Program options for the Biergarten pipeline application.
+ */
+
+#include <cstdint>
+#include <string>
+
+/**
+ * @brief Program options for the Biergarten pipeline application.
+ */
+struct ApplicationOptions {
+   /// @brief Path to the LLM model file (gguf format); mutually exclusive with
+   /// use_mocked.
+   std::string model_path;
+
+   /// @brief Use mocked generator instead of LLM; mutually exclusive with
+   /// model_path.
+   bool use_mocked = false;
+
+   /// @brief LLM sampling temperature (0.0 to 1.0, higher = more random).
+   float temperature = 1.0F;
+
+   /// @brief LLM nucleus sampling top-p parameter (0.0 to 1.0, higher = more
+   /// random).
+   float top_p = 0.95F;
+
+   /// @brief LLM top-k sampling parameter.
+   uint32_t top_k = 64;
+
+   /// @brief Context window size (tokens) for LLM inference. Higher values
+   /// support longer prompts but use more memory.
+   uint32_t n_ctx = 2048;
+
+   /// @brief Random seed for sampling (-1 for random, otherwise non-negative).
+   int seed = -1;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_APPLICATION_OPTIONS_H_

pipeline/includes/data_model/brewery_location.h

@@ -0,0 +1,22 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_BREWERY_LOCATION_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_BREWERY_LOCATION_H_
+
+/**
+ * @file data_model/brewery_location.h
+ * @brief Non-owning brewery location input.
+ */
+
+#include <string_view>
+
+/**
+ * @brief Non-owning brewery location input.
+ */
+struct BreweryLocation {
+   /// @brief City name.
+   std::string_view city_name;
+
+   /// @brief Country name.
+   std::string_view country_name;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_BREWERY_LOCATION_H_

pipeline/includes/data_model/brewery_result.h

@@ -0,0 +1,22 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_BREWERY_RESULT_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_BREWERY_RESULT_H_
+
+/**
+ * @file data_model/brewery_result.h
+ * @brief Generated brewery payload.
+ */
+
+#include <string>
+
+/**
+ * @brief Generated brewery payload.
+ */
+struct BreweryResult {
+   /// @brief Brewery display name.
+   std::string name;
+
+   /// @brief Brewery description text.
+   std::string description;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_BREWERY_RESULT_H_

pipeline/includes/data_model/enriched_city.h

@@ -0,0 +1,21 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_ENRICHED_CITY_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_ENRICHED_CITY_H_
+
+/**
+ * @file data_model/enriched_city.h
+ * @brief Enriched city data with Wikipedia context.
+ */
+
+#include <string>
+
+#include "data_model/location.h"
+
+/**
+ * @brief Enriched city data with Wikipedia context.
+ */
+struct EnrichedCity {
+   Location location;
+   std::string region_context;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_ENRICHED_CITY_H_

pipeline/includes/data_model/generated_brewery.h

@@ -0,0 +1,20 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_GENERATED_BREWERY_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_GENERATED_BREWERY_H_
+
+/**
+ * @file data_model/generated_brewery.h
+ * @brief Helper struct to store generated brewery data.
+ */
+
+#include "data_model/brewery_result.h"
+#include "data_model/location.h"
+
+/**
+ * @brief Helper struct to store generated brewery data.
+ */
+struct GeneratedBrewery {
+   Location location;
+   BreweryResult brewery;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_GENERATED_BREWERY_H_

pipeline/includes/data_model/generation_models.h

@@ -0,0 +1,13 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_GENERATION_MODELS_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_GENERATION_MODELS_H_
+
+/**
+ * @file data_model/generation_models.h
+ * @brief Convenience include for shared generation payload models.
+ */
+
+#include "data_model/brewery_location.h"
+#include "data_model/brewery_result.h"
+#include "data_model/user_result.h"
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_GENERATION_MODELS_H_

pipeline/includes/data_model/location.h

@@ -0,0 +1,37 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_LOCATION_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_LOCATION_H_
+
+/**
+ * @file data_model/location.h
+ * @brief Location data model used throughout generation pipeline.
+ */
+
+#include <string>
+
+/**
+ * @brief Canonical location record for city-level generation.
+ */
+struct Location {
+   /// @brief City name.
+   std::string city;
+
+   /// @brief State or province name.
+   std::string state_province;
+
+   /// @brief ISO 3166-2 subdivision code.
+   std::string iso3166_2;
+
+   /// @brief Country name.
+   std::string country;
+
+   /// @brief ISO 3166-1 country code.
+   std::string iso3166_1;
+
+   /// @brief Latitude in decimal degrees.
+   double latitude;
+
+   /// @brief Longitude in decimal degrees.
+   double longitude;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_LOCATION_H_

pipeline/includes/data_model/pipeline_models.h

@@ -0,0 +1,12 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_PIPELINE_MODELS_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_PIPELINE_MODELS_H_
+
+/**
+ * @file data_model/pipeline_models.h
+ * @brief Convenience include for pipeline-specific data models.
+ */
+
+#include "data_model/enriched_city.h"
+#include "data_model/generated_brewery.h"
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_PIPELINE_MODELS_H_

pipeline/includes/data_model/user_result.h

@@ -0,0 +1,22 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_USER_RESULT_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_USER_RESULT_H_
+
+/**
+ * @file data_model/user_result.h
+ * @brief Generated user profile payload.
+ */
+
+#include <string>
+
+/**
+ * @brief Generated user profile payload.
+ */
+struct UserResult {
+   /// @brief Username handle.
+   std::string username;
+
+   /// @brief Short user biography.
+   std::string bio;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_USER_RESULT_H_

pipeline/includes/json_handling/json_loader.h

@@ -0,0 +1,21 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_JSON_HANDLING_JSON_LOADER_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_JSON_HANDLING_JSON_LOADER_H_
+
+/**
+ * @file json_handling/json_loader.h
+ * @brief Loader API for curated location data.
+ */
+
+#include <string>
+#include <vector>
+
+#include "data_model/location.h"
+
+/// @brief Loads curated world locations from a JSON file into memory.
+class JsonLoader {
+  public:
+   /// @brief Parses a JSON array file and returns all location records.
+   static std::vector<Location> LoadLocations(const std::string& filepath);
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_JSON_HANDLING_JSON_LOADER_H_

pipeline/includes/llama_backend_state.h

@@ -0,0 +1,32 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_LLAMA_BACKEND_STATE_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_LLAMA_BACKEND_STATE_H_
+
+/**
+ * @file llama_backend_state.h
+ * @brief RAII guard for llama.cpp backend process lifetime.
+ */
+
+#include <llama.h>
+
+/**
+ * @brief RAII wrapper for llama_backend_init and llama_backend_free.
+ *
+ * Create one instance in application startup before using llama.cpp and keep
+ * it alive for application lifetime.
+ */
+class LlamaBackendState {
+  public:
+   /// @brief Initializes global llama backend state.
+   LlamaBackendState() { llama_backend_init(); }
+
+   /// @brief Cleans up global llama backend state.
+   ~LlamaBackendState() { llama_backend_free(); }
+
+   /// @brief Non-copyable type.
+   LlamaBackendState(const LlamaBackendState&) = delete;
+
+   /// @brief Non-copyable type.
+   LlamaBackendState& operator=(const LlamaBackendState&) = delete;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_LLAMA_BACKEND_STATE_H_

pipeline/includes/services/enrichment_service.h

@@ -0,0 +1,30 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ENRICHMENT_SERVICE_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ENRICHMENT_SERVICE_H_
+
+/**
+ * @file services/enrichment_service.h
+ * @brief Abstraction for resolving contextual enrichment for a location.
+ */
+
+#include <string>
+
+#include "data_model/location.h"
+
+/**
+ * @brief Interface for services that can enrich a location with context.
+ */
+class IEnrichmentService {
+  public:
+   /// @brief Virtual destructor for polymorphic cleanup.
+   virtual ~IEnrichmentService() = default;
+
+   /**
+    * @brief Resolves contextual enrichment for a location.
+    *
+    * @param loc Location to enrich.
+    * @return Context text, or an empty string if unavailable.
+    */
+   virtual std::string GetLocationContext(const Location& loc) = 0;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ENRICHMENT_SERVICE_H_

pipeline/includes/services/wikipedia_service.h

@@ -0,0 +1,33 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_WIKIPEDIA_SERVICE_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_WIKIPEDIA_SERVICE_H_
+
+/**
+ * @file services/wikipedia_service.h
+ * @brief Wikipedia summary retrieval service with in-memory caching.
+ */
+
+#include <memory>
+#include <string>
+#include <string_view>
+#include <unordered_map>
+
+#include "services/enrichment_service.h"
+#include "web_client/web_client.h"
+
+/// @brief Provides cached Wikipedia summary lookups for city and country pairs.
+class WikipediaService final : public IEnrichmentService {
+  public:
+   /// @brief Creates a new Wikipedia service with the provided web client.
+   explicit WikipediaService(std::shared_ptr<WebClient> client);
+
+   /// @brief Returns the Wikipedia-derived context for a location.
+   [[nodiscard]] std::string GetLocationContext(const Location& loc) override;
+
+  private:
+   std::string FetchExtract(std::string_view query);
+   std::shared_ptr<WebClient> client_;
+   std::unordered_map<std::string, std::string> cache_;
+   std::unordered_map<std::string, std::string> extract_cache_;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_WIKIPEDIA_SERVICE_H_

pipeline/includes/web_client/curl_web_client.h

@@ -0,0 +1,54 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_WEB_CLIENT_CURL_WEB_CLIENT_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_WEB_CLIENT_CURL_WEB_CLIENT_H_
+
+/**
+ * @file web_client/curl_web_client.h
+ * @brief libcurl-based WebClient implementation.
+ */
+
+#include "web_client/web_client.h"
+
+/**
+ * @brief RAII wrapper for curl_global_init and curl_global_cleanup.
+ *
+ * Create one instance in application startup before using libcurl and keep it
+ * alive for application lifetime.
+ */
+class CurlGlobalState {
+  public:
+   /// @brief Initializes global libcurl state.
+   CurlGlobalState();
+
+   /// @brief Cleans up global libcurl state.
+   ~CurlGlobalState();
+
+   /// @brief Non-copyable type.
+   CurlGlobalState(const CurlGlobalState&) = delete;
+
+   /// @brief Non-copyable type.
+   CurlGlobalState& operator=(const CurlGlobalState&) = delete;
+};
+
+/**
+ * @brief WebClient implementation backed by libcurl.
+ */
+class CURLWebClient : public WebClient {
+  public:
+   /**
+    * @brief Executes an HTTP GET request.
+    *
+    * @param url Request URL.
+    * @return Response body.
+    */
+   std::string Get(const std::string& url) override;
+
+   /**
+    * @brief URL-encodes a string value.
+    *
+    * @param value Raw value.
+    * @return URL-encoded string.
+    */
+   std::string UrlEncode(const std::string& value) override;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_WEB_CLIENT_CURL_WEB_CLIENT_H_

pipeline/includes/web_client/web_client.h

@@ -0,0 +1,36 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_WEB_CLIENT_WEB_CLIENT_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_WEB_CLIENT_WEB_CLIENT_H_
+
+/**
+ * @file web_client/web_client.h
+ * @brief Abstract interface for HTTP and URL utilities.
+ */
+
+#include <string>
+
+/**
+ * @brief Abstract web client interface.
+ */
+class WebClient {
+  public:
+   /// @brief Virtual destructor for polymorphic cleanup.
+   virtual ~WebClient() = default;
+
+   /**
+    * @brief Executes an HTTP GET request.
+    *
+    * @param url Request URL.
+    * @return Response body.
+    */
+   virtual std::string Get(const std::string& url) = 0;
+
+   /**
+    * @brief URL-encodes a string value.
+    *
+    * @param value Raw string value.
+    * @return Encoded value safe for URL usage.
+    */
+   virtual std::string UrlEncode(const std::string& value) = 0;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_WEB_CLIENT_WEB_CLIENT_H_

pipeline/locations.json

@@ -0,0 +1,902 @@
+[
+  {
+    "city": "Cape Town",
+    "state_province": "Western Cape",
+    "iso3166_2": "ZA-WC",
+    "country": "South Africa",
+    "iso3166_1": "ZA",
+    "latitude": -33.9249,
+    "longitude": 18.4241
+  },
+  {
+    "city": "Johannesburg",
+    "state_province": "Gauteng",
+    "iso3166_2": "ZA-GT",
+    "country": "South Africa",
+    "iso3166_1": "ZA",
+    "latitude": -26.2041,
+    "longitude": 28.0473
+  },
+  {
+    "city": "Durban",
+    "state_province": "KwaZulu-Natal",
+    "iso3166_2": "ZA-NL",
+    "country": "South Africa",
+    "iso3166_1": "ZA",
+    "latitude": -29.8587,
+    "longitude": 31.0218
+  },
+  {
+    "city": "Franschhoek",
+    "state_province": "Western Cape",
+    "iso3166_2": "ZA-WC",
+    "country": "South Africa",
+    "iso3166_1": "ZA",
+    "latitude": -33.9146,
+    "longitude": 19.1198
+  },
+  {
+    "city": "Nairobi",
+    "state_province": "Nairobi",
+    "iso3166_2": "KE-30",
+    "country": "Kenya",
+    "iso3166_1": "KE",
+    "latitude": -1.2921,
+    "longitude": 36.8219
+  },
+  {
+    "city": "Buenos Aires",
+    "state_province": "Buenos Aires City",
+    "iso3166_2": "AR-C",
+    "country": "Argentina",
+    "iso3166_1": "AR",
+    "latitude": -34.6037,
+    "longitude": -58.3816
+  },
+  {
+    "city": "Bariloche",
+    "state_province": "Río Negro",
+    "iso3166_2": "AR-R",
+    "country": "Argentina",
+    "iso3166_1": "AR",
+    "latitude": -41.1335,
+    "longitude": -71.3103
+  },
+  {
+    "city": "Bogotá",
+    "state_province": "Bogotá D.C.",
+    "iso3166_2": "CO-DC",
+    "country": "Colombia",
+    "iso3166_1": "CO",
+    "latitude": 4.711,
+    "longitude": -74.0721
+  },
+  {
+    "city": "Medellín",
+    "state_province": "Antioquia",
+    "iso3166_2": "CO-ANT",
+    "country": "Colombia",
+    "iso3166_1": "CO",
+    "latitude": 6.2442,
+    "longitude": -75.5812
+  },
+  {
+    "city": "São Paulo",
+    "state_province": "São Paulo",
+    "iso3166_2": "BR-SP",
+    "country": "Brazil",
+    "iso3166_1": "BR",
+    "latitude": -23.5505,
+    "longitude": -46.6333
+  },
+  {
+    "city": "Curitiba",
+    "state_province": "Paraná",
+    "iso3166_2": "BR-PR",
+    "country": "Brazil",
+    "iso3166_1": "BR",
+    "latitude": -25.4284,
+    "longitude": -49.2733
+  },
+  {
+    "city": "Rio de Janeiro",
+    "state_province": "Rio de Janeiro",
+    "iso3166_2": "BR-RJ",
+    "country": "Brazil",
+    "iso3166_1": "BR",
+    "latitude": -22.9068,
+    "longitude": -43.1729
+  },
+  {
+    "city": "Santiago",
+    "state_province": "Santiago Metropolitan",
+    "iso3166_2": "CL-RM",
+    "country": "Chile",
+    "iso3166_1": "CL",
+    "latitude": -33.4489,
+    "longitude": -70.6693
+  },
+  {
+    "city": "Valdivia",
+    "state_province": "Los Ríos",
+    "iso3166_2": "CL-LR",
+    "country": "Chile",
+    "iso3166_1": "CL",
+    "latitude": -39.8142,
+    "longitude": -73.2459
+  },
+  {
+    "city": "Lima",
+    "state_province": "Lima",
+    "iso3166_2": "PE-LMA",
+    "country": "Peru",
+    "iso3166_1": "PE",
+    "latitude": -12.0464,
+    "longitude": -77.0428
+  },
+  {
+    "city": "Tokyo",
+    "state_province": "Tokyo",
+    "iso3166_2": "JP-13",
+    "country": "Japan",
+    "iso3166_1": "JP",
+    "latitude": 35.6762,
+    "longitude": 139.6503
+  },
+  {
+    "city": "Osaka",
+    "state_province": "Osaka",
+    "iso3166_2": "JP-27",
+    "country": "Japan",
+    "iso3166_1": "JP",
+    "latitude": 34.6937,
+    "longitude": 135.5023
+  },
+  {
+    "city": "Kyoto",
+    "state_province": "Kyoto",
+    "iso3166_2": "JP-26",
+    "country": "Japan",
+    "iso3166_1": "JP",
+    "latitude": 35.0116,
+    "longitude": 135.7681
+  },
+  {
+    "city": "Sapporo",
+    "state_province": "Hokkaido",
+    "iso3166_2": "JP-01",
+    "country": "Japan",
+    "iso3166_1": "JP",
+    "latitude": 43.0618,
+    "longitude": 141.3545
+  },
+  {
+    "city": "Seoul",
+    "state_province": "Seoul",
+    "iso3166_2": "KR-11",
+    "country": "South Korea",
+    "iso3166_1": "KR",
+    "latitude": 37.5665,
+    "longitude": 126.978
+  },
+  {
+    "city": "Busan",
+    "state_province": "Busan",
+    "iso3166_2": "KR-26",
+    "country": "South Korea",
+    "iso3166_1": "KR",
+    "latitude": 35.1796,
+    "longitude": 129.0756
+  },
+  {
+    "city": "Ho Chi Minh City",
+    "state_province": "Ho Chi Minh",
+    "iso3166_2": "VN-SG",
+    "country": "Vietnam",
+    "iso3166_1": "VN",
+    "latitude": 10.8231,
+    "longitude": 106.6297
+  },
+  {
+    "city": "Hanoi",
+    "state_province": "Hanoi",
+    "iso3166_2": "VN-HN",
+    "country": "Vietnam",
+    "iso3166_1": "VN",
+    "latitude": 21.0285,
+    "longitude": 105.8542
+  },
+  {
+    "city": "Da Nang",
+    "state_province": "Da Nang",
+    "iso3166_2": "VN-DN",
+    "country": "Vietnam",
+    "iso3166_1": "VN",
+    "latitude": 16.0544,
+    "longitude": 108.2022
+  },
+  {
+    "city": "Bangkok",
+    "state_province": "Bangkok",
+    "iso3166_2": "TH-10",
+    "country": "Thailand",
+    "iso3166_1": "TH",
+    "latitude": 13.7563,
+    "longitude": 100.5018
+  },
+  {
+    "city": "Taipei",
+    "state_province": "Taipei",
+    "iso3166_2": "TW-TPE",
+    "country": "Taiwan",
+    "iso3166_1": "TW",
+    "latitude": 25.033,
+    "longitude": 121.5654
+  },
+  {
+    "city": "Beijing",
+    "state_province": "Beijing",
+    "iso3166_2": "CN-BJ",
+    "country": "China",
+    "iso3166_1": "CN",
+    "latitude": 39.9042,
+    "longitude": 116.4074
+  },
+  {
+    "city": "Shanghai",
+    "state_province": "Shanghai",
+    "iso3166_2": "CN-SH",
+    "country": "China",
+    "iso3166_1": "CN",
+    "latitude": 31.2304,
+    "longitude": 121.4737
+  },
+  {
+    "city": "Bengaluru",
+    "state_province": "Karnataka",
+    "iso3166_2": "IN-KA",
+    "country": "India",
+    "iso3166_1": "IN",
+    "latitude": 12.9716,
+    "longitude": 77.5946
+  },
+  {
+    "city": "Singapore",
+    "state_province": "Central Singapore",
+    "iso3166_2": "SG-01",
+    "country": "Singapore",
+    "iso3166_1": "SG",
+    "latitude": 1.3521,
+    "longitude": 103.8198
+  },
+  {
+    "city": "Melbourne",
+    "state_province": "Victoria",
+    "iso3166_2": "AU-VIC",
+    "country": "Australia",
+    "iso3166_1": "AU",
+    "latitude": -37.8136,
+    "longitude": 144.9631
+  },
+  {
+    "city": "Sydney",
+    "state_province": "New South Wales",
+    "iso3166_2": "AU-NSW",
+    "country": "Australia",
+    "iso3166_1": "AU",
+    "latitude": -33.8688,
+    "longitude": 151.2093
+  },
+  {
+    "city": "Brisbane",
+    "state_province": "Queensland",
+    "iso3166_2": "AU-QLD",
+    "country": "Australia",
+    "iso3166_1": "AU",
+    "latitude": -27.4705,
+    "longitude": 153.026
+  },
+  {
+    "city": "Adelaide",
+    "state_province": "South Australia",
+    "iso3166_2": "AU-SA",
+    "country": "Australia",
+    "iso3166_1": "AU",
+    "latitude": -34.9285,
+    "longitude": 138.6007
+  },
+  {
+    "city": "Perth",
+    "state_province": "Western Australia",
+    "iso3166_2": "AU-WA",
+    "country": "Australia",
+    "iso3166_1": "AU",
+    "latitude": -31.9505,
+    "longitude": 115.8605
+  },
+  {
+    "city": "Hobart",
+    "state_province": "Tasmania",
+    "iso3166_2": "AU-TAS",
+    "country": "Australia",
+    "iso3166_1": "AU",
+    "latitude": -42.8821,
+    "longitude": 147.3272
+  },
+  {
+    "city": "Wellington",
+    "state_province": "Wellington",
+    "iso3166_2": "NZ-WGN",
+    "country": "New Zealand",
+    "iso3166_1": "NZ",
+    "latitude": -41.2865,
+    "longitude": 174.7762
+  },
+  {
+    "city": "Auckland",
+    "state_province": "Auckland",
+    "iso3166_2": "NZ-AUK",
+    "country": "New Zealand",
+    "iso3166_1": "NZ",
+    "latitude": -36.8485,
+    "longitude": 174.7633
+  },
+  {
+    "city": "Christchurch",
+    "state_province": "Canterbury",
+    "iso3166_2": "NZ-CAN",
+    "country": "New Zealand",
+    "iso3166_1": "NZ",
+    "latitude": -43.532,
+    "longitude": 172.6306
+  },
+  {
+    "city": "Nelson",
+    "state_province": "Nelson",
+    "iso3166_2": "NZ-NSN",
+    "country": "New Zealand",
+    "iso3166_1": "NZ",
+    "latitude": -41.2706,
+    "longitude": 173.284
+  },
+  {
+    "city": "Munich",
+    "state_province": "Bavaria",
+    "iso3166_2": "DE-BY",
+    "country": "Germany",
+    "iso3166_1": "DE",
+    "latitude": 48.1351,
+    "longitude": 11.582
+  },
+  {
+    "city": "Berlin",
+    "state_province": "Berlin",
+    "iso3166_2": "DE-BE",
+    "country": "Germany",
+    "iso3166_1": "DE",
+    "latitude": 52.52,
+    "longitude": 13.405
+  },
+  {
+    "city": "Cologne",
+    "state_province": "North Rhine-Westphalia",
+    "iso3166_2": "DE-NW",
+    "country": "Germany",
+    "iso3166_1": "DE",
+    "latitude": 50.9375,
+    "longitude": 6.9603
+  },
+  {
+    "city": "Bamberg",
+    "state_province": "Bavaria",
+    "iso3166_2": "DE-BY",
+    "country": "Germany",
+    "iso3166_1": "DE",
+    "latitude": 49.8916,
+    "longitude": 10.8916
+  },
+  {
+    "city": "Brussels",
+    "state_province": "Brussels-Capital",
+    "iso3166_2": "BE-BRU",
+    "country": "Belgium",
+    "iso3166_1": "BE",
+    "latitude": 50.8503,
+    "longitude": 4.3517
+  },
+  {
+    "city": "Antwerp",
+    "state_province": "Flanders",
+    "iso3166_2": "BE-VLG",
+    "country": "Belgium",
+    "iso3166_1": "BE",
+    "latitude": 51.2194,
+    "longitude": 4.4025
+  },
+  {
+    "city": "Bruges",
+    "state_province": "Flanders",
+    "iso3166_2": "BE-VLG",
+    "country": "Belgium",
+    "iso3166_1": "BE",
+    "latitude": 51.2093,
+    "longitude": 3.2247
+  },
+  {
+    "city": "London",
+    "state_province": "England",
+    "iso3166_2": "GB-ENG",
+    "country": "United Kingdom",
+    "iso3166_1": "GB",
+    "latitude": 51.5074,
+    "longitude": -0.1278
+  },
+  {
+    "city": "Bristol",
+    "state_province": "England",
+    "iso3166_2": "GB-ENG",
+    "country": "United Kingdom",
+    "iso3166_1": "GB",
+    "latitude": 51.4545,
+    "longitude": -2.5879
+  },
+  {
+    "city": "Edinburgh",
+    "state_province": "Scotland",
+    "iso3166_2": "GB-SCT",
+    "country": "United Kingdom",
+    "iso3166_1": "GB",
+    "latitude": 55.9533,
+    "longitude": -3.1883
+  },
+  {
+    "city": "Glasgow",
+    "state_province": "Scotland",
+    "iso3166_2": "GB-SCT",
+    "country": "United Kingdom",
+    "iso3166_1": "GB",
+    "latitude": 55.8642,
+    "longitude": -4.2518
+  },
+  {
+    "city": "Prague",
+    "state_province": "Prague",
+    "iso3166_2": "CZ-10",
+    "country": "Czechia",
+    "iso3166_1": "CZ",
+    "latitude": 50.0755,
+    "longitude": 14.4378
+  },
+  {
+    "city": "Pilsen",
+    "state_province": "Plzeň",
+    "iso3166_2": "CZ-32",
+    "country": "Czechia",
+    "iso3166_1": "CZ",
+    "latitude": 49.7384,
+    "longitude": 13.3736
+  },
+  {
+    "city": "Amsterdam",
+    "state_province": "North Holland",
+    "iso3166_2": "NL-NH",
+    "country": "Netherlands",
+    "iso3166_1": "NL",
+    "latitude": 52.3676,
+    "longitude": 4.9041
+  },
+  {
+    "city": "Copenhagen",
+    "state_province": "Capital Region",
+    "iso3166_2": "DK-84",
+    "country": "Denmark",
+    "iso3166_1": "DK",
+    "latitude": 55.6761,
+    "longitude": 12.5683
+  },
+  {
+    "city": "Warsaw",
+    "state_province": "Masovian",
+    "iso3166_2": "PL-MZ",
+    "country": "Poland",
+    "iso3166_1": "PL",
+    "latitude": 52.2297,
+    "longitude": 21.0122
+  },
+  {
+    "city": "Krakow",
+    "state_province": "Lesser Poland",
+    "iso3166_2": "PL-MA",
+    "country": "Poland",
+    "iso3166_1": "PL",
+    "latitude": 50.0647,
+    "longitude": 19.945
+  },
+  {
+    "city": "Rome",
+    "state_province": "Lazio",
+    "iso3166_2": "IT-62",
+    "country": "Italy",
+    "iso3166_1": "IT",
+    "latitude": 41.9028,
+    "longitude": 12.4964
+  },
+  {
+    "city": "Milan",
+    "state_province": "Lombardy",
+    "iso3166_2": "IT-25",
+    "country": "Italy",
+    "iso3166_1": "IT",
+    "latitude": 45.4642,
+    "longitude": 9.19
+  },
+  {
+    "city": "Barcelona",
+    "state_province": "Catalonia",
+    "iso3166_2": "ES-CT",
+    "country": "Spain",
+    "iso3166_1": "ES",
+    "latitude": 41.3851,
+    "longitude": 2.1734
+  },
+  {
+    "city": "Madrid",
+    "state_province": "Madrid",
+    "iso3166_2": "ES-MD",
+    "country": "Spain",
+    "iso3166_1": "ES",
+    "latitude": 40.4168,
+    "longitude": -3.7038
+  },
+  {
+    "city": "Paris",
+    "state_province": "Île-de-France",
+    "iso3166_2": "FR-IDF",
+    "country": "France",
+    "iso3166_1": "FR",
+    "latitude": 48.8566,
+    "longitude": 2.3522
+  },
+  {
+    "city": "Lyon",
+    "state_province": "Auvergne-Rhône-Alpes",
+    "iso3166_2": "FR-ARA",
+    "country": "France",
+    "iso3166_1": "FR",
+    "latitude": 45.764,
+    "longitude": 4.8357
+  },
+  {
+    "city": "Stockholm",
+    "state_province": "Stockholm",
+    "iso3166_2": "SE-AB",
+    "country": "Sweden",
+    "iso3166_1": "SE",
+    "latitude": 59.3293,
+    "longitude": 18.0686
+  },
+  {
+    "city": "Gothenburg",
+    "state_province": "Västra Götaland",
+    "iso3166_2": "SE-O",
+    "country": "Sweden",
+    "iso3166_1": "SE",
+    "latitude": 57.7089,
+    "longitude": 11.9746
+  },
+  {
+    "city": "Oslo",
+    "state_province": "Oslo",
+    "iso3166_2": "NO-03",
+    "country": "Norway",
+    "iso3166_1": "NO",
+    "latitude": 59.9139,
+    "longitude": 10.7522
+  },
+  {
+    "city": "Dublin",
+    "state_province": "Leinster",
+    "iso3166_2": "IE-L",
+    "country": "Ireland",
+    "iso3166_1": "IE",
+    "latitude": 53.3498,
+    "longitude": -6.2603
+  },
+  {
+    "city": "Vienna",
+    "state_province": "Vienna",
+    "iso3166_2": "AT-9",
+    "country": "Austria",
+    "iso3166_1": "AT",
+    "latitude": 48.2082,
+    "longitude": 16.3738
+  },
+  {
+    "city": "Zurich",
+    "state_province": "Zurich",
+    "iso3166_2": "CH-ZH",
+    "country": "Switzerland",
+    "iso3166_1": "CH",
+    "latitude": 47.3769,
+    "longitude": 8.5417
+  },
+  {
+    "city": "Tallinn",
+    "state_province": "Harju",
+    "iso3166_2": "EE-37",
+    "country": "Estonia",
+    "iso3166_1": "EE",
+    "latitude": 59.437,
+    "longitude": 24.7536
+  },
+  {
+    "city": "Denver",
+    "state_province": "Colorado",
+    "iso3166_2": "US-CO",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 39.7392,
+    "longitude": -104.9903
+  },
+  {
+    "city": "Portland",
+    "state_province": "Oregon",
+    "iso3166_2": "US-OR",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 45.5152,
+    "longitude": -122.6784
+  },
+  {
+    "city": "San Diego",
+    "state_province": "California",
+    "iso3166_2": "US-CA",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 32.7157,
+    "longitude": -117.1611
+  },
+  {
+    "city": "Asheville",
+    "state_province": "North Carolina",
+    "iso3166_2": "US-NC",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 35.5951,
+    "longitude": -82.5515
+  },
+  {
+    "city": "Grand Rapids",
+    "state_province": "Michigan",
+    "iso3166_2": "US-MI",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 42.9634,
+    "longitude": -85.6681
+  },
+  {
+    "city": "Chicago",
+    "state_province": "Illinois",
+    "iso3166_2": "US-IL",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 41.8781,
+    "longitude": -87.6298
+  },
+  {
+    "city": "Seattle",
+    "state_province": "Washington",
+    "iso3166_2": "US-WA",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 47.6062,
+    "longitude": -122.3321
+  },
+  {
+    "city": "Austin",
+    "state_province": "Texas",
+    "iso3166_2": "US-TX",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 30.2672,
+    "longitude": -97.7431
+  },
+  {
+    "city": "Boston",
+    "state_province": "Massachusetts",
+    "iso3166_2": "US-MA",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 42.3601,
+    "longitude": -71.0589
+  },
+  {
+    "city": "Philadelphia",
+    "state_province": "Pennsylvania",
+    "iso3166_2": "US-PA",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 39.9526,
+    "longitude": -75.1652
+  },
+  {
+    "city": "Brooklyn",
+    "state_province": "New York",
+    "iso3166_2": "US-NY",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 40.6782,
+    "longitude": -73.9442
+  },
+  {
+    "city": "Milwaukee",
+    "state_province": "Wisconsin",
+    "iso3166_2": "US-WI",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 43.0389,
+    "longitude": -87.9065
+  },
+  {
+    "city": "Richmond",
+    "state_province": "Virginia",
+    "iso3166_2": "US-VA",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 37.5407,
+    "longitude": -77.436
+  },
+  {
+    "city": "Cincinnati",
+    "state_province": "Ohio",
+    "iso3166_2": "US-OH",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 39.1031,
+    "longitude": -84.512
+  },
+  {
+    "city": "St. Louis",
+    "state_province": "Missouri",
+    "iso3166_2": "US-MO",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 38.627,
+    "longitude": -90.1994
+  },
+  {
+    "city": "Tampa",
+    "state_province": "Florida",
+    "iso3166_2": "US-FL",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 27.9506,
+    "longitude": -82.4572
+  },
+  {
+    "city": "Minneapolis",
+    "state_province": "Minnesota",
+    "iso3166_2": "US-MN",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 44.9778,
+    "longitude": -93.265
+  },
+  {
+    "city": "Burlington",
+    "state_province": "Vermont",
+    "iso3166_2": "US-VT",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 44.4759,
+    "longitude": -73.2121
+  },
+  {
+    "city": "Portland",
+    "state_province": "Maine",
+    "iso3166_2": "US-ME",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 43.6591,
+    "longitude": -70.2568
+  },
+  {
+    "city": "Atlanta",
+    "state_province": "Georgia",
+    "iso3166_2": "US-GA",
+    "country": "United States",
+    "iso3166_1": "US",
+    "latitude": 33.749,
+    "longitude": -84.388
+  },
+  {
+    "city": "Toronto",
+    "state_province": "Ontario",
+    "iso3166_2": "CA-ON",
+    "country": "Canada",
+    "iso3166_1": "CA",
+    "latitude": 43.651,
+    "longitude": -79.347
+  },
+  {
+    "city": "Vancouver",
+    "state_province": "British Columbia",
+    "iso3166_2": "CA-BC",
+    "country": "Canada",
+    "iso3166_1": "CA",
+    "latitude": 49.2827,
+    "longitude": -123.1207
+  },
+  {
+    "city": "Montreal",
+    "state_province": "Quebec",
+    "iso3166_2": "CA-QC",
+    "country": "Canada",
+    "iso3166_1": "CA",
+    "latitude": 45.5017,
+    "longitude": -73.5673
+  },
+  {
+    "city": "Calgary",
+    "state_province": "Alberta",
+    "iso3166_2": "CA-AB",
+    "country": "Canada",
+    "iso3166_1": "CA",
+    "latitude": 51.0447,
+    "longitude": -114.0719
+  },
+  {
+    "city": "Halifax",
+    "state_province": "Nova Scotia",
+    "iso3166_2": "CA-NS",
+    "country": "Canada",
+    "iso3166_1": "CA",
+    "latitude": 44.6488,
+    "longitude": -63.5752
+  },
+  {
+    "city": "Mexico City",
+    "state_province": "Mexico City",
+    "iso3166_2": "MX-CMX",
+    "country": "Mexico",
+    "iso3166_1": "MX",
+    "latitude": 19.4326,
+    "longitude": -99.1332
+  },
+  {
+    "city": "Tijuana",
+    "state_province": "Baja California",
+    "iso3166_2": "MX-BCN",
+    "country": "Mexico",
+    "iso3166_1": "MX",
+    "latitude": 32.5149,
+    "longitude": -117.0382
+  },
+  {
+    "city": "Monterrey",
+    "state_province": "Nuevo León",
+    "iso3166_2": "MX-NLE",
+    "country": "Mexico",
+    "iso3166_1": "MX",
+    "latitude": 25.6866,
+    "longitude": -100.3161
+  },
+  {
+    "city": "Guadalajara",
+    "state_province": "Jalisco",
+    "iso3166_2": "MX-JAL",
+    "country": "Mexico",
+    "iso3166_1": "MX",
+    "latitude": 20.6597,
+    "longitude": -103.3496
+  },
+  {
+    "city": "Ensenada",
+    "state_province": "Baja California",
+    "iso3166_2": "MX-BCN",
+    "country": "Mexico",
+    "iso3166_1": "MX",
+    "latitude": 31.8667,
+    "longitude": -116.5964
+  }
+]

pipeline/prompts/system.md

@@ -0,0 +1,94 @@
+<|think|>
+Think through the brewery details internally before answering.
+Return only one raw JSON object as the final answer, with exactly two keys: "name" and "description".
+No markdown, code fences, preamble, or extra keys.
+
+# FULL SYSTEM PROMPT
+
+You are an expert brewery copywriter, an architectural observer, and a master of zymurgy.
+
+Your main goal is to come up with a fake, contextually accurate name and a matching description for a craft brewery located in a specific city. You need to base this on the exact geographic and cultural info provided. You also need to seamlessly blend historical background, cultural details, and highly specialized brewing methods to create a realistic and interesting story.
+
+You will receive the inputs like this:
+
+## CITY:
+
+$$City Name$$
+
+## COUNTRY:
+
+$$Country Name$$
+
+## CONTEXT:
+
+$$Information about local beer culture, history, or geography$$
+
+## CRITICAL OUTPUT FORMAT (READ CAREFULLY):
+
+You have to return a reasoning block first, then ONLY raw, perfectly valid JSON as the final answer. Any mistake with the JSON means the data pipeline breaks.
+
+ABSOLUTELY NO MARKDOWN FORMATTING. Do NOT wrap your response in json or ``` blocks.
+
+NO PREAMBLE OR POSTSCRIPT outside the reasoning block. Do not say "Here is the JSON" or "Enjoy!".
+
+The JSON must contain exactly two keys ("name" and "description"); do not rename or add any other keys.
+
+ESCAPE ALL QUOTES inside the description using ", or use single quotes (' ') instead. Escaping quotes perfectly is super important to avoid errors later.
+
+DO NOT use actual line breaks (\n) inside the string. Keep the description as one continuous string.
+
+Expected JSON format:
+{ "name": "Fictional Brewery Name", "description": "The description goes here." }
+
+## CONTENT RULES AND CONSTRAINTS:
+
+### THE HOOK:
+
+The first sentence must be an immersive, sensory environmental hook. It needs to clearly establish the weather, smells, or sounds typical of that city. Do not start by using the brewery's name or standard welcoming phrases.
+
+### GEOGRAPHIC & CULTURAL ANCHOR:
+
+The story must be deeply tied to the provided geographic and cultural info. It should mix historical brewing facts with the gritty reality of modern craft brewing, making sure it fits the local culture perfectly.
+
+### TECHNICAL BREWING DETAIL (VARY THIS!):
+
+You must include one highly specialized technical brewing detail. To avoid sounding repetitive, make sure this varies a lot. Some examples: using local wild yeast (like spontaneous Brettanomyces), adjusting the water profile (like Burtonization), specific mashing techniques, or using local barrels for aging. Don't use basic concepts like generic mash temperatures.
+
+### ARCHITECTURAL DETAIL (VARY THIS!):
+
+You must include one specific architectural or environmental detail, highlighting the building's physical wear, structure, or history. Examples include rusty steel beams, weird acoustics from an old factory, decaying brickwork, or worn-out local infrastructure. Avoid overused industry clichés like repurposed dairy equipment or glycol chillers.
+
+### THE INVITATION:
+
+The last sentence must be an atmospheric invitation to hang out in the space, kept totally objective. Good examples include suggesting where to stand, like "Observation may commence near the foundational supports," or "Positioning adjacent to the exterior loading apparatus is suggested." Avoid regular sayings like telling people to grab a seat or ask the bartender.
+
+### THE BLOCKLIST (FORBIDDEN CONCEPTS):
+
+You absolutely cannot use the following words and phrases because they are overused and too casual. Make sure your final output doesn't have any of these:
+
+- "hidden gem"
+- "passion"
+- "authentic"
+- "repurposed dairy tank"
+- "repurposed industrial vat"
+- "concrete eggs"
+- "glycol chiller"
+- "mash temperature"
+- "grab a stool"
+- "ask the bartender"
+
+### VOICE & PERSPECTIVE:
+
+The description must be written strictly in the third-person objective. You need to act like a detached architectural observer looking at the space and the brewing process from the outside. Do not use first-person or second-person pronouns, keeping an atmosphere of academic distance and professionalism.
+
+## EXAMPLE:
+
+Input:
+CITY: Sapporo
+COUNTRY: Japan
+CONTEXT: Sapporo is the capital of Hokkaido, Japan's northernmost main island, with a subarctic climate: winters are severe and protracted, with the city averaging over 6 metres of cumulative snowfall per season...
+
+$$Truncated for brevity, but assumes full context provided$$
+
+Output:
+{ "name": "Tokachi Grain & Ferment", "description": "By February, the powder snow blowing off the Teine range buries the bicycle racks on Susukino's side streets to the crossbar. Sapporo has been in the business of serious lager since 1876, but Tokachi Grain & Ferment isn't interested in replicating the macro-brew legacy. Instead, they source base malt exclusively from Obihiro-area farms and run the entire grain bill through a rigorous Burtonization protocol, driving up calcium sulfate levels to pull a sharp, mineral snap into the finish. The taproom is carved from a former Meiji-era goods shed, where a single run of oxidized copper piping bisects the ceiling and weeps green verdigris onto the communal timber table below. Observation may commence beneath the deteriorating copper, where the pale ale may be procured while the surrounding acoustics are analyzed." }

pipeline/src/biergarten_data_generator/biergarten_data_generator.cpp

@@ -0,0 +1,14 @@
+/**
+ * @file biergarten_data_generator/biergarten_data_generator.cpp
+ * @brief BiergartenDataGenerator constructor implementation.
+ */
+
+#include "biergarten_data_generator.h"
+
+#include <utility>
+
+BiergartenDataGenerator::BiergartenDataGenerator(
+    std::shared_ptr<IEnrichmentService> context_service,
+    std::unique_ptr<DataGenerator> generator)
+    : context_service_(std::move(context_service)),
+      generator_(std::move(generator)) {}

pipeline/src/biergarten_data_generator/generate_breweries.cpp

@@ -0,0 +1,41 @@
+/**
+ * @file biergarten_data_generator/generate_breweries.cpp
+ * @brief BiergartenDataGenerator::GenerateBreweries() implementation.
+ */
+
+#include <spdlog/spdlog.h>
+
+#include "biergarten_data_generator.h"
+
+void BiergartenDataGenerator::GenerateBreweries(
+    const std::vector<EnrichedCity>& cities) {
+   spdlog::info("\n=== SAMPLE BREWERY GENERATION ===");
+   generated_breweries_.clear();
+
+   size_t skipped_count = 0;
+
+   for (const auto& enriched_city : cities) {
+      try {
+         auto brewery = generator_->GenerateBrewery(
+             BreweryLocation{enriched_city.location.city,
+                             enriched_city.location.country},
+             enriched_city.region_context);
+         generated_breweries_.push_back(GeneratedBrewery{
+             .location = enriched_city.location, .brewery = brewery});
+      } catch (const std::exception& e) {
+         ++skipped_count;
+         spdlog::warn(
+             "[Pipeline] Skipping city '{}' ({}): brewery generation failed: "
+             "{}",
+             enriched_city.location.city, enriched_city.location.country,
+             e.what());
+      }
+   }
+
+   if (skipped_count > 0) {
+      spdlog::warn(
+          "[Pipeline] Skipped {} city/cities due to generation "
+          "errors",
+          skipped_count);
+   }
+}

pipeline/src/biergarten_data_generator/log_results.cpp

@@ -0,0 +1,23 @@
+/**
+ * @file biergarten_data_generator/log_results.cpp
+ * @brief BiergartenDataGenerator::LogResults() implementation.
+ */
+
+#include <spdlog/spdlog.h>
+
+#include "biergarten_data_generator.h"
+
+void BiergartenDataGenerator::LogResults() const {
+   spdlog::info("\n=== GENERATED DATA DUMP ===");
+   size_t index = 1;
+   for (const auto& [location, brewery] : generated_breweries_) {
+      spdlog::info(
+          "{}. city=\"{}\" country=\"{}\" state=\"{}\" "
+          "iso3166_2={} lat={} lon={}",
+          index, location.city, location.country, location.state_province,
+          location.iso3166_2, location.latitude, location.longitude);
+      spdlog::info("   brewery_name=\"{}\"", brewery.name);
+      spdlog::info("   brewery_description=\"{}\"", brewery.description);
+      ++index;
+   }
+}

pipeline/src/biergarten_data_generator/query_cities_with_countries.cpp

@@ -0,0 +1,40 @@
+/**
+ * @file biergarten_data_generator/query_cities_with_countries.cpp
+ * @brief BiergartenDataGenerator::QueryCitiesWithCountries() implementation.
+ */
+
+#include <spdlog/spdlog.h>
+
+#include <algorithm>
+#include <filesystem>
+#include <iterator>
+#include <random>
+
+#include "biergarten_data_generator.h"
+#include "json_handling/json_loader.h"
+
+static constexpr unsigned int brewery_amount = 4;
+
+std::vector<Location> BiergartenDataGenerator::QueryCitiesWithCountries() {
+   spdlog::info("\n=== GEOGRAPHIC DATA OVERVIEW ===");
+
+   const std::filesystem::path locations_path = "locations.json";
+
+   auto all_locations = JsonLoader::LoadLocations(locations_path.string());
+   spdlog::info("  Locations available: {}", all_locations.size());
+
+   const size_t sample_count =
+       std::min<size_t>(brewery_amount, all_locations.size());
+   const auto sample_count_signed =
+       static_cast<std::iter_difference_t<decltype(all_locations.cbegin())>>(
+           sample_count);
+   std::vector<Location> sampled_locations;
+   sampled_locations.reserve(sample_count);
+
+   std::random_device random_generator;
+   std::ranges::sample(all_locations, std::back_inserter(sampled_locations),
+                       sample_count_signed, random_generator);
+
+   spdlog::info("  Sampled locations: {}", sampled_locations.size());
+   return sampled_locations;
+}

pipeline/src/biergarten_data_generator/run.cpp

@@ -0,0 +1,47 @@
+/**
+ * @file biergarten_data_generator/run.cpp
+ * @brief BiergartenDataGenerator::Run() implementation.
+ */
+
+#include <spdlog/spdlog.h>
+
+#include "biergarten_data_generator.h"
+
+bool BiergartenDataGenerator::Run() {
+   try {
+      const std::vector<Location> cities = QueryCitiesWithCountries();
+      std::vector<EnrichedCity> enriched;
+      enriched.reserve(cities.size());
+
+      size_t skipped_count = 0;
+      for (const auto& city : cities) {
+         try {
+            const std::string region_context =
+                context_service_->GetLocationContext(city);
+            spdlog::info("[Pipeline] Context for '{}' ({}) gathered:\n{}",
+                         city.city, city.country, region_context);
+
+            enriched.push_back(EnrichedCity{.location = city,
+                                            .region_context = region_context});
+         } catch (const std::exception& exception) {
+            ++skipped_count;
+            spdlog::warn(
+                "[Pipeline] Skipping city '{}' ({}): context lookup failed: {}",
+                city.city, city.country, exception.what());
+         }
+      }
+
+      if (skipped_count > 0) {
+         spdlog::warn(
+             "[Pipeline] Skipped {} city/cities due to context lookup errors",
+             skipped_count);
+      }
+
+      this->GenerateBreweries(enriched);
+      this->LogResults();
+      return true;
+   } catch (const std::exception& e) {
+      spdlog::error("Pipeline execution failed with error: {}", e.what());
+      return false;
+   }
+}

pipeline/src/data_generation/llama/generate_brewery.cpp

@@ -0,0 +1,160 @@
+/**
+ * @file data_generation/llama/generate_brewery.cpp
+ * @brief Builds brewery prompts with regional context, performs retry-based
+ * inference, and validates structured JSON output for brewery records.
+ */
+
+#include <spdlog/spdlog.h>
+
+#include <array>
+#include <stdexcept>
+#include <string>
+
+#include "data_generation/llama_generator.h"
+#include "data_generation/llama_generator_helpers.h"
+
+namespace {
+
+std::string ExtractFinalJsonPayload(std::string raw_response) {
+   auto trim = [](std::string_view text) -> std::string_view {
+      const std::size_t first = text.find_first_not_of(" \t\n\r");
+      if (first == std::string_view::npos) {
+         return {};
+      }
+
+      const std::size_t last = text.find_last_not_of(" \t\n\r");
+      return text.substr(first, last - first + 1);
+   };
+
+   static const std::array<std::string_view, 6> separator_tokens = {
+       "<|think|>", "<think|>",   "<|turn|>",
+       "<turn|>",   "<channel|>", "<|channel|>"};
+
+   std::size_t separator_pos = std::string::npos;
+   std::size_t separator_length = 0;
+   for (const std::string_view token : separator_tokens) {
+      const std::size_t candidate_pos = raw_response.rfind(token);
+      if (candidate_pos != std::string::npos &&
+          (separator_pos == std::string::npos ||
+           candidate_pos > separator_pos)) {
+         separator_pos = candidate_pos;
+         separator_length = token.size();
+      }
+   }
+
+   if (separator_pos != std::string::npos) {
+      raw_response.erase(0, separator_pos + separator_length);
+   }
+
+   const std::string_view trimmed = trim(raw_response);
+   std::string json_candidate =
+       ExtractLastJsonObjectPublic(std::string(trimmed));
+   if (!json_candidate.empty()) {
+      return ExtractLastJsonObjectPublic(std::string(trimmed));
+   }
+
+   return std::string(trimmed);
+}
+
+}  // namespace
+
+BreweryResult LlamaGenerator::GenerateBrewery(
+    const BreweryLocation& location, const std::string& region_context) {
+   /**
+    * Preprocess and truncate region context to manageable size
+    */
+   const std::string safe_region_context =
+       PrepareRegionContextPublic(region_context);
+
+   /**
+    * Load brewery system prompt from file
+    * Falls back to minimal inline prompt if file not found
+    */
+   const std::string system_prompt =
+       LoadBrewerySystemPrompt("prompts/system.md");
+
+   /**
+    * User prompt: provides geographic context to guide generation towards
+    * culturally appropriate and locally-inspired brewery attributes
+    */
+   std::string prompt =
+       "Write a brewery name and place-specific long description for a craft "
+       "brewery in ";
+   prompt.append(location.city_name);
+   if (!location.country_name.empty()) {
+      prompt.append(", ");
+      prompt.append(location.country_name);
+   }
+   if (safe_region_context.empty()) {
+      prompt.append(".");
+   } else {
+      prompt.append(". Regional context: ");
+      prompt.append(safe_region_context);
+   }
+
+   /**
+    * Store location context for retry prompts (without repeating full context)
+    */
+   std::string retry_location = "Location: ";
+   retry_location.append(location.city_name);
+   if (!location.country_name.empty()) {
+      retry_location.append(", ");
+      retry_location.append(location.country_name);
+   }
+
+   /**
+    * RETRY LOOP with validation and error correction
+    * Attempts to generate valid brewery data up to 3 times, with feedback-based
+    * refinement
+    */
+   const int max_attempts = 3;
+   std::string raw;
+   std::string last_error;
+
+   // Limit output length to keep it concise and focused
+   constexpr int max_tokens = 1052;
+   for (int attempt = 0; attempt < max_attempts; ++attempt) {
+      // Generate brewery data from LLM
+      raw = Infer(system_prompt, prompt, max_tokens);
+      spdlog::debug("LlamaGenerator: raw output (attempt {}): {}", attempt + 1,
+                    raw);
+
+      // Validate output: parse JSON and check required fields
+
+      std::string name;
+      std::string description;
+      const std::string json_only = ExtractFinalJsonPayload(raw);
+      const std::string validation_error =
+          ValidateBreweryJsonPublic(json_only, name, description);
+      if (validation_error.empty()) {
+         // Success: return parsed brewery data
+         return {std::move(name), std::move(description)};
+      }
+
+      // Validation failed: log error and prepare corrective feedback
+
+      last_error = validation_error;
+      spdlog::warn("LlamaGenerator: malformed brewery JSON (attempt {}): {}",
+                   attempt + 1, validation_error);
+
+      // Update prompt with error details to guide LLM toward correct output.
+      // For retries, use a compact prompt format to avoid exceeding token
+      // limits.
+      prompt =
+          "Your previous response was invalid. Error: " + validation_error +
+          "\nReturn ONLY valid JSON with exactly these keys: "
+          "{\"name\": \"<brewery name>\", "
+          "\"description\": \"<single-paragraph description>\"}."
+          "\nDo not include markdown, comments, extra keys, or literal "
+          "placeholder values.";
+      prompt += "\n\n";
+      prompt += retry_location;
+   }
+
+   // All retry attempts exhausted: log failure and throw exception
+   spdlog::error(
+       "LlamaGenerator: malformed brewery response after {} attempts: "
+       "{}",
+       max_attempts, last_error.empty() ? raw : last_error);
+   throw std::runtime_error("LlamaGenerator: malformed brewery response");
+}

pipeline/src/data_generation/llama/generate_user.cpp

@@ -0,0 +1,100 @@
+/**
+ * @file data_generation/llama/generate_user.cpp
+ * @brief Generates locale-aware user profiles with strict two-line formatting,
+ * retry handling, and output sanitization for downstream parsing.
+ */
+
+#include <spdlog/spdlog.h>
+
+#include <algorithm>
+#include <stdexcept>
+#include <string>
+
+#include "data_generation/llama_generator.h"
+#include "data_generation/llama_generator_helpers.h"
+
+UserResult LlamaGenerator::GenerateUser(const std::string& locale) {
+   /**
+    * System prompt: specifies exact output format to minimize parsing errors
+    * Constraints: 2-line output, username format, bio length bounds
+    */
+   const std::string system_prompt =
+       "You generate plausible social media profiles for craft beer "
+       "enthusiasts. "
+       "Respond with exactly two lines: "
+       "the first line is a username (lowercase, no spaces, 8-20 characters), "
+       "the second line is a one-sentence bio (20-40 words). "
+       "The profile should feel consistent with the locale. "
+       "No preamble, no labels.";
+
+   /**
+    * User prompt: locale parameter guides cultural appropriateness of generated
+    * profiles
+    */
+   std::string prompt =
+       "Generate a craft beer enthusiast profile. Locale: " + locale;
+
+   /**
+    * RETRY LOOP with format validation
+    * Attempts up to 3 times to generate valid user profile with correct format
+    */
+   const int max_attempts = 3;
+   std::string raw;
+   for (int attempt = 0; attempt < max_attempts; ++attempt) {
+      /**
+       * Generate user profile (max 128 tokens - should fit 2 lines easily)
+       */
+      raw = Infer(system_prompt, prompt, 128);
+      spdlog::debug("LlamaGenerator (user): raw output (attempt {}): {}",
+                    attempt + 1, raw);
+
+      try {
+         /**
+          * Parse two-line response: first line = username, second line = bio
+          */
+         auto [username, bio] = ParseTwoLineResponsePublic(
+             raw, "LlamaGenerator: malformed user response");
+
+         /**
+          * Remove any whitespace from username (usernames shouldn't have
+          * spaces)
+          */
+         username.erase(
+             std::remove_if(username.begin(), username.end(),
+                            [](unsigned char ch) { return std::isspace(ch); }),
+             username.end());
+
+         /**
+          * Validate both fields are non-empty after processing
+          */
+         if (username.empty() || bio.empty()) {
+            throw std::runtime_error("LlamaGenerator: malformed user response");
+         }
+
+         /**
+          * Truncate bio if exceeds reasonable length for bio field
+          */
+         if (bio.size() > 200) bio = bio.substr(0, 200);
+
+         /**
+          * Success: return parsed user profile
+          */
+         return {username, bio};
+      } catch (const std::exception& e) {
+         /**
+          * Parsing failed: log and continue to next attempt
+          */
+         spdlog::warn(
+             "LlamaGenerator: malformed user response (attempt {}): {}",
+             attempt + 1, e.what());
+      }
+   }
+
+   /**
+    * All retry attempts exhausted: log failure and throw exception
+    */
+   spdlog::error(
+       "LlamaGenerator: malformed user response after {} attempts: {}",
+       max_attempts, raw);
+   throw std::runtime_error("LlamaGenerator: malformed user response");
+}

pipeline/src/data_generation/llama/helpers.cpp

@@ -0,0 +1,445 @@
+/**
+ * @file data_generation/llama/helpers.cpp
+ * @brief Provides prompt formatting, whitespace normalization, response
+ * parsing, token decoding, and JSON validation helpers for Llama modules.
+ */
+
+#include <algorithm>
+#include <array>
+#include <boost/json.hpp>
+#include <cctype>
+#include <sstream>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+#include "data_generation/llama_generator.h"
+#include "llama.h"
+
+/**
+ * String trimming: removes leading and trailing whitespace
+ */
+static std::string Trim(std::string value) {
+   auto not_space = [](unsigned char ch) { return !std::isspace(ch); };
+
+   value.erase(value.begin(),
+               std::find_if(value.begin(), value.end(), not_space));
+   value.erase(std::find_if(value.rbegin(), value.rend(), not_space).base(),
+               value.end());
+
+   return value;
+}
+
+/**
+ * Normalize whitespace: collapses multiple spaces/tabs/newlines into single
+ * spaces
+ */
+static std::string CondenseWhitespace(std::string text) {
+   std::string out;
+   out.reserve(text.size());
+
+   bool in_whitespace = false;
+   for (unsigned char ch : text) {
+      if (std::isspace(ch)) {
+         if (!in_whitespace) {
+            out.push_back(' ');
+            in_whitespace = true;
+         }
+         continue;
+      }
+
+      in_whitespace = false;
+      out.push_back(static_cast<char>(ch));
+   }
+
+   return Trim(std::move(out));
+}
+
+/**
+ * Truncate region context to fit within max length while preserving word
+ * boundaries
+ */
+static std::string PrepareRegionContext(std::string_view region_context,
+                                        std::size_t max_chars) {
+   std::string normalized = CondenseWhitespace(std::string(region_context));
+   if (normalized.size() <= max_chars) {
+      return normalized;
+   }
+
+   normalized.resize(max_chars);
+   const std::size_t last_space = normalized.find_last_of(' ');
+   if (last_space != std::string::npos && last_space > max_chars / 2) {
+      normalized.resize(last_space);
+   }
+
+   normalized += "...";
+   return normalized;
+}
+
+/**
+ * Remove common bullet points, numbers, and field labels added by LLM in output
+ */
+static std::string StripCommonPrefix(std::string line) {
+   line = Trim(std::move(line));
+
+   if (!line.empty() && (line[0] == '-' || line[0] == '*')) {
+      line = Trim(line.substr(1));
+   } else {
+      std::size_t i = 0;
+      while (i < line.size() &&
+             std::isdigit(static_cast<unsigned char>(line[i]))) {
+         ++i;
+      }
+      if (i > 0 && i < line.size() && (line[i] == '.' || line[i] == ')')) {
+         line = Trim(line.substr(i + 1));
+      }
+   }
+
+   auto strip_label = [&line](const std::string& label) {
+      if (line.size() >= label.size()) {
+         bool matches = true;
+         for (std::size_t i = 0; i < label.size(); ++i) {
+            if (std::tolower(static_cast<unsigned char>(line[i])) !=
+                std::tolower(static_cast<unsigned char>(label[i]))) {
+               matches = false;
+               break;
+            }
+         }
+         if (matches) {
+            line = Trim(line.substr(label.size()));
+         }
+      }
+   };
+
+   strip_label("name:");
+   strip_label("brewery name:");
+   strip_label("description:");
+   strip_label("username:");
+   strip_label("bio:");
+
+   return Trim(std::move(line));
+}
+
+/**
+ * Parse two-line response from LLM: normalize line endings, strip formatting,
+ * filter spurious output, and combine remaining lines if needed
+ */
+static std::pair<std::string, std::string> ParseTwoLineResponse(
+    const std::string& raw, const std::string& error_message) {
+   std::string normalized = raw;
+   std::replace(normalized.begin(), normalized.end(), '\r', '\n');
+
+   std::vector<std::string> lines;
+   std::stringstream stream(normalized);
+   std::string line;
+   while (std::getline(stream, line)) {
+      line = StripCommonPrefix(std::move(line));
+      if (!line.empty()) lines.push_back(std::move(line));
+   }
+
+   std::vector<std::string> filtered;
+   for (auto& l : lines) {
+      std::string low = l;
+      std::transform(low.begin(), low.end(), low.begin(), [](unsigned char c) {
+         return static_cast<char>(std::tolower(c));
+      });
+      // Filter known thinking tags like <think>...</think>, but be conservative
+      // to avoid removing legitimate output. Only filter specific known
+      // patterns.
+      if (!l.empty() && l.front() == '<' && low.back() == '>') {
+         // Only filter if it's a known thinking tag: <think>, <reasoning>, etc.
+         if (low.find("think") != std::string::npos ||
+             low.find("reasoning") != std::string::npos ||
+             low.find("reflect") != std::string::npos) {
+            continue;
+         }
+      }
+      if (low.rfind("okay,", 0) == 0 || low.rfind("hmm", 0) == 0) continue;
+      filtered.push_back(std::move(l));
+   }
+
+   if (filtered.size() < 2) throw std::runtime_error(error_message);
+
+   std::string first = Trim(filtered.front());
+   std::string second;
+   for (size_t i = 1; i < filtered.size(); ++i) {
+      if (!second.empty()) second += ' ';
+      second += filtered[i];
+   }
+   second = Trim(std::move(second));
+
+   if (first.empty() || second.empty()) throw std::runtime_error(error_message);
+   return {first, second};
+}
+std::string ToChatPrompt(const llama_model* model,
+                         const std::string& system_prompt,
+                         const std::string& user_prompt) {
+   const char* tmpl = llama_model_chat_template(model, nullptr);
+   if (tmpl == nullptr) {
+      // No template found, fallback to raw text
+      return system_prompt + "\n\n" + user_prompt;
+   }
+
+   const std::array<llama_chat_message, 2> messages = {
+       {{"system", system_prompt.c_str()}, {"user", user_prompt.c_str()}}};
+
+   std::vector<char> buffer(std::max<std::size_t>(
+       1024, (system_prompt.size() + user_prompt.size()) * 4));
+
+   int32_t required =
+       llama_chat_apply_template(tmpl, messages.data(), 2, true, buffer.data(),
+                                 static_cast<int32_t>(buffer.size()));
+
+   // FALLBACK: If the template fails (e.g., Gemma rejecting the "system" role),
+   // combine the system and user prompts into a single "user" message.
+   if (required < 0) {
+      std::string combined_prompt = system_prompt + "\n\n" + user_prompt;
+      const std::array<llama_chat_message, 1> fallback_msg = {
+          {{"user", combined_prompt.c_str()}}};
+
+      required = llama_chat_apply_template(tmpl, fallback_msg.data(), 1, true,
+                                           buffer.data(),
+                                           static_cast<int32_t>(buffer.size()));
+
+      // THE FIX: Ultimate fallback. If the GGUF's internal template is
+      // completely unparseable (which happens with complex Jinja macros),
+      // degrade gracefully to raw text instead of throwing a runtime_error.
+      if (required < 0) {
+         return combined_prompt;
+      }
+
+      if (required >= static_cast<int32_t>(buffer.size())) {
+         buffer.resize(static_cast<std::size_t>(required) + 1);
+         required = llama_chat_apply_template(
+             tmpl, fallback_msg.data(), 1, true, buffer.data(),
+             static_cast<int32_t>(buffer.size()));
+
+         if (required < 0) {
+            return combined_prompt;
+         }
+      }
+
+      return std::string(buffer.data(), static_cast<std::size_t>(required));
+   }
+
+   // Standard buffer resize if the original "system" + "user" array succeeded
+   // but needed more space
+   if (required >= static_cast<int32_t>(buffer.size())) {
+      buffer.resize(static_cast<std::size_t>(required) + 1);
+      required = llama_chat_apply_template(tmpl, messages.data(), 2, true,
+                                           buffer.data(),
+                                           static_cast<int32_t>(buffer.size()));
+
+      // Final safety net on resize
+      if (required < 0) {
+         return system_prompt + "\n\n" + user_prompt;
+      }
+   }
+
+   return std::string(buffer.data(), static_cast<std::size_t>(required));
+}
+
+static void AppendTokenPiece(const llama_vocab* vocab, llama_token token,
+                             std::string& output) {
+   std::array<char, 256> buffer{};
+   int32_t bytes =
+       llama_token_to_piece(vocab, token, buffer.data(),
+                            static_cast<int32_t>(buffer.size()), 0, true);
+
+   if (bytes < 0) {
+      std::vector<char> dynamic_buffer(static_cast<std::size_t>(-bytes));
+      bytes = llama_token_to_piece(vocab, token, dynamic_buffer.data(),
+                                   static_cast<int32_t>(dynamic_buffer.size()),
+                                   0, true);
+      if (bytes < 0) {
+         throw std::runtime_error(
+             "LlamaGenerator: failed to decode sampled token piece");
+      }
+
+      output.append(dynamic_buffer.data(), static_cast<std::size_t>(bytes));
+      return;
+   }
+
+   output.append(buffer.data(), static_cast<std::size_t>(bytes));
+}
+
+static bool ExtractLastJsonObject(const std::string& text,
+                                  std::string& json_out) {
+   std::size_t start = std::string::npos;
+   int depth = 0;
+   bool in_string = false;
+   bool escaped = false;
+   bool found = false;
+   std::string candidate;
+
+   for (std::size_t i = 0; i < text.size(); ++i) {
+      const char ch = text[i];
+
+      if (in_string) {
+         if (escaped) {
+            escaped = false;
+         } else if (ch == '\\') {
+            escaped = true;
+         } else if (ch == '"') {
+            in_string = false;
+         }
+         continue;
+      }
+
+      if (ch == '"') {
+         in_string = true;
+         continue;
+      }
+
+      if (ch == '{') {
+         if (depth == 0) {
+            start = i;
+         }
+         ++depth;
+         continue;
+      }
+
+      if (ch == '}') {
+         if (depth == 0) {
+            continue;
+         }
+         --depth;
+         if (depth == 0 && start != std::string::npos) {
+            candidate = text.substr(start, i - start + 1);
+            found = true;
+         }
+      }
+   }
+
+   if (!found) {
+      return false;
+   }
+
+   json_out = std::move(candidate);
+   return true;
+}
+
+std::string ExtractLastJsonObjectPublic(const std::string& text) {
+   std::string extracted;
+   if (ExtractLastJsonObject(text, extracted)) {
+      return extracted;
+   }
+
+   return {};
+}
+
+static std::string ValidateBreweryJson(const std::string& raw,
+                                       std::string& name_out,
+                                       std::string& description_out) {
+   auto validate_object = [&](const boost::json::value& jv,
+                              std::string& error_out) -> bool {
+      if (!jv.is_object()) {
+         error_out = "JSON root must be an object";
+         return false;
+      }
+
+      const auto& obj = jv.get_object();
+      if (!obj.contains("name") || !obj.at("name").is_string()) {
+         error_out = "JSON field 'name' is missing or not a string";
+         return false;
+      }
+
+      if (!obj.contains("description") || !obj.at("description").is_string()) {
+         error_out = "JSON field 'description' is missing or not a string";
+         return false;
+      }
+
+      name_out = Trim(std::string(obj.at("name").as_string().c_str()));
+      description_out =
+          Trim(std::string(obj.at("description").as_string().c_str()));
+
+      if (name_out.empty()) {
+         error_out = "JSON field 'name' must not be empty";
+         return false;
+      }
+
+      if (description_out.empty()) {
+         error_out = "JSON field 'description' must not be empty";
+         return false;
+      }
+
+      std::string name_lower = name_out;
+      std::string description_lower = description_out;
+      std::transform(
+          name_lower.begin(), name_lower.end(), name_lower.begin(),
+          [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+      std::transform(description_lower.begin(), description_lower.end(),
+                     description_lower.begin(), [](unsigned char c) {
+                        return static_cast<char>(std::tolower(c));
+                     });
+
+      if (name_lower == "string" || description_lower == "string") {
+         error_out = "JSON appears to be a schema placeholder, not content";
+         return false;
+      }
+
+      error_out.clear();
+      return true;
+   };
+
+   boost::system::error_code ec;
+   boost::json::value jv = boost::json::parse(raw, ec);
+   std::string validation_error;
+   if (ec) {
+      std::string extracted;
+      if (!ExtractLastJsonObject(raw, extracted)) {
+         return "JSON parse error: " + ec.message();
+      }
+
+      ec.clear();
+      jv = boost::json::parse(extracted, ec);
+      if (ec) {
+         return "JSON parse error: " + ec.message();
+      }
+
+      if (!validate_object(jv, validation_error)) {
+         return validation_error;
+      }
+
+      return {};
+   }
+
+   if (!validate_object(jv, validation_error)) {
+      return validation_error;
+   }
+
+   return {};
+}
+
+// Forward declarations for helper functions exposed to other translation units
+std::string PrepareRegionContextPublic(std::string_view region_context,
+                                       std::size_t max_chars) {
+   return PrepareRegionContext(region_context, max_chars);
+}
+
+std::pair<std::string, std::string> ParseTwoLineResponsePublic(
+    const std::string& raw, const std::string& error_message) {
+   return ParseTwoLineResponse(raw, error_message);
+}
+
+std::string ToChatPromptPublic(const llama_model* model,
+                               const std::string& user_prompt) {
+   return ToChatPrompt(model, user_prompt, "");
+}
+
+std::string ToChatPromptPublic(const llama_model* model,
+                               const std::string& system_prompt,
+                               const std::string& user_prompt) {
+   return ToChatPrompt(model, system_prompt, user_prompt);
+}
+
+void AppendTokenPiecePublic(const llama_vocab* vocab, llama_token token,
+                            std::string& output) {
+   AppendTokenPiece(vocab, token, output);
+}
+
+std::string ValidateBreweryJsonPublic(const std::string& raw,
+                                      std::string& name_out,
+                                      std::string& description_out) {
+   return ValidateBreweryJson(raw, name_out, description_out);
+}

pipeline/src/data_generation/llama/infer.cpp

@@ -0,0 +1,198 @@
+/**
+ * Text Generation / Inference Module
+ * Core module that performs LLM inference: converts text prompts into tokens,
+ * runs the neural network forward pass, samples the next token, and converts
+ * output tokens back to text. Supports both simple and system+user prompts.
+ */
+
+#include <spdlog/spdlog.h>
+
+#include <algorithm>
+#include <memory>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+#include "data_generation/llama_generator.h"
+#include "data_generation/llama_generator_helpers.h"
+#include "llama.h"
+
+std::string LlamaGenerator::Infer(const std::string& prompt, int max_tokens) {
+   return InferFormatted(ToChatPromptPublic(model_, prompt), max_tokens);
+}
+
+std::string LlamaGenerator::Infer(const std::string& system_prompt,
+                                  const std::string& prompt, int max_tokens) {
+   return InferFormatted(ToChatPromptPublic(model_, system_prompt, prompt),
+                         max_tokens);
+}
+
+std::string LlamaGenerator::InferFormatted(const std::string& formatted_prompt,
+                                           int max_tokens) {
+   /**
+    * Validate that model and context are loaded
+    */
+   if (model_ == nullptr || context_ == nullptr)
+      throw std::runtime_error("LlamaGenerator: model not loaded");
+
+   /**
+    * Get vocabulary for tokenization and token-to-text conversion
+    */
+   const llama_vocab* vocab = llama_model_get_vocab(model_);
+   if (vocab == nullptr)
+      throw std::runtime_error("LlamaGenerator: vocab unavailable");
+
+   /**
+    * Clear KV cache to ensure clean inference state (no residual context)
+    */
+   llama_memory_clear(llama_get_memory(context_), true);
+
+   /**
+    * TOKENIZATION PHASE
+    * Convert text prompt into token IDs (integers) that the model understands
+    */
+   std::vector<llama_token> prompt_tokens(formatted_prompt.size() + 8);
+   int32_t token_count = llama_tokenize(
+       vocab, formatted_prompt.c_str(),
+       static_cast<int32_t>(formatted_prompt.size()), prompt_tokens.data(),
+       static_cast<int32_t>(prompt_tokens.size()), true, true);
+
+   /**
+    * If buffer too small, negative return indicates required size
+    */
+   if (token_count < 0) {
+      prompt_tokens.resize(static_cast<std::size_t>(-token_count));
+      token_count = llama_tokenize(
+          vocab, formatted_prompt.c_str(),
+          static_cast<int32_t>(formatted_prompt.size()), prompt_tokens.data(),
+          static_cast<int32_t>(prompt_tokens.size()), true, true);
+   }
+
+   if (token_count < 0)
+      throw std::runtime_error("LlamaGenerator: prompt tokenization failed");
+
+   /**
+    * CONTEXT SIZE VALIDATION
+    * Validate and compute effective token budgets based on context window
+    * constraints
+    */
+   const int32_t n_ctx = static_cast<int32_t>(llama_n_ctx(context_));
+   const int32_t n_batch = static_cast<int32_t>(llama_n_batch(context_));
+   if (n_ctx <= 1 || n_batch <= 0)
+      throw std::runtime_error("LlamaGenerator: invalid context or batch size");
+
+   /**
+    * Clamp generation limit to available context window, reserve space for
+    * output
+    */
+   const int32_t effective_max_tokens =
+       std::max(1, std::min(max_tokens, n_ctx - 1));
+   /**
+    * Prompt can use remaining context after reserving space for generation
+    */
+   int32_t prompt_budget = std::min(n_batch, n_ctx - effective_max_tokens);
+   prompt_budget = std::max<int32_t>(1, prompt_budget);
+
+   /**
+    * Truncate prompt if necessary to fit within constraints
+    */
+   prompt_tokens.resize(static_cast<std::size_t>(token_count));
+   if (token_count > prompt_budget) {
+      spdlog::warn(
+          "LlamaGenerator: prompt too long ({} tokens), truncating to {} "
+          "tokens to fit n_batch/n_ctx limits",
+          token_count, prompt_budget);
+      prompt_tokens.resize(static_cast<std::size_t>(prompt_budget));
+      token_count = prompt_budget;
+   }
+
+   /**
+    * PROMPT PROCESSING PHASE
+    * Create a batch containing all prompt tokens and feed through the model
+    * This computes internal representations and fills the KV cache
+    */
+   const llama_batch prompt_batch = llama_batch_get_one(
+       prompt_tokens.data(), static_cast<int32_t>(prompt_tokens.size()));
+   if (llama_decode(context_, prompt_batch) != 0)
+      throw std::runtime_error("LlamaGenerator: prompt decode failed");
+
+   /**
+    * SAMPLER CONFIGURATION PHASE
+    * Set up the probabilistic token selection pipeline (sampler chain)
+    * Samplers are applied in sequence: temperature -> top-k -> top-p ->
+    * distribution
+    */
+   llama_sampler_chain_params sampler_params =
+       llama_sampler_chain_default_params();
+   using SamplerPtr =
+       std::unique_ptr<llama_sampler, decltype(&llama_sampler_free)>;
+   SamplerPtr sampler(llama_sampler_chain_init(sampler_params),
+                      &llama_sampler_free);
+   if (!sampler)
+      throw std::runtime_error("LlamaGenerator: failed to initialize sampler");
+
+   /**
+    * Temperature: scales logits before softmax (controls randomness)
+    */
+   llama_sampler_chain_add(sampler.get(),
+                           llama_sampler_init_temp(sampling_temperature_));
+   /**
+    * Top-K: limits sampling to the most likely tokens before nucleus
+    * sampling
+    */
+   llama_sampler_chain_add(
+       sampler.get(),
+       llama_sampler_init_top_k(static_cast<int32_t>(sampling_top_k_)));
+   /**
+    * Top-P: nucleus sampling - filters to most likely tokens summing to top_p
+    * probability
+    */
+   llama_sampler_chain_add(sampler.get(),
+                           llama_sampler_init_top_p(sampling_top_p_, 1));
+   /**
+    * Distribution sampler: selects actual token using configured seed for
+    * reproducibility
+    */
+   llama_sampler_chain_add(sampler.get(), llama_sampler_init_dist(rng_()));
+
+   /**
+    * TOKEN GENERATION LOOP
+    * Iteratively generate tokens one at a time until max_tokens or
+    * end-of-sequence
+    */
+   std::vector<llama_token> generated_tokens;
+   generated_tokens.reserve(static_cast<std::size_t>(effective_max_tokens));
+
+   for (int i = 0; i < effective_max_tokens; ++i) {
+      /**
+       * Sample next token using configured sampler chain and model logits
+       * Index -1 means use the last output position from previous batch
+       */
+      const llama_token next =
+          llama_sampler_sample(sampler.get(), context_, -1);
+      /**
+       * Stop if model predicts end-of-generation token (EOS/EOT)
+       */
+      if (llama_vocab_is_eog(vocab, next)) break;
+      generated_tokens.push_back(next);
+      /**
+       * Feed the sampled token back into model for next iteration
+       * (autoregressive)
+       */
+      llama_token token = next;
+      const llama_batch one_token_batch = llama_batch_get_one(&token, 1);
+      if (llama_decode(context_, one_token_batch) != 0)
+         throw std::runtime_error(
+             "LlamaGenerator: decode failed during generation");
+   }
+
+   /**
+    * DETOKENIZATION PHASE
+    * Convert generated token IDs back to text using vocabulary
+    */
+   std::string output;
+   for (const llama_token token : generated_tokens)
+      AppendTokenPiecePublic(vocab, token, output);
+
+   return output;
+}

pipeline/src/data_generation/llama/llama_generator.cpp

@@ -0,0 +1,76 @@
+/**
+ * @file data_generation/llama/llama_generator.cpp
+ * @brief LlamaGenerator constructor and destructor implementation.
+ */
+
+#include "data_generation/llama_generator.h"
+
+#include <random>
+#include <stdexcept>
+#include <string>
+
+#include "data_model/application_options.h"
+#include "llama.h"
+
+LlamaGenerator::LlamaGenerator(const ApplicationOptions& options,
+                               const std::string& model_path)
+    : rng_(std::random_device{}()) {
+   if (model_path.empty()) {
+      throw std::runtime_error("LlamaGenerator: model path must not be empty");
+   }
+
+   if (options.temperature < 0.0F) {
+      throw std::runtime_error(
+          "LlamaGenerator: sampling temperature must be >= 0");
+   }
+
+   if (options.top_p <= 0.0F || options.top_p > 1.0F) {
+      throw std::runtime_error(
+          "LlamaGenerator: sampling top-p must be in (0, 1]");
+   }
+
+   if (options.top_k == 0U) {
+      throw std::runtime_error("LlamaGenerator: sampling top-k must be > 0");
+   }
+
+   if (options.seed < -1) {
+      throw std::runtime_error(
+          "LlamaGenerator: seed must be >= 0, or -1 for random");
+   }
+
+   if (options.n_ctx == 0 || options.n_ctx > 32768) {
+      throw std::runtime_error(
+          "LlamaGenerator: context size must be in range [1, 32768]");
+   }
+
+   sampling_temperature_ = options.temperature;
+   sampling_top_p_ = options.top_p;
+   sampling_top_k_ = options.top_k;
+   if (options.seed == -1) {
+      std::random_device random_device;
+      rng_.seed(random_device());
+   } else {
+      rng_.seed(static_cast<uint32_t>(options.seed));
+   }
+   n_ctx_ = options.n_ctx;
+
+   this->Load(model_path);
+}
+
+LlamaGenerator::~LlamaGenerator() {
+   /**
+    * Free the inference context (contains KV cache and computation state)
+    */
+   if (context_ != nullptr) {
+      llama_free(context_);
+      context_ = nullptr;
+   }
+
+   /**
+    * Free the loaded model (contains weights and vocabulary)
+    */
+   if (model_ != nullptr) {
+      llama_model_free(model_);
+      model_ = nullptr;
+   }
+}

pipeline/src/data_generation/llama/load.cpp

@@ -0,0 +1,45 @@
+/**
+ * @file data_generation/llama/load.cpp
+ * @brief Initializes llama backend, loads model weights, creates inference
+ * context, and resets prior resources during model initialization.
+ */
+
+#include <spdlog/spdlog.h>
+
+#include <algorithm>
+#include <stdexcept>
+#include <string>
+
+#include "data_generation/llama_generator.h"
+#include "llama.h"
+
+void LlamaGenerator::Load(const std::string& model_path) {
+   if (context_ != nullptr) {
+      llama_free(context_);
+      context_ = nullptr;
+   }
+   if (model_ != nullptr) {
+      llama_model_free(model_);
+      model_ = nullptr;
+   }
+
+   llama_model_params model_params = llama_model_default_params();
+   model_ = llama_model_load_from_file(model_path.c_str(), model_params);
+   if (model_ == nullptr) {
+      throw std::runtime_error(
+          "LlamaGenerator: failed to load model from path: " + model_path);
+   }
+
+   llama_context_params context_params = llama_context_default_params();
+   context_params.n_ctx = n_ctx_;
+   context_params.n_batch = std::min(n_ctx_, static_cast<uint32_t>(5000));
+
+   context_ = llama_init_from_model(model_, context_params);
+   if (context_ == nullptr) {
+      llama_model_free(model_);
+      model_ = nullptr;
+      throw std::runtime_error("LlamaGenerator: failed to create context");
+   }
+
+   spdlog::info("[LlamaGenerator] Loaded model: {}", model_path);
+}

pipeline/src/data_generation/llama/load_brewery_prompt.cpp

@@ -0,0 +1,97 @@
+/**
+ * @file data_generation/llama/load_brewery_prompt.cpp
+ * @brief Resolves brewery system prompt content from cache or filesystem
+ * search paths and provides a robust inline fallback prompt when absent.
+ */
+
+#include <spdlog/spdlog.h>
+
+#include <filesystem>
+#include <fstream>
+
+#include "data_generation/llama_generator.h"
+
+namespace fs = std::filesystem;
+
+/**
+ * @brief Loads brewery system prompt from disk or cache.
+ *
+ * @param prompt_file_path Preferred prompt file location.
+ * @return Prompt text loaded from disk or fallback content.
+ */
+std::string LlamaGenerator::LoadBrewerySystemPrompt(
+    const std::string& prompt_file_path) {
+   // Return cached version if already loaded
+   if (!brewery_system_prompt_.empty()) {
+      return brewery_system_prompt_;
+   }
+
+   // Try multiple path locations
+   std::vector<std::string> paths_to_try = {
+       prompt_file_path,             // As provided
+       "../" + prompt_file_path,     // One level up
+       "../../" + prompt_file_path,  // Two levels up
+   };
+
+   for (const auto& path : paths_to_try) {
+      std::ifstream prompt_file(path);
+      if (prompt_file.is_open()) {
+         std::string prompt((std::istreambuf_iterator<char>(prompt_file)),
+                            std::istreambuf_iterator<char>());
+         prompt_file.close();
+
+         if (!prompt.empty()) {
+            spdlog::info(
+                "LlamaGenerator: Loaded brewery system prompt from '{}' ({} "
+                "chars)",
+                path, prompt.length());
+            brewery_system_prompt_ = prompt;
+            return brewery_system_prompt_;
+         }
+      }
+   }
+
+   spdlog::warn(
+       "LlamaGenerator: Could not open brewery system prompt file at any of "
+       "the "
+       "expected locations. Using fallback inline prompt.");
+   return GetFallbackBreweryPrompt();
+}
+
+/**
+ * @brief Provides an inline fallback brewery system prompt.
+ *
+ * @return Default fallback prompt text.
+ */
+std::string LlamaGenerator::GetFallbackBreweryPrompt() {
+   return "You are an experienced brewmaster and owner of a local craft "
+          "brewery. "
+          "Create a distinctive, authentic name and detailed description that "
+          "genuinely reflects your specific location, brewing philosophy, "
+          "local "
+          "culture, and community connection. The brewery must feel real and "
+          "grounded—not generic or interchangeable.\n\n"
+          "AVOID REPETITIVE PHRASES - Never use:\n"
+          "Love letter to, tribute to, rolling hills, picturesque, every sip "
+          "tells a story, Come for X stay for Y, rich history, passion, woven "
+          "into, ancient roots, timeless, where tradition meets innovation\n\n"
+          "OPENING APPROACHES - Choose ONE:\n"
+          "1. Start with specific beer style and its regional origins\n"
+          "2. Begin with specific brewing challenge (water, altitude, "
+          "climate)\n"
+          "3. Open with founding story or personal motivation\n"
+          "4. Lead with specific local ingredient or resource\n"
+          "5. Start with unexpected angle or contradiction\n"
+          "6. Open with local event, tradition, or cultural moment\n"
+          "7. Begin with tangible architectural or geographic detail\n\n"
+          "BE SPECIFIC - Include:\n"
+          "- At least ONE concrete proper noun (landmark, river, "
+          "neighborhood)\n"
+          "- Specific beer styles relevant to the REGION'S culture\n"
+          "- Concrete brewing challenges or advantages\n"
+          "- Sensory details SPECIFIC to place—not generic adjectives\n\n"
+          "LENGTH: 150-250 words. TONE: Can be soulful, irreverent, "
+          "matter-of-fact, unpretentious, or minimalist.\n\n"
+          "Output ONLY a raw JSON object with keys name and description. "
+          "No markdown, backticks, preamble, or trailing text.";
+}

pipeline/src/data_generation/mock/data.cpp

@@ -0,0 +1,71 @@
+/**
+ * @file data_generation/mock/data.cpp
+ * @brief Defines static lookup tables used by MockGenerator for deterministic
+ * brewery names, descriptions, usernames, and bios.
+ */
+
+#include <string>
+#include <vector>
+
+#include "data_generation/mock_generator.h"
+
+const std::vector<std::string> MockGenerator::kBreweryAdjectives = {
+    "Craft",      "Heritage", "Local",  "Artisan",  "Pioneer",    "Golden",
+    "Modern",     "Classic",  "Summit", "Northern", "Riverstone", "Barrel",
+    "Hinterland", "Harbor",   "Wild",   "Granite",  "Copper",     "Maple"};
+
+const std::vector<std::string> MockGenerator::kBreweryNouns = {
+    "Brewing Co.", "Brewery",    "Bier Haus", "Taproom",      "Works",
+    "House",       "Fermentery", "Ale Co.",   "Cellars",      "Collective",
+    "Project",     "Foundry",    "Malthouse", "Public House", "Co-op",
+    "Lab",         "Beer Hall",  "Guild"};
+
+const std::vector<std::string> MockGenerator::kBreweryDescriptions = {
+    "Handcrafted pale ales and seasonal IPAs with local ingredients.",
+    "Traditional lagers and experimental sours in small batches.",
+    "Award-winning stouts and wildly hoppy blonde ales.",
+    "Craft brewery specializing in Belgian-style triples and dark porters.",
+    "Modern brewery blending tradition with bold experimental flavors.",
+    "Neighborhood-focused taproom pouring crisp pilsners and citrusy pale "
+    "ales.",
+    "Small-batch brewery known for barrel-aged releases and smoky lagers.",
+    "Independent brewhouse pairing farmhouse ales with rotating food pop-ups.",
+    "Community brewpub making balanced bitters, saisons, and hazy IPAs.",
+    "Experimental nanobrewery exploring local yeast and regional grains.",
+    "Family-run brewery producing smooth amber ales and robust porters.",
+    "Urban brewery crafting clean lagers and bright, fruit-forward sours.",
+    "Riverfront brewhouse featuring oak-matured ales and seasonal blends.",
+    "Modern taproom focused on sessionable lagers and classic pub styles.",
+    "Brewery rooted in tradition with a lineup of malty reds and crisp lagers.",
+    "Creative brewery offering rotating collaborations and limited draft-only "
+    "pours.",
+    "Locally inspired brewery serving approachable ales with bold hop "
+    "character.",
+    "Destination taproom known for balanced IPAs and cocoa-rich stouts."};
+
+const std::vector<std::string> MockGenerator::kUsernames = {
+    "hopseeker",     "malttrail",   "yeastwhisper",  "lagerlane",
+    "barrelbound",   "foamfinder",  "taphunter",     "graingeist",
+    "brewscout",     "aleatlas",    "caskcompass",   "hopsandmaps",
+    "mashpilot",     "pintnomad",   "fermentfriend", "stoutsignal",
+    "sessionwander", "kettlekeeper"};
+
+const std::vector<std::string> MockGenerator::kBios = {
+    "Always chasing balanced IPAs and crisp lagers across local taprooms.",
+    "Weekend brewery explorer with a soft spot for dark, roasty stouts.",
+    "Documenting tiny brewpubs, fresh pours, and unforgettable beer gardens.",
+    "Fan of farmhouse ales, food pairings, and long tasting flights.",
+    "Collecting favorite pilsners one city at a time.",
+    "Hops-first drinker who still saves room for classic malt-forward styles.",
+    "Finding hidden tap lists and sharing the best seasonal releases.",
+    "Brewery road-tripper focused on local ingredients and clean fermentation.",
+    "Always comparing house lagers and ranking patio pint vibes.",
+    "Curious about yeast strains, barrel programs, and cellar experiments.",
+    "Believes every neighborhood deserves a great community taproom.",
+    "Looking for session beers that taste great from first sip to last.",
+    "Belgian ale enthusiast who never skips a new saison.",
+    "Hazy IPA critic with deep respect for a perfectly clear pilsner.",
+    "Visits breweries for the stories, stays for the flagship pours.",
+    "Craft beer fan mapping tasting notes and favorite brew routes.",
+    "Always ready to trade recommendations for underrated local breweries.",
+    "Keeping a running list of must-try collab releases and tap takeovers."};

pipeline/src/data_generation/mock/deterministic_hash.cpp

@@ -0,0 +1,17 @@
+/**
+ * @file data_generation/mock/deterministic_hash.cpp
+ * @brief Implements a stable hash combiner used by MockGenerator to derive
+ * repeatable pseudo-random indices from location input.
+ */
+
+#include <boost/container_hash/hash.hpp>
+#include <string>
+
+#include "data_generation/mock_generator.h"
+
+std::size_t MockGenerator::DeterministicHash(const BreweryLocation& location) {
+   std::size_t seed = 0;
+   boost::hash_combine(seed, location.city_name);
+   boost::hash_combine(seed, location.country_name);
+   return seed;
+}

pipeline/src/data_generation/mock/generate_brewery.cpp

@@ -0,0 +1,38 @@
+/**
+ * @file data_generation/mock/generate_brewery.cpp
+ * @brief Builds deterministic brewery names and descriptions by hashing city
+ * and country into fixed mock phrase catalogs.
+ */
+
+#include <string>
+
+#include "data_generation/mock_generator.h"
+
+BreweryResult MockGenerator::GenerateBrewery(
+    const BreweryLocation& location, const std::string& /*region_context*/) {
+   const std::size_t hash = DeterministicHash(location);
+
+   const std::string& adjective =
+       kBreweryAdjectives.at(hash % kBreweryAdjectives.size());
+   const std::string& noun =
+       kBreweryNouns.at((hash / 7) % kBreweryNouns.size());
+   const std::string& base_description =
+       kBreweryDescriptions.at((hash / 13) % kBreweryDescriptions.size());
+
+   std::string name(location.city_name);
+   name.append(" ");
+   name.append(adjective);
+   name.append(" ");
+   name.append(noun);
+
+   std::string description = base_description;
+   description.append(" Based in ");
+   description.append(location.city_name);
+   if (!location.country_name.empty()) {
+      description.append(", ");
+      description.append(location.country_name);
+   }
+   description.append(".");
+
+   return {name, description};
+}

pipeline/src/data_generation/mock/generate_user.cpp

@@ -0,0 +1,19 @@
+/**
+ * @file data_generation/mock/generate_user.cpp
+ * @brief Generates deterministic mock user profiles by hashing locale values
+ * into predefined username and bio collections.
+ */
+
+#include <functional>
+#include <string>
+
+#include "data_generation/mock_generator.h"
+
+UserResult MockGenerator::GenerateUser(const std::string& locale) {
+   const std::size_t hash = std::hash<std::string>{}(locale);
+
+   UserResult result;
+   result.username = kUsernames[hash % kUsernames.size()];
+   result.bio = kBios[(hash / 11) % kBios.size()];
+   return result;
+}

pipeline/src/json_handling/json_loader.cpp

@@ -0,0 +1,83 @@
+/**
+ * @file json_handling/json_loader.cpp
+ * @brief Parses curated location JSON input into strongly typed Location
+ * records with strict field validation and descriptive error reporting.
+ */
+
+#include "json_handling/json_loader.h"
+
+#include <spdlog/spdlog.h>
+
+#include <boost/json.hpp>
+#include <fstream>
+#include <sstream>
+#include <stdexcept>
+
+static std::string ReadRequiredString(const boost::json::object& object,
+                                      const char* key) {
+   const boost::json::value* value = object.if_contains(key);
+   if (value == nullptr || !value->is_string()) {
+      throw std::runtime_error(
+          std::string("Missing or invalid string field: ") + key);
+   }
+   return std::string(value->as_string().c_str());
+}
+
+static double ReadRequiredNumber(const boost::json::object& object,
+                                 const char* key) {
+   const boost::json::value* value = object.if_contains(key);
+   if (value == nullptr || !value->is_number()) {
+      throw std::runtime_error(
+          std::string("Missing or invalid numeric field: ") + key);
+   }
+   return value->to_number<double>();
+}
+
+std::vector<Location> JsonLoader::LoadLocations(const std::string& filepath) {
+   std::ifstream input(filepath);
+   if (!input.is_open()) {
+      throw std::runtime_error("Failed to open locations file: " + filepath);
+   }
+
+   std::stringstream buffer;
+   buffer << input.rdbuf();
+   const std::string content = buffer.str();
+
+   boost::system::error_code error;
+   boost::json::value root = boost::json::parse(content, error);
+   if (error) {
+      throw std::runtime_error("Failed to parse locations JSON: " +
+                               error.message());
+   }
+
+   if (!root.is_array()) {
+      throw std::runtime_error(
+          "Invalid locations JSON: root element must be an array");
+   }
+
+   std::vector<Location> locations;
+   const auto& items = root.as_array();
+   locations.reserve(items.size());
+
+   for (const auto& item : items) {
+      if (!item.is_object()) {
+         throw std::runtime_error(
+             "Invalid locations JSON: each entry must be an object");
+      }
+
+      const auto& object = item.as_object();
+      locations.push_back(Location{
+          .city = ReadRequiredString(object, "city"),
+          .state_province = ReadRequiredString(object, "state_province"),
+          .iso3166_2 = ReadRequiredString(object, "iso3166_2"),
+          .country = ReadRequiredString(object, "country"),
+          .iso3166_1 = ReadRequiredString(object, "iso3166_1"),
+          .latitude = ReadRequiredNumber(object, "latitude"),
+          .longitude = ReadRequiredNumber(object, "longitude"),
+      });
+   }
+
+   spdlog::info("[JsonLoader] Loaded {} locations from {}", locations.size(),
+                filepath);
+   return locations;
+}

pipeline/src/main.cpp

@@ -0,0 +1,170 @@
+/**
+ * @file main.cpp
+ * @brief Parses command-line options, validates runtime mode selection,
+ * initializes shared infrastructure, and executes the pipeline entry flow.
+ */
+
+#include <spdlog/spdlog.h>
+
+#include <boost/di.hpp>
+#include <boost/program_options.hpp>
+#include <exception>
+#include <memory>
+#include <sstream>
+#include <string>
+
+#include "biergarten_data_generator.h"
+#include "data_generation/llama_generator.h"
+#include "data_generation/mock_generator.h"
+#include "data_model/application_options.h"
+#include "llama_backend_state.h"
+#include "services/enrichment_service.h"
+#include "services/wikipedia_service.h"
+#include "web_client/curl_web_client.h"
+
+namespace prog_opts = boost::program_options;
+namespace di = boost::di;
+
+/**
+ * @brief Parse command-line arguments into ApplicationOptions.
+ *
+ * @param argc Command-line argument count.
+ * @param argv Command-line arguments.
+ * @param options Output ApplicationOptions struct.
+ * @return true if parsing succeeded and should proceed, false otherwise.
+ */
+bool ParseArguments(const int argc, char** argv,
+                    ApplicationOptions& options) noexcept {
+   prog_opts::options_description desc("Pipeline Options");
+   desc.add_options()("help,h", "Produce help message")(
+       "mocked", prog_opts::bool_switch(),
+       "Use mocked generator for brewery/user data")(
+       "model,m", prog_opts::value<std::string>()->default_value(""),
+       "Path to LLM model (gguf)")(
+       "temperature", prog_opts::value<float>()->default_value(1.0F),
+       "Sampling temperature (higher = more random)")(
+       "top-p", prog_opts::value<float>()->default_value(0.95F),
+       "Nucleus sampling top-p in (0,1] (higher = more random)")(
+       "top-k", prog_opts::value<uint32_t>()->default_value(64),
+       "Top-k sampling parameter (higher = more candidate tokens)")(
+       "n-ctx", prog_opts::value<uint32_t>()->default_value(8192),
+       "Context window size in tokens (1-32768)")(
+       "seed", prog_opts::value<int>()->default_value(-1),
+       "Sampler seed: -1 for random, otherwise non-negative integer");
+
+   // Handle the "no arguments" or "help" case
+   if (argc == 1) {
+      spdlog::info("Biergarten Pipeline");
+      std::stringstream usage_stream;
+      usage_stream << "\nUsage: biergarten-pipeline [options]\n\n" << desc;
+      spdlog::info(usage_stream.str());
+      return false;
+   }
+
+   try {
+      prog_opts::variables_map variables_map;
+      prog_opts::store(prog_opts::parse_command_line(argc, argv, desc),
+                       variables_map);
+      prog_opts::notify(variables_map);
+
+      if (variables_map.contains("help")) {
+         std::stringstream help_stream;
+         help_stream << "\n" << desc;
+         spdlog::info(help_stream.str());
+         return false;
+      }
+
+      const auto use_mocked = variables_map["mocked"].as<bool>();
+      const auto model_path = variables_map["model"].as<std::string>();
+
+      if (use_mocked && !model_path.empty()) {
+         spdlog::error(
+             "Invalid arguments: --mocked and --model are mutually exclusive");
+         return false;
+      }
+
+      if (!use_mocked && model_path.empty()) {
+         spdlog::error(
+             "Invalid arguments: Either --mocked or --model must be specified");
+         return false;
+      }
+
+      const bool has_llm_params = !variables_map["temperature"].defaulted() ||
+                                  !variables_map["top-p"].defaulted() ||
+                                  !variables_map["top-k"].defaulted() ||
+                                  !variables_map["seed"].defaulted();
+
+      if (use_mocked && has_llm_params) {
+         spdlog::warn(
+             "Sampling parameters (--temperature, --top-p, --top-k, --seed) are"
+             " ignored when using --mocked");
+      }
+
+      options.use_mocked = use_mocked;
+      options.model_path = model_path;
+      options.temperature = variables_map["temperature"].as<float>();
+      options.top_p = variables_map["top-p"].as<float>();
+      options.top_k = variables_map["top-k"].as<uint32_t>();
+      options.n_ctx = variables_map["n-ctx"].as<uint32_t>();
+      options.seed = variables_map["seed"].as<int>();
+
+      return true;
+   } catch (const std::exception& exception) {
+      spdlog::error("Failed to parse command-line arguments: {}",
+                    exception.what());
+      return false;
+   } catch (...) {
+      spdlog::error("Failed to parse command-line arguments: unknown error");
+      return false;
+   }
+}
+
+int main(const int argc, char** argv) noexcept {
+   try {
+      const CurlGlobalState curl_state;
+      const LlamaBackendState llama_backend_state;
+      spdlog::set_pattern("[%Y-%m-%d %H:%M:%S.%e] [%^%l%$] %v");
+
+      ApplicationOptions options;
+      if (!ParseArguments(argc, argv, options)) {
+         return 0;
+      }
+
+      const auto injector = di::make_injector(
+          di::bind<WebClient>().to<CURLWebClient>(),
+          di::bind<ApplicationOptions>().to(options),
+          di::bind<IEnrichmentService>().to<WikipediaService>(),
+          di::bind<std::string>().to(options.model_path),
+          di::bind<DataGenerator>().to([options](const auto& injector)
+                                           -> std::unique_ptr<DataGenerator> {
+             if (options.use_mocked) {
+                spdlog::info(
+                    "[Generator] Using MockGenerator (no model path provided)");
+                return std::make_unique<MockGenerator>();
+             }
+
+             spdlog::info(
+                 "[Generator] Using LlamaGenerator: {} (temperature={}, "
+                 "top-p={}, top-k={}, n_ctx={}, seed={})",
+                 options.model_path, options.temperature, options.top_p,
+                 options.top_k, options.n_ctx, options.seed);
+             return injector.template create<std::unique_ptr<LlamaGenerator>>();
+          }));
+
+      auto generator = injector.create<BiergartenDataGenerator>();
+
+      if (!generator.Run()) {
+         spdlog::error("Pipeline execution failed");
+         return 1;
+      }
+
+      spdlog::info("Pipeline executed successfully");
+      return 0;
+   } catch (const std::exception& exception) {
+      spdlog::critical("Unhandled fatal error in main: {}", exception.what());
+      return 1;
+   } catch (...) {
+      spdlog::critical("Unhandled fatal non-standard exception in main");
+      return 1;
+   }
+}

pipeline/src/services/wikipedia/fetch_extract.cpp

@@ -0,0 +1,58 @@
+/**
+ * @file wikipedia/fetch_extract.cpp
+ * @brief WikipediaService::FetchExtract() implementation.
+ */
+
+#include <spdlog/spdlog.h>
+
+#include <boost/json.hpp>
+#include <string>
+#include <string_view>
+
+#include "services/wikipedia_service.h"
+
+std::string WikipediaService::FetchExtract(std::string_view query) {
+   const std::string cache_key(query);
+   const auto cache_it = this->extract_cache_.find(cache_key);
+   if (cache_it != this->extract_cache_.end()) {
+      return cache_it->second;
+   }
+
+   const std::string encoded = this->client_->UrlEncode(cache_key);
+   const std::string url =
+       "https://en.wikipedia.org/w/api.php?action=query&titles=" + encoded +
+       "&prop=extracts&explaintext=1&format=json";
+
+   const std::string body = this->client_->Get(url);
+
+   boost::system::error_code parse_error;
+   boost::json::value doc = boost::json::parse(body, parse_error);
+
+   if (!parse_error && doc.is_object()) {
+      try {
+         auto& pages = doc.at("query").at("pages").get_object();
+         if (!pages.empty()) {
+            auto& page = pages.begin()->value().get_object();
+            if (page.contains("extract") && page.at("extract").is_string()) {
+               std::string extract(page.at("extract").as_string().c_str());
+               spdlog::debug("WikipediaService fetched {} chars for '{}'",
+                             extract.size(), query);
+               this->extract_cache_.emplace(cache_key, extract);
+               return extract;
+            }
+         }
+         this->extract_cache_.emplace(cache_key, std::string{});
+      } catch (const std::exception& e) {
+         spdlog::warn(
+             "WikipediaService: failed to parse response structure for '{}': "
+             "{}",
+             query, e.what());
+         return {};
+      }
+   } else if (parse_error) {
+      spdlog::warn("WikipediaService: JSON parse error for '{}': {}", query,
+                   parse_error.message());
+   }
+
+   return {};
+}

pipeline/src/services/wikipedia/get_summary.cpp

@@ -0,0 +1,56 @@
+/**
+ * @file wikipedia/get_summary.cpp
+ * @brief WikipediaService::GetLocationContext() implementation.
+ */
+
+#include <spdlog/spdlog.h>
+
+#include <string>
+
+#include "services/wikipedia_service.h"
+
+std::string WikipediaService::GetLocationContext(const Location& loc) {
+   const std::string cache_key = loc.city + "|" + loc.country;
+   const auto cache_it = cache_.find(cache_key);
+   if (cache_it != cache_.end()) {
+      return cache_it->second;
+   }
+
+   std::string result;
+
+   if (!client_) {
+      cache_.emplace(cache_key, result);
+      return result;
+   }
+
+   std::string region_query(loc.city);
+   if (!loc.country.empty()) {
+      region_query += ", ";
+      region_query += loc.country;
+   }
+
+   const std::string beer_query = "beer in " + loc.country;
+   const std::string city_beer_query = "beer in " + loc.city;
+
+   auto append_extract = [&result](const std::string& extract) -> void {
+      if (extract.empty()) {
+         return;
+      }
+      if (!result.empty()) {
+         result += "\n\n";
+      }
+      result += extract;
+   };
+
+   try {
+      append_extract(FetchExtract(region_query));
+      append_extract(FetchExtract(beer_query));
+      append_extract(FetchExtract(city_beer_query));
+   } catch (const std::runtime_error& e) {
+      spdlog::debug("WikipediaService lookup failed for '{}': {}", region_query,
+                    e.what());
+   }
+
+   cache_.emplace(cache_key, result);
+   return result;
+}

pipeline/src/services/wikipedia/wikipedia_service.cpp

@@ -0,0 +1,11 @@
+/**
+ * @file services/wikipedia/wikipedia_service.cpp
+ * @brief WikipediaService constructor implementation.
+ */
+
+#include "services/wikipedia_service.h"
+
+#include <utility>
+
+WikipediaService::WikipediaService(std::shared_ptr<WebClient> client)
+    : client_(std::move(client)) {}

pipeline/src/web_client/curl_global_state.cpp

@@ -0,0 +1,19 @@
+/**
+ * @file web_client/curl_global_state.cpp
+ * @brief CurlGlobalState constructor and destructor implementation.
+ */
+
+#include <curl/curl.h>
+
+#include <stdexcept>
+
+#include "web_client/curl_web_client.h"
+
+CurlGlobalState::CurlGlobalState() {
+   if (curl_global_init(CURL_GLOBAL_DEFAULT) != CURLE_OK) {
+      throw std::runtime_error(
+          "[CURLWebClient] Failed to initialize libcurl globally");
+   }
+}
+
+CurlGlobalState::~CurlGlobalState() { curl_global_cleanup(); }

pipeline/src/web_client/curl_web_client_get.cpp

@@ -0,0 +1,50 @@
+/**
+ * @file web_client/curl_web_client_get.cpp
+ * @brief CURLWebClient::Get() implementation.
+ */
+
+#include <curl/curl.h>
+
+#include <sstream>
+#include <stdexcept>
+#include <string>
+
+#include "curl_web_client_utils.h"
+#include "web_client/curl_web_client.h"
+
+// curl write callback that appends response data into a std::string
+static size_t WriteCallbackString(void* contents, size_t size, size_t nmemb,
+                                  void* userp) {
+   size_t realsize = size * nmemb;
+   auto* s = static_cast<std::string*>(userp);
+   s->append(static_cast<char*>(contents), realsize);
+   return realsize;
+}
+
+std::string CURLWebClient::Get(const std::string& url) {
+   auto curl = create_handle();
+
+   std::string response_string;
+   set_common_get_options(curl.get(), url, {10L, 20L});
+   curl_easy_setopt(curl.get(), CURLOPT_WRITEFUNCTION, WriteCallbackString);
+   curl_easy_setopt(curl.get(), CURLOPT_WRITEDATA, &response_string);
+
+   CURLcode res = curl_easy_perform(curl.get());
+
+   if (res != CURLE_OK) {
+      std::string error =
+          std::string("[CURLWebClient] GET failed: ") + curl_easy_strerror(res);
+      throw std::runtime_error(error);
+   }
+
+   long httpCode = 0;
+   curl_easy_getinfo(curl.get(), CURLINFO_RESPONSE_CODE, &httpCode);
+
+   if (httpCode != 200) {
+      std::stringstream ss;
+      ss << "[CURLWebClient] HTTP error " << httpCode << " for URL " << url;
+      throw std::runtime_error(ss.str());
+   }
+
+   return response_string;
+}

pipeline/src/web_client/curl_web_client_url_encode.cpp

@@ -0,0 +1,23 @@
+/**
+ * @file web_client/curl_web_client_url_encode.cpp
+ * @brief CURLWebClient::UrlEncode() implementation.
+ */
+
+#include <curl/curl.h>
+
+#include <stdexcept>
+#include <string>
+
+#include "web_client/curl_web_client.h"
+
+std::string CURLWebClient::UrlEncode(const std::string& value) {
+   // A NULL handle is fine for UTF-8 encoding according to libcurl docs.
+   char* output = curl_easy_escape(nullptr, value.c_str(), 0);
+
+   if (output) {
+      std::string result(output);
+      curl_free(output);
+      return result;
+   }
+   throw std::runtime_error("[CURLWebClient] curl_easy_escape failed");
+}

pipeline/src/web_client/curl_web_client_utils.cpp

@@ -0,0 +1,28 @@
+/**
+ * @file web_client/curl_web_client_utils.cpp
+ * @brief Shared CURLWebClient helper implementations.
+ */
+
+#include "curl_web_client_utils.h"
+
+#include <stdexcept>
+
+CurlHandle create_handle() {
+   CURL* handle = curl_easy_init();
+   if (handle == nullptr) {
+      throw std::runtime_error(
+          "[CURLWebClient] Failed to initialize libcurl handle");
+   }
+   return CurlHandle(handle, &curl_easy_cleanup);
+}
+
+void set_common_get_options(CURL* curl, const std::string& url,
+                            CurlTimeouts timeouts) {
+   curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
+   curl_easy_setopt(curl, CURLOPT_USERAGENT, "biergarten-pipeline/0.1.0");
+   curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
+   curl_easy_setopt(curl, CURLOPT_MAXREDIRS, 5L);
+   curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT, timeouts.connect_timeout);
+   curl_easy_setopt(curl, CURLOPT_TIMEOUT, timeouts.total_timeout);
+   curl_easy_setopt(curl, CURLOPT_ACCEPT_ENCODING, "gzip");
+}

pipeline/src/web_client/curl_web_client_utils.h

@@ -0,0 +1,26 @@
+#ifndef BIERGARTEN_PIPELINE_SRC_WEB_CLIENT_CURL_WEB_CLIENT_UTILS_H_
+#define BIERGARTEN_PIPELINE_SRC_WEB_CLIENT_CURL_WEB_CLIENT_UTILS_H_
+
+/**
+ * @file web_client/curl_web_client_utils.h
+ * @brief Shared helpers for CURLWebClient request setup.
+ */
+
+#include <curl/curl.h>
+
+#include <memory>
+#include <string>
+
+using CurlHandle = std::unique_ptr<CURL, decltype(&curl_easy_cleanup)>;
+
+struct CurlTimeouts {
+   long connect_timeout;
+   long total_timeout;
+};
+
+CurlHandle create_handle();
+
+void set_common_get_options(CURL* curl, const std::string& url,
+                            CurlTimeouts timeouts);
+
+#endif  // BIERGARTEN_PIPELINE_SRC_WEB_CLIENT_CURL_WEB_CLIENT_UTILS_H_

src/Core/.dockerignore

@@ -0,0 +1,25 @@
+**/.dockerignore
+**/.env
+**/.git
+**/.gitignore
+**/.project
+**/.settings
+**/.toolstarget
+**/.vs
+**/.vscode
+**/.idea
+**/*.*proj.user
+**/*.dbmdl
+**/*.jfm
+**/azds.yaml
+**/bin
+**/charts
+**/docker-compose*
+**/Dockerfile*
+**/node_modules
+**/npm-debug.log
+**/obj
+**/secrets.dev.yaml
+**/values.dev.yaml
+LICENSE
+README.md

src/Core/API/API.Core/API.Core.csproj

@@ -0,0 +1,42 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+    <PropertyGroup>
+        <TargetFramework>net10.0</TargetFramework>
+        <Nullable>enable</Nullable>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <RootNamespace>API.Core</RootNamespace>
+        <DockerDefaultTargetOS>Linux</DockerDefaultTargetOS>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <PackageReference
+            Include="Microsoft.AspNetCore.OpenApi"
+            Version="9.0.11"
+        />
+        <PackageReference Include="Swashbuckle.AspNetCore" Version="6.6.2" />
+        <PackageReference
+            Include="FluentValidation.AspNetCore"
+            Version="11.3.0"
+        />
+    </ItemGroup>
+
+    <ItemGroup>
+        <Folder Include="Infrastructure\" />
+    </ItemGroup>
+
+    <ItemGroup>
+        <ProjectReference Include="..\..\Domain\Domain.Entities\Domain.Entities.csproj" />
+        <ProjectReference Include="..\..\Domain\Domain.Exceptions\Domain.Exceptions.csproj" />
+        <ProjectReference Include="..\..\Infrastructure\Infrastructure.Email\Infrastructure.Email.csproj" />
+        <ProjectReference Include="..\..\Infrastructure\Infrastructure.Email.Templates\Infrastructure.Email.Templates.csproj" />
+        <ProjectReference Include="..\..\Infrastructure\Infrastructure.Repository\Infrastructure.Repository.csproj" />
+        <ProjectReference Include="..\..\Infrastructure\Infrastructure.Jwt\Infrastructure.Jwt.csproj" />
+        <ProjectReference Include="..\..\Service\Service.Auth\Service.Auth.csproj" />
+        <ProjectReference Include="..\..\Service\Service.UserManagement\Service.UserManagement.csproj" />
+    </ItemGroup>
+
+    <ItemGroup>
+        <Content Include="..\..\.dockerignore">
+            <Link>.dockerignore</Link>
+        </Content>
+    </ItemGroup>
+</Project>

src/Core/API/API.Core/Authentication/JwtAuthenticationHandler.cs

@@ -0,0 +1,86 @@
+using System.Security.Claims;
+using System.Text.Encodings.Web;
+using System.Text.Json;
+using API.Core.Contracts.Common;
+using Infrastructure.Jwt;
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.Extensions.Options;
+
+namespace API.Core.Authentication;
+
+public class JwtAuthenticationHandler(
+    IOptionsMonitor<JwtAuthenticationOptions> options,
+    ILoggerFactory logger,
+    UrlEncoder encoder,
+    ITokenInfrastructure tokenInfrastructure,
+    IConfiguration configuration
+) : AuthenticationHandler<JwtAuthenticationOptions>(options, logger, encoder)
+{
+    protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
+    {
+        // Use the same access-token secret source as TokenService to avoid mismatched validation.
+        var secret = Environment.GetEnvironmentVariable("ACCESS_TOKEN_SECRET");
+        if (string.IsNullOrWhiteSpace(secret))
+        {
+            secret = configuration["Jwt:SecretKey"];
+        }
+
+        if (string.IsNullOrWhiteSpace(secret))
+        {
+            return AuthenticateResult.Fail("JWT secret is not configured");
+        }
+
+        // Check if Authorization header exists
+        if (
+            !Request.Headers.TryGetValue(
+                "Authorization",
+                out var authHeaderValue
+            )
+        )
+        {
+            return AuthenticateResult.Fail("Authorization header is missing");
+        }
+
+        var authHeader = authHeaderValue.ToString();
+        if (
+            !authHeader.StartsWith(
+                "Bearer ",
+                StringComparison.OrdinalIgnoreCase
+            )
+        )
+        {
+            return AuthenticateResult.Fail(
+                "Invalid authorization header format"
+            );
+        }
+
+        var token = authHeader.Substring("Bearer ".Length).Trim();
+
+        try
+        {
+            var claimsPrincipal = await tokenInfrastructure.ValidateJwtAsync(
+                token,
+                secret
+            );
+            var ticket = new AuthenticationTicket(claimsPrincipal, Scheme.Name);
+            return AuthenticateResult.Success(ticket);
+        }
+        catch (Exception ex)
+        {
+            return AuthenticateResult.Fail(
+                $"Token validation failed: {ex.Message}"
+            );
+        }
+    }
+
+    protected override async Task HandleChallengeAsync(AuthenticationProperties properties)
+    {
+        Response.ContentType = "application/json";
+        Response.StatusCode = 401;
+
+        var response = new ResponseBody { Message = "Unauthorized: Invalid or missing authentication token" };
+        await Response.WriteAsJsonAsync(response);
+    }
+}
+
+public class JwtAuthenticationOptions : AuthenticationSchemeOptions { }

src/Core/API/API.Core/Contracts/Auth/AuthDTO.cs

@@ -0,0 +1,21 @@
+using Domain.Entities;
+using Org.BouncyCastle.Asn1.Cms;
+
+namespace API.Core.Contracts.Auth;
+
+public record LoginPayload(
+    Guid UserAccountId,
+    string Username,
+    string RefreshToken,
+    string AccessToken
+);
+
+public record RegistrationPayload(
+    Guid UserAccountId,
+    string Username,
+    string RefreshToken,
+    string AccessToken,
+    bool ConfirmationEmailSent
+);
+
+public record ConfirmationPayload(Guid UserAccountId, DateTime ConfirmedDate);

src/Core/API/API.Core/Contracts/Auth/Login.cs

@@ -0,0 +1,20 @@
+using API.Core.Contracts.Common;
+using FluentValidation;
+
+namespace API.Core.Contracts.Auth;
+
+public record LoginRequest
+{
+    public string Username { get; init; } = default!;
+    public string Password { get; init; } = default!;
+}
+
+public class LoginRequestValidator : AbstractValidator<LoginRequest>
+{
+    public LoginRequestValidator()
+    {
+        RuleFor(x => x.Username).NotEmpty().WithMessage("Username is required");
+
+        RuleFor(x => x.Password).NotEmpty().WithMessage("Password is required");
+    }
+}

src/Core/API/API.Core/Contracts/Auth/RefreshToken.cs

@@ -0,0 +1,19 @@
+using FluentValidation;
+
+namespace API.Core.Contracts.Auth;
+
+public record RefreshTokenRequest
+{
+    public string RefreshToken { get; init; } = default!;
+}
+
+public class RefreshTokenRequestValidator
+    : AbstractValidator<RefreshTokenRequest>
+{
+    public RefreshTokenRequestValidator()
+    {
+        RuleFor(x => x.RefreshToken)
+            .NotEmpty()
+            .WithMessage("Refresh token is required");
+    }
+}

src/Core/API/API.Core/Contracts/Auth/Register.cs

@@ -0,0 +1,71 @@
+using API.Core.Contracts.Common;
+using FluentValidation;
+
+namespace API.Core.Contracts.Auth;
+
+public record RegisterRequest(
+    string Username,
+    string FirstName,
+    string LastName,
+    string Email,
+    DateTime DateOfBirth,
+    string Password
+);
+
+public class RegisterRequestValidator : AbstractValidator<RegisterRequest>
+{
+    public RegisterRequestValidator()
+    {
+        RuleFor(x => x.Username)
+            .NotEmpty()
+            .WithMessage("Username is required")
+            .Length(3, 64)
+            .WithMessage("Username must be between 3 and 64 characters")
+            .Matches("^[a-zA-Z0-9._-]+$")
+            .WithMessage(
+                "Username can only contain letters, numbers, dots, underscores, and hyphens"
+            );
+
+        RuleFor(x => x.FirstName)
+            .NotEmpty()
+            .WithMessage("First name is required")
+            .MaximumLength(128)
+            .WithMessage("First name cannot exceed 128 characters");
+
+        RuleFor(x => x.LastName)
+            .NotEmpty()
+            .WithMessage("Last name is required")
+            .MaximumLength(128)
+            .WithMessage("Last name cannot exceed 128 characters");
+
+        RuleFor(x => x.Email)
+            .NotEmpty()
+            .WithMessage("Email is required")
+            .EmailAddress()
+            .WithMessage("Invalid email format")
+            .MaximumLength(128)
+            .WithMessage("Email cannot exceed 128 characters");
+
+        RuleFor(x => x.DateOfBirth)
+            .NotEmpty()
+            .WithMessage("Date of birth is required")
+            .LessThan(DateTime.Today.AddYears(-19))
+            .WithMessage("You must be at least 19 years old to register");
+
+        RuleFor(x => x.Password)
+            .NotEmpty()
+            .WithMessage("Password is required")
+            .MinimumLength(8)
+            .WithMessage("Password must be at least 8 characters")
+            .Matches("[A-Z]")
+            .WithMessage("Password must contain at least one uppercase letter")
+            .Matches("[a-z]")
+            .WithMessage("Password must contain at least one lowercase letter")
+            .Matches("[0-9]")
+            .WithMessage("Password must contain at least one number")
+            .Matches("[^a-zA-Z0-9]")
+            .WithMessage(
+                "Password must contain at least one special character"
+            );
+    }
+}

src/Core/API/API.Core/Contracts/Common/ResponseBody.cs

@@ -0,0 +1,12 @@
+namespace API.Core.Contracts.Common;
+
+public record ResponseBody<T>
+{
+    public required string Message { get; init; }
+    public required T Payload { get; init; }
+}
+
+public record ResponseBody
+{
+    public required string Message { get; init; }
+}

src/Core/API/API.Core/Controllers/AuthController.cs

@@ -0,0 +1,111 @@
+using API.Core.Contracts.Auth;
+using API.Core.Contracts.Common;
+using Domain.Entities;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using Service.Auth;
+
+namespace API.Core.Controllers
+{
+    [ApiController]
+    [Route("api/[controller]")]
+    [Authorize(AuthenticationSchemes = "JWT")]
+    public class AuthController(
+        IRegisterService registerService,
+        ILoginService loginService,
+        IConfirmationService confirmationService,
+        ITokenService tokenService
+    ) : ControllerBase
+    {
+        [AllowAnonymous]
+        [HttpPost("register")]
+        public async Task<ActionResult<UserAccount>> Register(
+            [FromBody] RegisterRequest req
+        )
+        {
+            var rtn = await registerService.RegisterAsync(
+                new UserAccount
+                {
+                    UserAccountId = Guid.Empty,
+                    Username = req.Username,
+                    FirstName = req.FirstName,
+                    LastName = req.LastName,
+                    Email = req.Email,
+                    DateOfBirth = req.DateOfBirth,
+                },
+                req.Password
+            );
+
+            var response = new ResponseBody<RegistrationPayload>
+            {
+                Message = "User registered successfully.",
+                Payload = new RegistrationPayload(
+                    rtn.UserAccount.UserAccountId,
+                    rtn.UserAccount.Username,
+                    rtn.RefreshToken,
+                    rtn.AccessToken,
+                    rtn.EmailSent
+                ),
+            };
+            return Created("/", response);
+        }
+
+        [AllowAnonymous]
+        [HttpPost("login")]
+        public async Task<ActionResult> Login([FromBody] LoginRequest req)
+        {
+            var rtn = await loginService.LoginAsync(req.Username, req.Password);
+
+            return Ok(
+                new ResponseBody<LoginPayload>
+                {
+                    Message = "Logged in successfully.",
+                    Payload = new LoginPayload(
+                        rtn.UserAccount.UserAccountId,
+                        rtn.UserAccount.Username,
+                        rtn.RefreshToken,
+                        rtn.AccessToken
+                    ),
+                }
+            );
+        }
+
+        [HttpPost("confirm")]
+        public async Task<ActionResult> Confirm([FromQuery] string token)
+        {
+            var rtn = await confirmationService.ConfirmUserAsync(token);
+            return Ok(
+                new ResponseBody<ConfirmationPayload>
+                {
+                    Message = "User with ID " + rtn.UserId + " is confirmed.",
+                    Payload = new ConfirmationPayload(
+                        rtn.UserId,
+                        rtn.ConfirmedAt
+                    ),
+                }
+            );
+        }
+
+        [AllowAnonymous]
+        [HttpPost("refresh")]
+        public async Task<ActionResult> Refresh(
+            [FromBody] RefreshTokenRequest req
+        )
+        {
+            var rtn = await tokenService.RefreshTokenAsync(req.RefreshToken);
+
+            return Ok(
+                new ResponseBody<LoginPayload>
+                {
+                    Message = "Token refreshed successfully.",
+                    Payload = new LoginPayload(
+                        rtn.UserAccount.UserAccountId,
+                        rtn.UserAccount.Username,
+                        rtn.RefreshToken,
+                        rtn.AccessToken
+                    ),
+                }
+            );
+        }
+    }
+}

src/Core/API/API.Core/Controllers/NotFoundController.cs

@@ -0,0 +1,16 @@
+using Microsoft.AspNetCore.Mvc;
+
+namespace API.Core.Controllers
+{
+    [ApiController]
+    [ApiExplorerSettings(IgnoreApi = true)]
+    [Route("error")] // required
+    public class NotFoundController : ControllerBase
+    {
+        [HttpGet("404")] //required
+        public IActionResult Handle404()
+        {
+            return NotFound(new { message = "Route not found." });
+        }
+    }
+}

src/Core/API/API.Core/Controllers/ProtectedController.cs

@@ -0,0 +1,27 @@
+using System.Security.Claims;
+using API.Core.Contracts.Common;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+
+namespace API.Core.Controllers;
+
+[ApiController]
+[Route("api/[controller]")]
+[Authorize(AuthenticationSchemes = "JWT")]
+public class ProtectedController : ControllerBase
+{
+    [HttpGet]
+    public ActionResult<ResponseBody<object>> Get()
+    {
+        var userId = User.FindFirst(ClaimTypes.NameIdentifier)?.Value;
+        var username = User.FindFirst(ClaimTypes.Name)?.Value;
+
+        return Ok(
+            new ResponseBody<object>
+            {
+                Message = "Protected endpoint accessed successfully",
+                Payload = new { userId, username },
+            }
+        );
+    }
+}

src/Core/API/API.Core/Controllers/UserController.cs

@@ -0,0 +1,28 @@
+using Domain.Entities;
+using Microsoft.AspNetCore.Mvc;
+using Service.UserManagement.User;
+
+namespace API.Core.Controllers
+{
+    [ApiController]
+    [Route("api/[controller]")]
+    public class UserController(IUserService userService) : ControllerBase
+    {
+        [HttpGet]
+        public async Task<ActionResult<IEnumerable<UserAccount>>> GetAll(
+            [FromQuery] int? limit,
+            [FromQuery] int? offset
+        )
+        {
+            var users = await userService.GetAllAsync(limit, offset);
+            return Ok(users);
+        }
+
+        [HttpGet("{id:guid}")]
+        public async Task<ActionResult<UserAccount>> GetById(Guid id)
+        {
+            var user = await userService.GetByIdAsync(id);
+            return Ok(user);
+        }
+    }
+}

src/Core/API/API.Core/Dockerfile

@@ -0,0 +1,32 @@
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
+ARG APP_UID=1000
+USER $APP_UID
+WORKDIR /app
+EXPOSE 8080
+EXPOSE 8081
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+ARG BUILD_CONFIGURATION=Release
+WORKDIR /src
+COPY ["API/API.Core/API.Core.csproj", "API/API.Core/"]
+COPY ["Domain/Domain.Entities/Domain.Entities.csproj", "Domain.Entities/"]
+COPY ["Domain/Domain.Exceptions/Domain.Exceptions.csproj", "Domain.Exceptions/"]
+COPY ["Infrastructure/Infrastructure.Repository/Infrastructure.Repository.csproj", "Infrastructure/Infrastructure.Repository/"]
+COPY ["Infrastructure/Infrastructure.Jwt/Infrastructure.Jwt.csproj", "Infrastructure/Infrastructure.Jwt/"]
+COPY ["Infrastructure/Infrastructure.PasswordHashing/Infrastructure.PasswordHashing.csproj", "Infrastructure/Infrastructure.PasswordHashing/"]
+COPY ["Infrastructure/Infrastructure.Email/Infrastructure.Email.csproj", "Infrastructure/Infrastructure.Email/"]
+COPY ["Service/Service.Auth/Service.Auth.csproj", "Service/Service.Auth/"]
+COPY ["Service/Service.UserManagement/Service.UserManagement.csproj", "Service/Service.UserManagement/"]
+RUN dotnet restore "API/API.Core/API.Core.csproj"
+COPY . .
+WORKDIR "/src/API/API.Core"
+RUN dotnet build "./API.Core.csproj" -c $BUILD_CONFIGURATION -o /app/build
+
+FROM build AS publish
+ARG BUILD_CONFIGURATION=Release
+RUN dotnet publish "./API.Core.csproj" -c $BUILD_CONFIGURATION -o /app/publish /p:UseAppHost=false
+
+FROM base AS final
+WORKDIR /app
+COPY --from=publish /app/publish .
+ENTRYPOINT ["dotnet", "API.Core.dll"]