Persist generated users to SQLite and code cleanup

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

@@ -13,6 +13,7 @@ low-resource language failures.
 - [Model Bias and Language Quality](#model-bias-and-language-quality)
 - [Western and Eurocentric Lens](#western-and-eurocentric-lens)
 - [Wikipedia Enrichment](#wikipedia-enrichment)
+- [Names-by-Country Dataset](#names-by-country-dataset)
 - [The "Avoid AI Phrases" Prompt Instruction](#the-avoid-ai-phrases-prompt-instruction)
 - [Known Issues](#known-issues)
   - [Hallucinated Brewing Techniques](#hallucinated-brewing-techniques)
@@ -91,6 +92,33 @@ generated descriptions.
 
 ---
 
+## Names-by-Country Dataset
+
+`tooling/pipeline/forenames-by-country.json` and `surnames-by-country.json`
+(used to sample a `Name` per ISO 3166-1 country code for user generation) are
+vendored verbatim, unmodified, from
+[sigpwned/popular-names-by-country-dataset](https://github.com/sigpwned/popular-names-by-country-dataset)
+(the `common-forenames-by-country.json` / `common-surnames-by-country.json`
+release assets), released under **CC0** (public domain). That dataset's own
+forename/surname lists are pulled from Wikipedia's "Lists of most common
+surnames" and "List of most popular given names" as of the week of
+2023-07-08 — see that project's README for full provenance. Names are not
+LLM-generated; this is curated fixture data per ROADMAP.md §2. Per-forename
+gender from the source data is preserved through to the sampled `Name`
+(rather than discarded during loading) so it's available for gender-aware
+persona/bio generation later.
+
+The full multinational dataset is kept as-is (106 countries for forenames,
+75 for surnames) rather than trimmed to `locations.json`'s current country
+list, so it doesn't need re-sourcing if more countries are added later.
+`NamesByCountry::SampleName()` returns no result for a country present in
+neither file; of the countries in `locations.json`, that's currently `KE`,
+`SE`, `SG`, `TH`, `VN`, and `ZA` — `GenerateUsers` skips cities in those
+countries the same way brewery generation skips cities whose enrichment
+lookup fails.
+
+---
+
 ## The "Avoid AI Phrases" Prompt Instruction
 
 The system prompt instructs the model to avoid common AI-generated phrasing
@@ -245,7 +273,7 @@ but is semantically incoherent. This comes from limited training-data coverage
 rather than prompt engineering.
 
 Output sample:
-[./out-sample/french-cities.example](out-sample/french-cities.example)
+[./french-cities.example](french-cities.example)
 
 #### Proposed Mitigations
 

docs/pipeline/README.md

@@ -94,23 +94,26 @@ Each run writes a fresh dated SQLite file such as
 ./biergarten-pipeline \
   --model ../models/google_gemma-4-E4B-it-Q6_K.gguf \
   --prompt-dir prompts \
+  --location-count 25 \
   --temperature 1.0 --top-p 0.95 --top-k 64 --n-ctx 8192 --seed -1
 ```
 
 #### CLI Flags
 
 | Flag               | Purpose                                                                                              |
-| --------------- | ---------------------------------------------------------------------------------------------------- |
+| ------------------ | ---------------------------------------------------------------------------------------------------- |
 | `--mocked`         | Deterministic mock generator, no model required.                                                     |
 | `--model, -m`      | Path to a GGUF file. Required unless `--mocked` is set.                                              |
 | `--prompt-dir`     | Directory containing prompt files (e.g. `BREWERY_GENERATION.md`). Required unless `--mocked` is set. |
 | `--output, -o`     | Directory for generated SQLite artifacts. Default: `output`.                                         |
 | `--log-path`       | Path for application logs. Default: `pipeline.log`.                                                  |
+| `--location-count` | Number of cities to sample from `locations.json` per run. Default: `10`.                             |
 | `--temperature`    | Sampling temperature. Default: `1.0`.                                                                |
 | `--top-p`          | Nucleus sampling. Default: `0.95`.                                                                   |
 | `--top-k`          | Top-k sampling. Default: `64`.                                                                       |
 | `--n-ctx`          | Context window size. Default: `8192`.                                                                |
 | `--seed`           | Random seed. Default: `-1` (random at runtime).                                                      |
+| `--n-gpu-layers`   | Number of model layers to offload to GPU. Default: `0`.                                              |
 | `--help, -h`       | Print usage and exit.                                                                                |
 
 `--mocked` and `--model` are mutually exclusive. Omitting both exits with an
@@ -130,17 +133,20 @@ NVIDIA GPU.
 
 ### How it works
 
-The container uses a two-stage build. The first stage pulls prebuilt
+The container uses a two-stage build. The builder stage installs CMake/Ninja,
-`libllama`, `libggml`, and backend plugin libraries (including `libggml-cuda.so`
+clones the matching llama.cpp release tag for its headers only (installed into
-and the CPU variant plugins) from `ghcr.io/ggml-org/llama.cpp:full-cuda`. The
+`/usr/local/include`), and copies prebuilt shared libraries (`libllama`,
-second stage copies those libraries into `/usr/local/lib` and runs `ldconfig` so
+`libggml`, and CUDA/CPU backend plugins) from `ghcr.io/ggml-org/llama.cpp:full-cuda`
-the dynamic linker and `dlopen` calls from `ggml_backend_load_all()` can resolve
+into `/usr/local/lib`. With both headers and libraries present, CMake's
-the CUDA backend plugin at runtime. llama.cpp headers are cloned at the matching
+system-library detection (see [Build](#build) above) finds them and skips the
-tag and installed into `/usr/local/include`. CMake auto-detects both and skips
+FetchContent source build, keeping image build times short.
-the FetchContent source build entirely, keeping image build times short.
 
-`GGML_BACKEND_PATH` is set to `/usr/local/lib` so llama.cpp knows where to scan
+The runtime stage copies the compiled binary, the same prebuilt shared
-for backend plugins.
+libraries, and config/prompt assets into a slim CUDA runtime image. It sets
+`LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH` so the dynamic linker
+resolves `libllama`/`libggml` at startup, and also co-locates
+`libggml-cuda.so` and the CPU backend plugins next to the binary for
+`ggml_backend_load_all()`'s `dlopen` scan.
 
 ### Build the image
 
@@ -165,44 +171,46 @@ docker build \
 Look for `[biergarten] Found system llama.cpp — skipping FetchContent` in the
 output to confirm the fast path was taken.
 
-### Run in mocked mode
+### Run the container
 
-No model or GPU required. Useful for validating the pipeline logic and SQLite
+The container always runs the model-backed path; there is no `--mocked`
-export path.
+container mode (use a native build for that — see [Quick Start](#quick-start)).
-
+The entrypoint, `runpod/start.sh`, downloads the GGUF model automatically if
-```bash
+it is not already present at the configured path.
-docker run --rm \
-  -e BIERGARTEN_MODE=mocked \
-  -v "$PWD/output:/workspace/output" \
-  -v "$PWD/logs:/workspace/logs" \
-  biergarten-pipeline:latest
-```
-
-### Run in live mode
-
-Mount your GGUF model before starting. The container validates the model path
-before launching the binary.
 
 ```bash
 docker run --rm \
   --runtime=nvidia \
-  -e BIERGARTEN_MODE=live \
-  -e GGML_BACKEND_PATH="/usr/local/lib/libggml-cuda.so" \
   -v "$PWD/models:/workspace/models" \
   -v "$PWD/output:/workspace/output" \
   -v "$PWD/logs:/workspace/logs" \
   biergarten-pipeline:latest
 ```
 
-The model must be present at `./models/google_gemma-4-E4B-it-Q6_K.gguf` on the
+By default this downloads `google_gemma-4-E4B-it-Q6_K.gguf` to
-host. See [Model](#model) above for the download command.
+`./models/` on first run if it isn't already there. To use a pre-downloaded
+model, place it at that path first — see [Model](#model) above.
+
+#### Environment variables
+
+| Variable                 | Purpose                                                          |
+| ------------------------- | ----------------------------------------------------------------- |
+| `BIERGARTEN_MODEL_PATH`   | GGUF model path. Default: `/workspace/models/google_gemma-4-E4B-it-Q6_K.gguf`. |
+| `BIERGARTEN_OUTPUT_DIR`   | SQLite output directory. Default: `/workspace/output`.            |
+| `BIERGARTEN_LOG_PATH`     | Log file path. Default: `/workspace/logs/pipeline.log`.           |
+| `BIERGARTEN_GL_LAYERS`    | GPU layers to offload (`--n-gpu-layers`). Default: `40`.          |
+| `BIERGARTEN_TEMPERATURE`, `BIERGARTEN_TOP_P`, `BIERGARTEN_TOP_K`, `BIERGARTEN_N_CTX`, `BIERGARTEN_SEED` | Optional sampling overrides, unset by default (binary defaults apply). |
+| `BIERGARTEN_EXTRA_ARGS`   | Additional raw CLI args appended verbatim.                       |
+
+`--prompt-dir` is hardcoded to `/app/prompts` inside the container and is not
+configurable via environment variable.
 
 ### RunPod deployment
 
 Use a GPU pod template. Mount persistent storage for `/workspace/models`,
-`/workspace/output`, and `/workspace/logs`. Set `BIERGARTEN_MODE=live` in the
+`/workspace/output`, and `/workspace/logs`. See
-template environment. See `tooling/pipeline/runpod/pod-template.yaml` for a
+`tooling/pipeline/runpod/pod-template.yaml` for a starter template — set the
-starter template.
+environment variables listed above to match your run.
 
 ---
 
@@ -213,8 +221,8 @@ starter template.
 | Stage    | Implementation                                                                                                                          |
 | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
 | Load     | `JsonLoader::LoadLocations()` reads `locations.json` into typed `Location` records.                                                     |
-| Sample   | `BiergartenDataGenerator::QueryCitiesWithCountries()` samples up to 50 locations per run.                                               |
+| Sample   | `BiergartenPipelineOrchestrator::QueryCitiesWithCountries()` samples `--location-count` locations per run (default `10`).               |
-| Enrich   | `WikipediaService` fetches city and beer context. Keeps going when a lookup fails.                                                      |
+| Enrich   | `WikipediaEnrichmentService` fetches brewing and beer-related context. Keeps going when a lookup fails. `--mocked` runs use `MockEnrichmentService` instead and skip Wikipedia entirely. |
 | Generate | `MockGenerator` or `LlamaGenerator` produces brewery names and descriptions in English and the local language.                          |
 | Store    | `SqliteExportService` writes each successful brewery into a fresh dated `.sqlite` database with normalized location and brewery tables. |
 | Log      | `spdlog` writes results and warnings to the console.                                                                                    |
@@ -226,11 +234,13 @@ pipeline continues.
 
 - `src/main.cc` — argument parsing and Boost.DI composition root.
 - `JsonLoader` — validates curated location input.
-- `WikipediaService` — queries Wikipedia extracts, caches results, returns empty
+- `WikipediaEnrichmentService` — queries Wikipedia extracts, caches results,
-  context on failure.
+  returns empty context on failure. `MockEnrichmentService` is the no-op
+  substitute used in `--mocked` runs.
 - `LlamaGenerator` — formats prompts for Gemma 4, validates JSON output, retries
-  malformed responses up to three times. If output looks truncated, the retry
+  malformed responses up to three times with corrective feedback in the
-  raises the token budget before trying again.
+  retry prompt. The token budget is fixed across attempts; it is not raised
+  automatically on truncation.
 - `MockGenerator` — stable hash-based output so the same city input always
   produces the same brewery.
 - `SqliteExportService` — creates a dated SQLite file per run and persists each
@@ -240,18 +250,18 @@ pipeline continues.
 
 ### Runtime Behaviour
 
-`WikipediaService` queries city, country, and beer-related Wikipedia extracts
+`WikipediaEnrichmentService` fetches two Wikipedia extracts per city: a
-using its configured lookup, then caches the first successful response per query
+generic "brewing" extract and a "beer in `{country}`" extract. It does not
-string. The fetched extract text is included in the prompt as context for
+currently query a city- or region-specific page. Each query string is cached
-generation.
+after its first successful (or empty) lookup.
 
 `GetLocationContext()` returns an empty string when the web client is
 unavailable or when lookup/parsing fails.
 
-`LlamaGenerator` validates model output as structured JSON. The retry path
+`LlamaGenerator` validates model output as structured JSON. On validation
-exists as a safety hatch for cases where the reasoning block consumes available
+failure it retries up to three times, replaying the previous error message in
-token budget and compresses the JSON output space. All runs to date have
+the next prompt so the model can self-correct. All runs to date have produced
-produced valid output on the first pass; the path is kept for resilience.
+valid output on the first pass; the retry path is kept for resilience.
 
 `MockGenerator` uses stable hashes for repeatable output in demos and Storybook
 runs.
@@ -292,7 +302,6 @@ code, latitude, and longitude for each entry.
 | `local_languages`                   | Locale-aware copy selection                      |
 | `name_en`, `description_en`         | Default English display content                  |
 | `name_local`, `description_local`   | Local-language display content                   |
-| `region_context`                    | Richer copy for cards and detail pages           |
 
 ---
 
@@ -369,28 +378,30 @@ Silicon; CUDA or HIP/ROCm is detected on Linux when the toolkit is present.
 ## Repo Layout
 
 | Path                                  | Purpose                                            |
-| ---------------------------- | -------------------------------------------------- |
+| -------------------------------------- | -------------------------------------------------- |
-| `includes/`                  | Public headers and shared models.                  |
+| `tooling/pipeline/includes/`           | Public headers and shared models.                  |
-| `src/`                       | Implementation files.                              |
+| `tooling/pipeline/src/`                | Implementation files.                              |
-| `locations.json`             | Curated city input copied into the build tree.     |
+| `tooling/pipeline/locations.json`      | Curated city input copied into the build tree.     |
-| `prompts/`                   | System prompts used by the model-backed path.      |
+| `tooling/pipeline/prompts/`            | System prompts used by the model-backed path.      |
-| `diagrams/`                  | Architecture and pipeline diagrams.                |
 | `tooling/pipeline/runpod/`             | Dockerfile, launcher, and RunPod pod template.      |
-| `ETHICS-AND-KNOWN-ISSUES.md` | Ethics, bias, hallucination analysis, mitigations. |
+| `docs/pipeline/diagrams/`              | Architecture and pipeline diagrams.                |
+| `docs/pipeline/ETHICS-AND-KNOWN-ISSUES.md` | Ethics, bias, hallucination analysis, mitigations. |
 
 ---
 
 ## Code Tour
 
+Paths below are relative to `tooling/pipeline/`.
+
 - `src/main.cc` — argument parsing and DI composition root.
-- `src/biergarten_data_generator/` — orchestration, sampling, logging, and
+- `src/biergarten_pipeline_orchestrator/` — orchestration, sampling, logging,
-  export.
+  and export.
-- `src/services/wikipedia/` — enrichment service and cache.
+- `src/services/enrichment/wikipedia/` — enrichment service and cache.
 - `src/services/sqlite/` — SQLite export implementation.
 - `src/data_generation/llama/` — local inference, prompt loading, output
   validation.
 - `src/data_generation/mock/` — deterministic fallback.
-- `tooling/pipeline/runpod/` — container build and runtime launcher.
+- `runpod/` — container build and runtime launcher.
 
 ---
 
@@ -398,7 +409,9 @@ Silicon; CUDA or HIP/ROCm is detected on Linux when the toolkit is present.
 
 The pipeline currently produces city-aware brewery records and dated SQLite
 exports. The next passes add additional fixture types so the app can exercise
-the full brewery domain without live data.
+the full brewery domain without live data. For the detailed engineering
+breakdown of what's needed to reach the architecture in
+[`diagrams/planned/`](./diagrams/planned/), see [ROADMAP.md](./ROADMAP.md).
 
 ### Testing — Very High Priority
 

docs/pipeline/ROADMAP.md

@@ -0,0 +1,211 @@
+# Pipeline Roadmap — Reaching the Planned Architecture
+
+This is the engineering breakdown for closing the gap between the **current**
+pipeline and the **planned** architecture documented in
+[`diagrams/planned/class.puml`](./diagrams/planned/class.puml) and
+[`diagrams/planned/activity.puml`](./diagrams/planned/activity.puml). Nothing
+in `diagrams/planned/` is implemented yet — this file tracks what it would
+take to get there. For the current implementation, see
+[README.md](./README.md).
+
+Items are grouped by layer and roughly ordered by dependency: later groups
+build on types and services introduced earlier.
+
+The only concurrency in the current pipeline is the log dispatcher thread
+(`main.cc` spawns it to drain a `BoundedChannel<LogEntry>` into spdlog for the
+whole run). Sampling, enrichment, generation, and export all happen
+synchronously on the main thread inside `BiergartenPipelineOrchestrator::Run()`
+— §6 below is what introduces the additional worker threads the planned
+architecture needs.
+
+---
+
+## 1. Domain Models
+
+`tooling/pipeline/includes/data_model/generated_models.h` and `models.h`.
+
+- [ ] Add `Completeness` enum (`Full`, `Partial`, `Absent`) and a
+      `LocationContext` struct (`text`, `completeness`, `char_count`).
+      Replace `EnrichedCity::region_context` (currently a plain
+      `std::string`) with `context : LocationContext`.
+- [ ] Add `BeerStyle` (`name`, `description`, `min_abv`, `max_abv`,
+      `min_ibu`, `max_ibu`).
+- [ ] Add `BeerResult`, `CheckinResult`, `RatingResult` result payloads.
+- [ ] Add `GenerationMetadata` (`generation_id`, `generated_time`,
+      `context_provided`, `generated_with`).
+- [x] Add `first_name`, `last_name`, `gender`, and `activity_weight` to
+      `UserResult` (currently just `username`, `bio`). `first_name`/
+      `last_name`/`gender` are copied from the sampled `Name` (see below),
+      not LLM-invented.
+- [x] Add `Name` (`first_name`, `last_name`, `gender`) — the sampled result
+      handed to `DataGenerator::GenerateUser`. Add `ForenameEntry` (`name`,
+      `gender`) and a `NamesByCountry` class (not a bare typedef) that owns
+      two maps — `std::unordered_map<std::string, std::vector<ForenameEntry>>`
+      and `std::unordered_map<std::string, std::vector<std::string>>`, both
+      keyed by ISO 3166-1 code — and exposes `SampleName(iso3166_1, rng)`.
+      Pairing a forename with a surname happens at sample time so gender
+      (present per-forename in the source data) is never discarded the way a
+      pre-flattened `{first_name, last_name}` list would lose it; see
+      `LoadNamesByCountry()` below.
+- [ ] Extend `GeneratedBrewery` with `brewery_id`, `context_completeness`,
+      `metadata` (currently just `{location, brewery}`).
+- [ ] Add `GeneratedBeer`, `GeneratedCheckin`, `GeneratedRating`,
+      `GeneratedFollow` aggregate structs.
+- [x] Add `GeneratedUser` aggregate struct. Carries `email`, `date_of_birth`,
+      and `password` — programmatically generated by the orchestrator, never
+      LLM-authored — so a downstream auth-account seeding consumer (outside
+      this repo tree's docs) can register real accounts from the pipeline's
+      SQLite export. Skips `user_id`/`metadata` for now, matching
+      `GeneratedBrewery`'s current (pre-`brewery_id`/`metadata`) shape. Not
+      yet wired into `IExportService`/`SqliteExportService` — `GenerateUsers`
+      currently only logs and holds `generated_users_` in memory; no `users`
+      table exists in the SQLite export yet (see §5).
+- [x] Add `UserPersona` (`name`, `description`, `style_affinities`).
+
+## 2. Data Preloading
+
+`tooling/pipeline/includes/json_handling/`, fixture files.
+
+- [ ] Extract a `DataPreloader` interface; have `JsonLoader` implement it.
+      `JsonLoader` now also exposes static `LoadPersonas()` and
+      `LoadNamesByCountry()` (see below), but as additional static methods,
+      not yet behind a formal interface.
+- [ ] Add `LoadBeerStyles()`. `beer-styles.json` already exists in the repo
+      and is already copied into the Docker image
+      (`runpod/Dockerfile`), but no loader reads it yet, and the native
+      CMake build doesn't copy it into `build/` at all — `CMakeLists.txt`'s
+      "Runtime Assets" step only copies `locations.json` and `prompts/`.
+- [x] Add `LoadPersonas()` and author `personas.json` (doesn't exist yet).
+- [x] Add `LoadNamesByCountry(forenames_filepath, surnames_filepath)`,
+      parsing `tooling/pipeline/forenames-by-country.json` and
+      `surnames-by-country.json` into a `NamesByCountry`. Both files are
+      vendored verbatim (unmodified, full multinational coverage) from
+      `sigpwned/popular-names-by-country-dataset` (CC0) — see
+      ETHICS-AND-KNOWN-ISSUES.md's Names-by-Country Dataset section for
+      provenance. Deliberately not pre-paired or filtered down to just the
+      countries in `locations.json`: keeping the source shape (including
+      per-forename gender) intact means the loader can support more
+      countries later, or gender-aware persona/bio generation, without
+      re-sourcing data.
+
+## 3. Policy / Strategy Layer
+
+Entirely new — no `includes/policy/` (or equivalent) directory exists today.
+
+- [ ] `ContextStrategy` interface + `BreweryContextStrategy` /
+      `BeerContextStrategy`. Today `WikipediaEnrichmentService::GetLocationContext`
+      hardcodes a generic `"brewing"` query and a `"beer in {country}"`
+      query directly — no per-phase strategy selection.
+- [ ] `SamplingStrategy` interface + `UniformSamplingStrategy`, replacing
+      the inline `std::ranges::sample(...)` call in
+      `BiergartenPipelineOrchestrator::QueryCitiesWithCountries()`.
+- [ ] `BeerSelectionStrategy` interface + `RandomBeerSelectionStrategy`, to
+      pick styles per brewery from the `BeerStyle` palette (depends on §1
+      and §2).
+- [ ] `CheckinDistributionStrategy` interface + `JCurveCheckinStrategy` /
+      `RandomCheckinStrategy` — this is the "Check-In System" item already
+      called out in README.md's Next Steps, made concrete.
+- [ ] `FollowGenerationStrategy` interface + `RandomFollowStrategy` /
+      `ActivityWeightedFollowStrategy`.
+
+## 4. Data Generation
+
+`tooling/pipeline/includes/data_generation/`, `src/data_generation/`.
+
+- [ ] Extend the `DataGenerator` interface with `GenerateBeer`,
+      `GenerateCheckin`, `GenerateRating` (today: only `GenerateBrewery` and
+      `GenerateUser`).
+- [x] Implement `LlamaGenerator::GenerateUser` for real, with a retry loop
+      mirroring `GenerateBrewery` (GBNF grammar, `ValidateUserJson`, up to 3
+      attempts with corrective feedback) and a new
+      `prompts/USER_GENERATION.md`. Changed the `DataGenerator::GenerateUser`
+      signature to
+      `(city : const EnrichedCity&, persona : const UserPersona&, name : const Name&) : UserResult`,
+      matching what the activity diagram actually passes. `MockGenerator::GenerateUser`
+      updated to match the new signature too.
+- [ ] Implement `MockGenerator::GenerateBeer` / `GenerateCheckin` /
+      `GenerateRating`.
+- [ ] Add `IPromptFormatter::ExpectedArchitecture()` and
+      `LlamaGenerator::ValidateModelArchitecture()` so loading a GGUF that
+      doesn't match the configured chat template fails fast instead of
+      silently producing degraded output.
+- [ ] Add prompt template files for beer/checkin/rating generation next to
+      the existing `prompts/BREWERY_GENERATION.md`.
+
+## 5. Export Service
+
+`tooling/pipeline/includes/services/database/`, `src/services/sqlite/`.
+
+- [ ] Extend `IExportService` with `ProcessBeer`, `ProcessUser`,
+      `ProcessCheckin`, `ProcessRating`, `ProcessFollow` (today only
+      `ProcessRecord(const GeneratedBrewery&)` exists).
+- [ ] Add `beers`, `users`, `checkins`, `ratings`, `follows` tables to
+      `SqliteExportService::InitializeSchema()` — see
+      `kCreateLocationsTableSql` / `kCreateBreweriesTableSql` in
+      `includes/services/database/sqlite_statement_helpers.h` for the
+      existing pattern to follow.
+- [ ] Add a `brewery_cache_` alongside the existing `location_cache_`, and
+      move from one open transaction for the whole run to per-phase batched
+      commits (`BEGIN` / `COMMIT & BEGIN` on a batch-size threshold), as
+      shown in the planned activity diagram.
+
+## 6. Concurrency & Orchestration
+
+`tooling/pipeline/includes/concurrency/`,
+`src/biergarten_pipeline_orchestrator/`.
+
+- [ ] `BoundedChannel<T>` already exists and is production-tested — but
+      it's only wired to the single log channel today. Stand up the
+      per-phase producer/consumer channels (`loc_ch`, `exp_ch`, etc.) the
+      planned activity diagram describes, each with a dedicated LLM worker
+      thread and SQLite worker thread.
+- [ ] Rewrite `BiergartenPipelineOrchestrator::Run()` from one synchronous
+      pass over `generated_breweries_` into phased methods —
+      `RunUserPhase` → `RunBreweryAndBeerPhase` (with a `RunBeerPhase`
+      sub-step once `brewery_pool_` is populated) → `RunCheckinPhase` /
+      `RunFollowPhase` (these two can run in parallel) → `RunRatingPhase` —
+      backed by `user_pool_`, `brewery_pool_`, `beer_pool_`,
+      `checkin_pool_`, `follow_pool_`.
+- [ ] Honor the structural-concurrency requirement already called out in a
+      comment on `BiergartenPipelineOrchestrator::Run()` in
+      `biergarten_pipeline_orchestrator.h`: once real worker threads exist,
+      they must be structurally joined (e.g. via `std::jthread`) before
+      `Run()` returns, so no worker logs to a closed channel during
+      teardown.
+
+## 7. Enrichment
+
+- [ ] Decide whether to restore the city/region-specific Wikipedia query
+      that's currently commented out in
+      `src/services/enrichment/wikipedia/get_summary.cc`
+      (`GetLocationContext`). The `ContextStrategy` work in §3 is a natural
+      place to reintroduce it via `BreweryContextStrategy::QueriesFor()`.
+- [ ] Pre-warm caches at startup (`PreWarmBeerStyleCache`,
+      `PreWarmLocationCache` in the planned activity diagram) instead of
+      fetching lazily per record, so the streaming phases never block on a
+      cold cache mid-run.
+
+## 8. Fixtures / Build
+
+- [ ] Author `personas.json` and `names-by-country.json` (see §2).
+- [ ] Fix the `beer-styles.json` build-tree gap: add it to the "Runtime
+      Assets" `configure_file` step in `CMakeLists.txt` so native builds and
+      the Docker image agree on what's available at runtime.
+
+---
+
+## Suggested build order
+
+The planned activity diagram's own phase notes ("brewery*pool* is now fully
+populated. Phase 1b may begin.", etc.) imply a dependency order. Roughly:
+
+1. Domain models (§1) and data preloading (§2) — nothing else compiles
+   without these.
+2. Export schema (§5) — so every later generation phase has somewhere to
+   land its output.
+3. Policy/strategy layer (§3) and generator interface (§4).
+4. Concurrency/orchestration rewrite (§6), which is the only piece that
+   actually wires §1–§5 into the phased, parallel pipeline shown in the
+   planned diagrams.
+5. Enrichment cache pre-warming and the city/region query decision (§7) —
+   useful at any point, but most valuable once phases run concurrently.

docs/pipeline/diagrams/current/activity.puml

@@ -18,23 +18,40 @@ skinparam ActivityBarColor #628A5B
 skinparam SwimlaneBorderColor #547461
 skinparam SwimlaneBorderThickness 0.3
 
-title The Biergarten Data Pipeline (Streaming Architecture)
+title The Biergarten Data Pipeline (Current — Synchronous Data Path)
 
 |#F2F6F0|main.cc|
 start
+:Create BoundedChannel<LogEntry> log_channel;
+:Spawn log dispatcher thread\n(LogDispatcher::Run());
+note right
+  The only concurrency in the current pipeline:
+  a dedicated thread drains log_channel and
+  forwards entries to spdlog for the entire run.
+  Joined during shutdown after log_channel closes.
+end note
 :ParseArguments(argc, argv);
 if (Are arguments valid?) then (no)
-  :spdlog::error usage info;
+  :Log error / usage info;
   stop
 else (yes)
 endif
 
 :Init OpenSSL global state & LlamaBackendState;
 :di::make_injector(...);
-:injector.create<std::unique_ptr<BiergartenDataGenerator>>();
+note right
-:BiergartenDataGenerator::Run();
+  Binds ILogger, IEnrichmentService, DataGenerator,
+  IExportService, IPromptFormatter, WebClient based
+  on --mocked vs. model-backed mode.
+end note
+:injector.create<std::unique_ptr<BiergartenPipelineOrchestrator>>();
+:BiergartenPipelineOrchestrator::Run();
+note right
+  Run() itself is synchronous — sampling, enrichment,
+  generation, and export all happen on this thread.
+end note
 
-|#EAF0E8|BiergartenDataGenerator|
+|#EAF0E8|BiergartenPipelineOrchestrator|
 :Initialize SQLite export;
 
 |#E0EAE0|SqliteExportService|
@@ -48,23 +65,35 @@ note right
   Begins Transaction
 end note
 
-|#EAF0E8|BiergartenDataGenerator|
+|#EAF0E8|BiergartenPipelineOrchestrator|
 :QueryCitiesWithCountries();
 
 |#E2EBDC|JsonLoader|
 :JsonLoader::LoadLocations("locations.json");
-:std::ranges::sample(all_locations, 50);
+:std::ranges::sample(all_locations, --location-count);
+note right
+  --location-count defaults to 10.
+end note
 
-|#EAF0E8|BiergartenDataGenerator|
+|#EAF0E8|BiergartenPipelineOrchestrator|
 while (For each sampled Location?) is (Remaining cities)
-  |#DCE8D8|WikipediaService|
+  |#DCE8D8|IEnrichmentService|
   :GetLocationContext(loc);
-  :FetchExtracts(City, Country, Beer);
+  note right
-  |#EAF0E8|BiergartenDataGenerator|
+    WikipediaEnrichmentService fetches a generic
+    "brewing" extract and a "beer in {country}" extract
+    (not a city/region-specific page). MockEnrichmentService
+    (--mocked) returns an empty string instead.
+  end note
+  |#EAF0E8|BiergartenPipelineOrchestrator|
+  if (Lookup failed?) then (yes)
+    :Log warning, skip city;
+  else (no)
     :Store EnrichedCity{Location, region_context};
+  endif
 endwhile (Done)
 
-|#EAF0E8|BiergartenDataGenerator|
+|#EAF0E8|BiergartenPipelineOrchestrator|
 :GenerateBreweries(enriched_cities);
 
 |#E5EDE1|DataGenerator|
@@ -73,7 +102,10 @@ while (For each EnrichedCity?) is (Remaining cities)
     :DeterministicHash & Format;
   else (LlamaGenerator)
     :PrepareRegionContext;
-    :LoadBrewerySystemPrompt("prompts/system.md");
+    :prompt_directory_->Load("BREWERY_GENERATION");
+    note right
+      Resolves to BREWERY_GENERATION.md inside --prompt-dir.
+    end note
     repeat
       :Infer(system_prompt, user_prompt, max_tokens, kBreweryJsonGrammar);
       :ValidateBreweryJson(raw, brewery);
@@ -81,11 +113,16 @@ while (For each EnrichedCity?) is (Remaining cities)
         break
       else (no)
         :Attempt++;
+        :Append validation error to retry prompt;
       endif
     repeat while (Attempt < 3?) is (yes)
+    note right
+      max_tokens is fixed across retries —
+      it is not raised on truncation.
+    end note
   endif
 
-  |#EAF0E8|BiergartenDataGenerator|
+  |#EAF0E8|BiergartenPipelineOrchestrator|
   if (Generation successful?) then (yes)
     |#E0EAE0|SqliteExportService|
     :ProcessRecord(GeneratedBrewery);
@@ -97,8 +134,8 @@ while (For each EnrichedCity?) is (Remaining cities)
     :Insert Brewery (FK: location_id);
 
     if (Exception caught during insert?) then (yes)
-      |#EAF0E8|BiergartenDataGenerator|
+      |#EAF0E8|BiergartenPipelineOrchestrator|
-      :spdlog::warn "Failed to stream record to SQLite export";
+      :Log warning "SQLite export failed";
       note right
         Data loss is prevented per-record.
         The pipeline continues running.
@@ -106,7 +143,7 @@ while (For each EnrichedCity?) is (Remaining cities)
     else (no)
     endif
   else (no)
-    :spdlog::warn "Generation failed, skipping...";
+    :Log warning "Generation failed, skipping...";
   endif
   |#E5EDE1|DataGenerator|
 endwhile (Done)
@@ -119,6 +156,8 @@ note right
 end note
 
 |#F2F6F0|main.cc|
+:Close log_channel;
+:Join log dispatcher thread;
 :Return 0;
 stop
 

docs/pipeline/diagrams/current/class.puml

@@ -25,11 +25,12 @@ skinparam note {
 
 title The Biergarten Data Pipeline - Class Diagram
 
-class BiergartenDataGenerator {
+class BiergartenPipelineOrchestrator {
   - logger_ : std::shared_ptr<ILogger>
   - context_service_ : std::unique_ptr<IEnrichmentService>
   - generator_ : std::unique_ptr<DataGenerator>
   - exporter_ : std::unique_ptr<IExportService>
+  - application_options_ : ApplicationOptions
   - generated_breweries_ : std::vector<GeneratedBrewery>
   + Run() : bool
   - QueryCitiesWithCountries() : std::vector<Location>
@@ -54,21 +55,29 @@ class PipelinePhase <<enumeration>> {
   Teardown
 }
 
-struct LogEntry {
+struct LogDTO {
-  + timestamp : std::chrono::system_clock::time_point
+  + level : LogLevel
+  + phase : PipelinePhase
+  + message : std::string
+}
+
+struct LogEntry {
+  + timestamp : std::chrono::system_clock::time_point
+  + origin : std::source_location
+  + thread_id : std::thread::id
   + level : LogLevel
   + phase : PipelinePhase
   + message : std::string
-  + worker : std::optional<std::string>
 }
 
 interface ILogger <<interface>> {
-  + Log(entry : const LogEntry&) : void
+  + Log(payload : LogDTO) : void
+  - {abstract} DoLog(entry : LogEntry) : void
 }
 
 class LogProducer {
   - channel_ : BoundedChannel<LogEntry>&
-  + Log(entry : const LogEntry&) : void
+  - DoLog(entry : LogEntry) : void
 }
 
 class LogDispatcher {
@@ -81,7 +90,11 @@ interface IEnrichmentService <<interface>> {
   + GetLocationContext(loc : const Location&) : std::string
 }
 
-class WikipediaService {
+class MockEnrichmentService {
+  + GetLocationContext(loc : const Location&) : std::string
+}
+
+class WikipediaEnrichmentService {
   - client_ : std::unique_ptr<WebClient>
   - extract_cache_ : std::unordered_map<std::string, std::string>
   + GetLocationContext(loc : const Location&) : std::string
@@ -113,13 +126,13 @@ class LlamaGenerator {
   - model_ : ModelHandle
   - context_ : ContextHandle
   - prompt_formatter_ : std::unique_ptr<IPromptFormatter>
+  - prompt_directory_ : std::unique_ptr<IPromptDirectory>
   - rng_ : std::mt19937
   + GenerateBrewery(...) : BreweryResult
   + GenerateUser(...) : UserResult
   - Load(model_path : const std::string&) : void
   - Infer(...) : std::string
   - InferFormatted(...) : std::string
-  - LoadBrewerySystemPrompt(...) : std::string
 }
 
 interface IPromptFormatter <<interface>> {
@@ -130,6 +143,16 @@ class Gemma4JinjaPromptFormatter {
   + Format(system_prompt : std::string_view, user_prompt : std::string_view) : std::string
 }
 
+interface IPromptDirectory <<interface>> {
+  + Load(key : std::string_view) : std::string
+}
+
+class PromptDirectory {
+  - prompt_dir_ : std::filesystem::path
+  - cache_ : std::unordered_map<std::string, std::string>
+  + Load(key : std::string_view) : std::string
+}
+
 class JsonLoader {
   + {static} LoadLocations(filepath : const std::filesystem::path&) : std::vector<Location>
 }
@@ -164,19 +187,22 @@ class SystemDateTimeProvider {
 }
 
 ' Structural Relationships / Dependency Injection
-BiergartenDataGenerator *-- ILogger : owns
+BiergartenPipelineOrchestrator *-- ILogger : owns
-BiergartenDataGenerator *-- IEnrichmentService : owns
+BiergartenPipelineOrchestrator *-- IEnrichmentService : owns
-BiergartenDataGenerator *-- DataGenerator : owns
+BiergartenPipelineOrchestrator *-- DataGenerator : owns
-BiergartenDataGenerator *-- IExportService : owns
+BiergartenPipelineOrchestrator *-- IExportService : owns
 
 LogEntry *-- LogLevel
 LogEntry *-- PipelinePhase
+LogDTO *-- LogLevel
+LogDTO *-- PipelinePhase
 ILogger <|.. LogProducer : implements
 LogProducer ..> LogEntry : emits
 LogDispatcher ..> LogEntry : consumes
 
-IEnrichmentService <|.. WikipediaService : implements
+IEnrichmentService <|.. WikipediaEnrichmentService : implements
-WikipediaService *-- WebClient : owns
+IEnrichmentService <|.. MockEnrichmentService : implements
+WikipediaEnrichmentService *-- WebClient : owns
 
 WebClient <|.. HttpWebClient : implements
 
@@ -184,10 +210,12 @@ DataGenerator <|.. MockGenerator : implements
 DataGenerator <|.. LlamaGenerator : implements
 
 LlamaGenerator *-- IPromptFormatter : uses
+LlamaGenerator *-- IPromptDirectory : uses
 
 IPromptFormatter <|.. Gemma4JinjaPromptFormatter : implements
+IPromptDirectory <|.. PromptDirectory : implements
 
-BiergartenDataGenerator ..> JsonLoader : uses
+BiergartenPipelineOrchestrator ..> JsonLoader : uses
 
 IExportService <|.. SqliteExportService : implements
 SqliteExportService *-- IDateTimeProvider : owns

docs/pipeline/diagrams/planned/activity.puml

@@ -43,7 +43,7 @@ fork again
   :EnrichmentService::PreWarmLocationCache(sampled_locations);
 end fork
 fork
-  :JsonLoader::LoadNamesByCountry("names-by-country.json");
+  :JsonLoader::LoadNamesByCountry(\n  "forenames-by-country.json",\n  "surnames-by-country.json");
 fork again
   :JsonLoader::LoadPersonas("personas.json");
 end fork

docs/pipeline/diagrams/planned/class.puml

@@ -67,11 +67,47 @@ package "Domain: Models" {
   }
 
   class UserResult {
+    + first_name : std::string
+    + last_name : std::string
+    + gender : std::string
     + username : std::string
     + bio : std::string
     + activity_weight : float
   }
 
+  class Name {
+    + first_name : std::string
+    + last_name : std::string
+    + gender : std::string
+  }
+
+  class ForenameEntry {
+    + name : std::string
+    + gender : std::string
+  }
+
+  class NamesByCountry {
+    - forenames_by_country_ : std::unordered_map<std::string, std::vector<ForenameEntry>>
+    - surnames_by_country_ : std::unordered_map<std::string, std::vector<std::string>>
+    + SampleName(iso3166_1 : const std::string&,\n  rng : std::mt19937&) : std::optional<Name>
+  }
+
+  note right of NamesByCountry
+    Backed by two source-shaped maps,
+    keyed by ISO 3166-1 country code,
+    sourced from popular-names-by-country-dataset
+    (CC0) -- see ETHICS-AND-KNOWN-ISSUES.md.
+    Gender is preserved per forename so it can
+    be threaded through to persona/bio generation
+    later; surnames carry no gender in the source
+    data. Pairing happens at sample time, not at
+    fixture-authoring time, so no information from
+    the source dataset is discarded up front.
+  end note
+
+  NamesByCountry *-- "0..*" ForenameEntry
+  NamesByCountry ..> Name : produces
+
   class CheckinResult {
     + checked_in_at : std::string
     + note : std::string
@@ -110,9 +146,20 @@ package "Domain: Models" {
     + user_id : uint64_t
     + location : Location
     + user : UserResult
+    + email : std::string
+    + date_of_birth : std::string
+    + password : std::string
     + metadata : GenerationMetadata
   }
 
+  note right of GeneratedUser
+    email, date_of_birth, and password are
+    programmatically generated by the orchestrator
+    (not LLM-authored) so a downstream auth-account
+    seeding consumer can register real accounts from
+    this export. See ROADMAP.md §1.
+  end note
+
   class GeneratedCheckin {
     + checkin_id : uint64_t
     + user_id : uint64_t
@@ -321,15 +368,15 @@ package "Infrastructure: Data Preloading" {
   interface DataPreloader <<interface>> {
     + LoadLocations(filepath : const std::filesystem::path&) : std::vector<Location>
     + LoadBeerStyles(filepath : const std::filesystem::path&) : std::vector<BeerStyle>
-    + LoadPersonas(filepath : const std::filesystem::path&) : std::vector<Persona>
+    + LoadPersonas(filepath : const std::filesystem::path&) : std::vector<UserPersona>
-    + LoadNamesByCountry(filepath : const std::filesystem::path&) : NamesByCountry
+    + LoadNamesByCountry(forenames_filepath : const std::filesystem::path&,\n  surnames_filepath : const std::filesystem::path&) : NamesByCountry
   }
 
   class JsonLoader {
     + LoadLocations(filepath : const std::filesystem::path&) : std::vector<Location>
     + LoadBeerStyles(filepath : const std::filesystem::path&) : std::vector<BeerStyle>
-    + LoadPersonas(filepath : const std::filesystem::path&) : std::vector<Persona>
+    + LoadPersonas(filepath : const std::filesystem::path&) : std::vector<UserPersona>
-    + LoadNamesByCountry(filepath : const std::filesystem::path&) : NamesByCountry
+    + LoadNamesByCountry(forenames_filepath : const std::filesystem::path&,\n  surnames_filepath : const std::filesystem::path&) : NamesByCountry
   }
 
 }
@@ -380,7 +427,7 @@ package "Infrastructure: Data Generation" {
   interface DataGenerator <<interface>> {
     + GenerateBrewery(location : const Location&,\n  context : const LocationContext&) : BreweryResult
     + GenerateBeer(brewery_id : uint64_t,\n  location : const Location&,\n  context : const LocationContext&,\n  style : const BeerStyle&) : BeerResult
-    + GenerateUser(location : const Location&) : UserResult
+    + GenerateUser(city : const EnrichedCity&,\n  persona : const UserPersona&,\n  name : const Name&) : UserResult
     + GenerateCheckin(user : const GeneratedUser&,\n  brewery : const GeneratedBrewery&,\n  timestamp : const std::string&) : CheckinResult
     + GenerateRating(user : const GeneratedUser&,\n  beer : const GeneratedBeer&,\n  checkin_id : uint64_t) : RatingResult
   }

tooling/pipeline/CMakeLists.txt

@@ -151,6 +151,11 @@ target_sources(${PROJECT_NAME} PRIVATE
         src/json_handling/json_loader.cc
 )
 
+# --- data_model ---
+target_sources(${PROJECT_NAME} PRIVATE
+        src/data_model/names_by_country.cc
+)
+
 # --- application_options ---
 target_sources(${PROJECT_NAME} PRIVATE
         src/application_options/parse_arguments.cc
@@ -161,6 +166,7 @@ target_sources(${PROJECT_NAME} PRIVATE
         src/biergarten_pipeline_orchestrator/log_results.cc
         src/biergarten_pipeline_orchestrator/biergarten_pipeline_orchestrator.cc
         src/biergarten_pipeline_orchestrator/generate_breweries.cc
+        src/biergarten_pipeline_orchestrator/generate_users.cc
         src/biergarten_pipeline_orchestrator/run.cc
         src/biergarten_pipeline_orchestrator/query_cities_with_countries.cc
 )
@@ -204,6 +210,7 @@ target_sources(${PROJECT_NAME} PRIVATE
 # --- services: sqlite ---
 target_sources(${PROJECT_NAME} PRIVATE
 	src/services/sqlite/process_record.cc
+	src/services/sqlite/process_user_record.cc
 	src/services/sqlite/sqlite_export_service.cc
 	src/services/sqlite/finalize.cc
 	src/services/sqlite/initialize.cc
@@ -260,6 +267,21 @@ configure_file(
         ${CMAKE_BINARY_DIR}/locations.json
         COPYONLY
 )
+configure_file(
+        ${CMAKE_SOURCE_DIR}/personas.json
+        ${CMAKE_BINARY_DIR}/personas.json
+        COPYONLY
+)
+configure_file(
+        ${CMAKE_SOURCE_DIR}/forenames-by-country.json
+        ${CMAKE_BINARY_DIR}/forenames-by-country.json
+        COPYONLY
+)
+configure_file(
+        ${CMAKE_SOURCE_DIR}/surnames-by-country.json
+        ${CMAKE_BINARY_DIR}/surnames-by-country.json
+        COPYONLY
+)
 add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
         COMMAND ${CMAKE_COMMAND} -E copy_directory
         ${CMAKE_SOURCE_DIR}/prompts

tooling/pipeline/includes/biergarten_pipeline_orchestrator.h

@@ -91,6 +91,18 @@ class BiergartenPipelineOrchestrator {
    */
   void GenerateBreweries(std::span<const EnrichedCity> cities);
 
+  /**
+   * @brief Generate users grounded in sampled names and personas for
+   * enriched cities.
+   *
+   * Loads personas.json / forenames-by-country.json / surnames-by-country.json
+   * itself, mirroring how QueryCitiesWithCountries() owns its own
+   * locations.json load.
+   *
+   * @param cities Span of enriched city data.
+   */
+  void GenerateUsers(std::span<const EnrichedCity> cities);
+
   /**
    * @brief Log the generated brewery results.
    */
@@ -98,5 +110,8 @@ class BiergartenPipelineOrchestrator {
 
   /// @brief Stores generated brewery data.
   std::vector<GeneratedBrewery> generated_breweries_;
+
+  /// @brief Stores generated user data.
+  std::vector<GeneratedUser> generated_users_;
 };
 #endif  // BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_DATA_GENERATOR_H_

tooling/pipeline/includes/data_generation/data_generator.h

@@ -28,12 +28,16 @@ class DataGenerator {
                                         const std::string& region_context) = 0;
 
   /**
-   * @brief Generates a user profile for a locale.
+   * @brief Generates a user profile grounded in a sampled name and persona.
    *
-   * @param locale Locale hint used by generator.
+   * @param city Enriched city the user is associated with.
+   * @param persona Persona archetype grounding the generated bio.
+   * @param name Sampled first/last name (and gender) -- not LLM-invented.
    * @return User generation result.
    */
-  virtual UserResult GenerateUser(const std::string& locale) = 0;
+  virtual UserResult GenerateUser(const EnrichedCity& city,
+                                  const UserPersona& persona,
+                                  const Name& name) = 0;
 };
 
 #endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_DATA_GENERATOR_H_

tooling/pipeline/includes/data_generation/llama_generator.h

@@ -65,12 +65,15 @@ class LlamaGenerator final : public DataGenerator {
                                 const std::string& region_context) override;
 
   /**
-   * @brief Generates a user profile for the provided locale.
+   * @brief Generates a user profile grounded in a sampled name and persona.
    *
-   * @param locale Locale hint.
+   * @param city Enriched city the user is associated with.
+   * @param persona Persona archetype grounding the generated bio.
+   * @param name Sampled first/last name -- not LLM-invented.
    * @return Generated user profile.
    */
-  UserResult GenerateUser(const std::string& locale) override;
+  UserResult GenerateUser(const EnrichedCity& city, const UserPersona& persona,
+                          const Name& name) override;
 
  private:
   static constexpr int32_t kDefaultMaxTokens = 10000;

tooling/pipeline/includes/data_generation/llama_generator_helpers.h

@@ -47,4 +47,18 @@ void AppendTokenPiece(const llama_vocab* vocab, llama_token token,
 std::optional<std::string> ValidateBreweryJson(const std::string& raw,
                                                BreweryResult& brewery_out);
 
+/**
+ * @brief Validates and parses user JSON output.
+ *
+ * Only populates `username`, `bio`, and `activity_weight` -- `first_name`
+ * and `last_name` are not LLM-authored and are set separately from the
+ * sampled Name.
+ *
+ * @param raw Raw model output.
+ * @param user_out Parsed user payload.
+ * @return Validation error message if invalid, or std::nullopt on success.
+ */
+std::optional<std::string> ValidateUserJson(const std::string& raw,
+                                            UserResult& user_out);
+
 #endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_LLAMA_GENERATOR_HELPERS_H_

tooling/pipeline/includes/data_generation/mock_generator.h

@@ -28,12 +28,16 @@ class MockGenerator final : public DataGenerator {
                                 const std::string& region_context) override;
 
   /**
-   * @brief Generates deterministic user data for a locale.
+   * @brief Generates deterministic user data grounded in a sampled name and
+   * persona.
    *
-   * @param locale Locale hint.
+   * @param city Enriched city the user is associated with.
+   * @param persona Persona archetype.
+   * @param name Sampled first/last name, copied directly into the result.
    * @return Generated user result.
    */
-  UserResult GenerateUser(const std::string& locale) override;
+  UserResult GenerateUser(const EnrichedCity& city, const UserPersona& persona,
+                          const Name& name) override;
 
  private:
   /**
@@ -44,12 +48,26 @@ class MockGenerator final : public DataGenerator {
    */
   static size_t DeterministicHash(const Location& location);
 
+  /**
+   * @brief Combines city, persona, and name into a stable hash value.
+   *
+   * @param location City and country names.
+   * @param persona Persona archetype.
+   * @param name Sampled first/last name.
+   * @return Deterministic hash value.
+   */
+  static size_t DeterministicHash(const Location& location,
+                                  const UserPersona& persona,
+                                  const Name& name);
+
   // Hash stride constants for deterministic distribution across fixed-size
   // arrays. These coprime strides spread hash values uniformly without
   // clustering, ensuring diverse output across different hash inputs.
   static constexpr size_t kNounHashStride = 7;
   static constexpr size_t kDescriptionHashStride = 13;
   static constexpr size_t kBioHashStride = 11;
+  static constexpr size_t kActivityWeightHashStride = 17;
+  static constexpr size_t kActivityWeightHashRange = 1000;
 
   static constexpr std::array<std::string_view, 18> kBreweryAdjectives = {
       "Craft",      "Heritage", "Local",  "Artisan",  "Pioneer",    "Golden",

tooling/pipeline/includes/data_model/generated_models.h

@@ -36,11 +36,27 @@ struct BreweryResult {
  * @brief Generated user profile payload.
  */
 struct UserResult {
+  /// @brief First (given) name, copied from the sampled Name -- not
+  /// LLM-invented.
+  std::string first_name{};
+
+  /// @brief Last (family) name, copied from the sampled Name -- not
+  /// LLM-invented.
+  std::string last_name{};
+
+  /// @brief Gender associated with the sampled first name, copied from the
+  /// sampled Name -- not LLM-invented.
+  std::string gender{};
+
   /// @brief Username handle.
   std::string username{};
 
   /// @brief Short user biography.
   std::string bio{};
+
+  /// @brief Relative check-in/activity weight for this user, used to drive
+  /// a J-curve activity profile in later pipeline phases.
+  float activity_weight{};
 };
 
 // ============================================================================
@@ -63,4 +79,19 @@ struct GeneratedBrewery {
   BreweryResult brewery;
 };
 
+/**
+ * @brief Helper struct to store generated user data.
+ *
+ * `email`, `date_of_birth`, and `password` are programmatically generated by
+ * the orchestrator (never LLM-authored) so a downstream auth-account seeding
+ * consumer can register real accounts from the pipeline's SQLite export.
+ */
+struct GeneratedUser {
+  Location location;
+  UserResult user;
+  std::string email{};
+  std::string date_of_birth{};
+  std::string password{};
+};
+
 #endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_GENERATED_MODELS_H_

tooling/pipeline/includes/data_model/models.h

@@ -64,6 +64,53 @@ struct BreweryLocation {
   std::string_view country_name;
 };
 
+// ============================================================================
+// Name / Persona Models
+// ============================================================================
+
+/**
+ * @brief A sampled first/last name pair, with the source forename's gender.
+ *
+ * Produced by NamesByCountry::SampleName();
+ */
+struct Name {
+  /// @brief First (given) name.
+  std::string first_name{};
+
+  /// @brief Last (family) name.
+  std::string last_name{};
+
+  /// @brief Gender associated with the sampled forename (e.g. "M", "F"), as
+  /// reported by the source dataset.
+  std::string gender{};
+};
+
+/**
+ * @brief A single forename entry from the names-by-country fixture data.
+ */
+struct ForenameEntry {
+  /// @brief Romanized forename.
+  std::string name{};
+
+  /// @brief Gender associated with this forename, as reported by the source
+  /// dataset (e.g. "M", "F").
+  std::string gender{};
+};
+
+/**
+ * @brief A persona archetype used to ground LLM-generated user bios.
+ */
+struct UserPersona {
+  /// @brief Persona display name (e.g. "Hophead Explorer").
+  std::string name{};
+
+  /// @brief Short description of the persona's interests and voice.
+  std::string description{};
+
+  /// @brief Beer styles this persona gravitates toward.
+  std::vector<std::string> style_affinities{};
+};
+
 // ============================================================================
 // Configuration Models
 // ============================================================================
@@ -72,7 +119,7 @@ struct BreweryLocation {
  * @brief LLM sampling parameters.
  */
 struct SamplingOptions {
-  /// @brief LLM sampling temperature (0.0 to 1.0, higher = more random).
+  /// @brief LLM sampling temperature (higher = more random).
   float temperature = 1.0F;
 
   /// @brief LLM nucleus sampling top-p parameter.

tooling/pipeline/includes/data_model/names_by_country.h

@@ -0,0 +1,52 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_NAMES_BY_COUNTRY_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_NAMES_BY_COUNTRY_H_
+
+/**
+ * @file data_model/names_by_country.h
+ * @brief Sampling over the names-by-country fixture data.
+ */
+
+#include <optional>
+#include <random>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include "data_model/models.h"
+
+/**
+ * @brief Samples locale-appropriate names from curated forename/surname
+ * fixture data, keyed by ISO 3166-1 country code.
+ *
+ * Forenames and surnames are kept in separate maps (mirroring the source
+ * dataset's own shape) so per-forename gender is preserved; pairing happens
+ * at sample time rather than being precomputed, so no information from the
+ * source dataset is discarded up front.
+ */
+class NamesByCountry {
+ public:
+  NamesByCountry(
+      std::unordered_map<std::string, std::vector<ForenameEntry>>
+          forenames_by_country,
+      std::unordered_map<std::string, std::vector<std::string>>
+          surnames_by_country);
+
+  /**
+   * @brief Samples a first/last name pair for the given country.
+   *
+   * @param iso3166_1 ISO 3166-1 country code to sample for.
+   * @param rng Random source used for sampling.
+   * @return A sampled Name, or std::nullopt if the country has no forename
+   * or no surname entries.
+   */
+  [[nodiscard]] std::optional<Name> SampleName(const std::string& iso3166_1,
+                                               std::mt19937& rng) const;
+
+ private:
+  std::unordered_map<std::string, std::vector<ForenameEntry>>
+      forenames_by_country_;
+  std::unordered_map<std::string, std::vector<std::string>>
+      surnames_by_country_;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_NAMES_BY_COUNTRY_H_

tooling/pipeline/includes/json_handling/json_loader.h

@@ -11,6 +11,7 @@
 #include <vector>
 
 #include "data_model/models.h"
+#include "data_model/names_by_country.h"
 #include "services/logging/logger.h"
 
 /// @brief Loads curated world locations from a JSON file into memory.
@@ -20,6 +21,23 @@ class JsonLoader {
   static std::vector<Location> LoadLocations(
       const std::filesystem::path& filepath,
       std::shared_ptr<ILogger> logger = nullptr);
+
+  /// @brief Parses a JSON array file and returns all persona records.
+  static std::vector<UserPersona> LoadPersonas(
+      const std::filesystem::path& filepath,
+      std::shared_ptr<ILogger> logger = nullptr);
+
+  /**
+   * @brief Parses the names-by-country fixture pair into a sampling-capable
+   * NamesByCountry.
+   *
+   * @param forenames_filepath Path to forenames-by-country.json.
+   * @param surnames_filepath Path to surnames-by-country.json.
+   */
+  static NamesByCountry LoadNamesByCountry(
+      const std::filesystem::path& forenames_filepath,
+      const std::filesystem::path& surnames_filepath,
+      std::shared_ptr<ILogger> logger = nullptr);
 };
 
 #endif  // BIERGARTEN_PIPELINE_INCLUDES_JSON_HANDLING_JSON_LOADER_H_

tooling/pipeline/includes/services/database/export_service.h

@@ -35,6 +35,13 @@ class IExportService {
    */
   virtual uint64_t ProcessRecord(const GeneratedBrewery& brewery) = 0;
 
+  /**
+   * @brief Persists one generated user record.
+   *
+   * @param user Generated user payload to store.
+   */
+  virtual uint64_t ProcessRecord(const GeneratedUser& user) = 0;
+
   /// @brief Finalizes the export destination.
   virtual void Finalize() = 0;
 };

tooling/pipeline/includes/services/database/sqlite_export_service.h

@@ -31,6 +31,7 @@ class SqliteExportService final : public IExportService {
 
   void Initialize() override;
   uint64_t ProcessRecord(const GeneratedBrewery& brewery) override;
+  uint64_t ProcessRecord(const GeneratedUser& user) override;
   void Finalize() override;
 
  private:
@@ -46,6 +47,15 @@ class SqliteExportService final : public IExportService {
   [[nodiscard]] std::filesystem::path BuildDatabasePath() const;
   [[nodiscard]] static std::string BuildLocationKey(const Location& location);
 
+  /**
+   * @brief Returns the row id for @p location, inserting it first if it has
+   * not already been seen during this run.
+   *
+   * Shared by both ProcessRecord() overloads so breweries and users
+   * referencing the same location resolve to the same row.
+   */
+  [[nodiscard]] sqlite3_int64 ResolveLocationId(const Location& location);
+
   std::unique_ptr<IDateTimeProvider> date_time_provider_;
   std::filesystem::path output_path_;
   std::string run_timestamp_utc_;
@@ -53,6 +63,7 @@ class SqliteExportService final : public IExportService {
   SqliteDatabaseHandle db_handle_;
   SqliteStatementHandle insert_location_stmt_;
   SqliteStatementHandle insert_brewery_stmt_;
+  SqliteStatementHandle insert_user_stmt_;
   bool transaction_open_ = false;
   std::unordered_map<std::string, sqlite3_int64> location_cache_;
 };

tooling/pipeline/includes/services/database/sqlite_statement_helpers.h

@@ -50,6 +50,27 @@ CREATE INDEX IF NOT EXISTS idx_breweries_location_id ON breweries(location_id);
 
 )sql";
 
+inline constexpr std::string_view kCreateUsersTableSql = R"sql(
+
+CREATE TABLE IF NOT EXISTS users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  location_id INTEGER NOT NULL,
+  first_name TEXT NOT NULL,
+  last_name TEXT NOT NULL,
+  gender TEXT NOT NULL,
+  username TEXT NOT NULL,
+  bio TEXT NOT NULL,
+  activity_weight REAL NOT NULL,
+  email TEXT NOT NULL UNIQUE,
+  date_of_birth TEXT NOT NULL,
+  password TEXT NOT NULL,
+  FOREIGN KEY(location_id) REFERENCES locations(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_users_location_id ON users(location_id);
+
+)sql";
+
 inline constexpr std::string_view kInsertLocationSql = R"sql(
 INSERT INTO locations (
   city,
@@ -73,6 +94,21 @@ INSERT INTO breweries (
 ) VALUES (?, ?, ?, ?, ?);
 )sql";
 
+inline constexpr std::string_view kInsertUserSql = R"sql(
+INSERT INTO users (
+  location_id,
+  first_name,
+  last_name,
+  gender,
+  username,
+  bio,
+  activity_weight,
+  email,
+  date_of_birth,
+  password
+) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?);
+)sql";
+
 inline constexpr int kLocationCityBindIndex = 1;
 inline constexpr int kLocationStateProvinceBindIndex = 2;
 inline constexpr int kLocationIso31662BindIndex = 3;
@@ -88,6 +124,17 @@ inline constexpr int kBreweryEnglishDescriptionBindIndex = 3;
 inline constexpr int kBreweryLocalNameBindIndex = 4;
 inline constexpr int kBreweryLocalDescriptionBindIndex = 5;
 
+inline constexpr int kUserLocationIdBindIndex = 1;
+inline constexpr int kUserFirstNameBindIndex = 2;
+inline constexpr int kUserLastNameBindIndex = 3;
+inline constexpr int kUserGenderBindIndex = 4;
+inline constexpr int kUserUsernameBindIndex = 5;
+inline constexpr int kUserBioBindIndex = 6;
+inline constexpr int kUserActivityWeightBindIndex = 7;
+inline constexpr int kUserEmailBindIndex = 8;
+inline constexpr int kUserDateOfBirthBindIndex = 9;
+inline constexpr int kUserPasswordBindIndex = 10;
+
 SqliteStatementHandle PrepareStatement(const SqliteDatabaseHandle& db_handle,
                                        std::string_view sql,
                                        const char* action);

tooling/pipeline/includes/services/logging/log_entry.h

@@ -35,6 +35,7 @@ enum class LogLevel {
  */
 enum class PipelinePhase {
   Startup,                   ///< Initialization and validation.
+  Enrichment,                ///< Location/context enrichment (e.g. Wikipedia lookups).
   UserGeneration,            ///< User profile generation.
   BreweryAndBeerGeneration,  ///< Brewery and beer data generation.
   CheckinGeneration,         ///< Checkin (visit) record generation.

tooling/pipeline/personas.json

@@ -0,0 +1,42 @@
+[
+  {
+    "name": "Hophead Explorer",
+    "description": "Chases the newest hop varieties and double-digit IBUs, tracking hazy releases and limited tap takeovers across town.",
+    "style_affinities": ["American IPA", "Double IPA", "New England IPA", "Black IPA"]
+  },
+  {
+    "name": "Malt & Tradition Loyalist",
+    "description": "Prefers clean, balanced lagers brewed the way their region has brewed them for generations, and is quick to defend a well-made Helles.",
+    "style_affinities": ["Munich Helles", "Vienna Lager", "Märzen", "Festbier"]
+  },
+  {
+    "name": "Dark & Roasty Devotee",
+    "description": "Orders the darkest beer on the board year-round, drawn to roasted malt, coffee, and chocolate notes over carbonated lightness.",
+    "style_affinities": ["Imperial Stout", "Robust Porter", "Baltic Porter", "Oatmeal Stout"]
+  },
+  {
+    "name": "Sour & Wild Forager",
+    "description": "Seeks out barrel-aged, spontaneously fermented, and funky beers, and will travel for a fresh bottling of something wild.",
+    "style_affinities": ["Lambic", "Gueuze", "Flanders Red Ale", "Wild Ale"]
+  },
+  {
+    "name": "Session Sipper",
+    "description": "Values an easy-drinking pint that holds up over a long afternoon at the taproom more than raw intensity or novelty.",
+    "style_affinities": ["Session IPA", "Ordinary Bitter", "Cream Ale", "Blonde Ale"]
+  },
+  {
+    "name": "Belgian Abbey Pilgrim",
+    "description": "Collects abbey and trappist releases, drawn to the dried-fruit esters and warming strength of classic Belgian ales.",
+    "style_affinities": ["Belgian Tripel", "Belgian Dubbel", "Belgian Quadrupel", "Trappist Single"]
+  },
+  {
+    "name": "Wheat & Citrus Casual",
+    "description": "Reaches for something light, cloudy, and refreshing, usually with a citrus or coriander note, especially on a patio in summer.",
+    "style_affinities": ["Hefeweizen", "Witbier", "American Wheat Beer", "Berliner Weisse"]
+  },
+  {
+    "name": "Big & Boozy Connoisseur",
+    "description": "Sips slowly from a snifter, seeking out high-ABV releases meant for aging and savoring rather than quick refreshment.",
+    "style_affinities": ["English Barleywine", "Wee Heavy", "Doppelbock", "Old Ale"]
+  }
+]

tooling/pipeline/prompts/USER_GENERATION.md

@@ -0,0 +1,122 @@
+# FULL SYSTEM PROMPT
+
+You are a craft beer community profile writer. You write short, first-person
+biographies for fictional users of a brewery-discovery app, grounded in the
+exact name, locale, and persona provided. You do not invent the user's name --
+it is given to you and must not be altered, translated, or abbreviated beyond
+forming a username.
+
+You will receive the inputs like this:
+
+## NAME:
+
+[First name] [Last name]
+
+## GENDER:
+
+[Gender associated with the given first name]
+
+## CITY:
+
+[City Name]
+
+## COUNTRY:
+
+[Country Name]
+
+## PERSONA:
+
+[Persona archetype name]
+
+## PERSONA DESCRIPTION:
+
+[What this persona cares about and how they talk about beer]
+
+## STYLE AFFINITIES:
+
+[Comma-separated beer styles this persona favors]
+
+## CRITICAL OUTPUT FORMAT (READ CAREFULLY):
+
+ABSOLUTELY NO MARKDOWN FORMATTING. Do NOT wrap your response in json or ```
+blocks.
+
+Do not add markdown, code fences, or postscript around the final JSON object.
+Do not say "Here is the JSON" or "Enjoy!".
+
+The JSON must contain exactly three keys ("username", "bio",
+"activity_weight") in that order. Do not rename or add any other keys.
+
+ESCAPE ALL QUOTES inside the bio field using \", or use single quotes (' ')
+instead.
+
+DO NOT use actual line breaks (\n) inside any string. Keep the bio as one
+continuous string.
+
+The bio must be between 25 and 60 words, written in first person, and must
+read as something this specific person would write about themselves -- not a
+generic profile blurb.
+
+`activity_weight` is a number between 0 and 1 (inclusive) representing how
+often this persona checks in at breweries relative to other users. Persona
+archetypes implying frequent, habitual brewery visits should skew higher;
+casual or occasional-visitor personas should skew lower. Do not default to
+0.5 -- vary it meaningfully based on the persona description.
+
+Expected JSON format:
+
+```json
+{
+  "username": "a handle derived from the given name",
+  "bio": "The first-person bio goes here.",
+  "activity_weight": 0.62
+}
+```
+
+## CONTENT RULES AND CONSTRAINTS:
+
+### THE USERNAME:
+
+Derive the username from the given first and/or last name (e.g. lowercase,
+abbreviated, or combined with a short word or number tied to the persona's
+style affinities). Do not invent an unrelated handle. Do not include spaces.
+
+### THE BIO:
+
+Ground the bio in the supplied persona description and style affinities --
+mention at least one specific beer style from the style affinities list, in a
+way that sounds like a personal preference rather than a list. Reference the
+city or country naturally if it fits, but do not force it.
+
+### VOICE & PERSPECTIVE:
+
+Write in the first person ("I"/"my"). The tone should match the persona:
+an enthusiastic explorer sounds different from a relaxed, easy-drinking
+regular. Do not write in second or third person.
+
+### THE BLOCKLIST (FORBIDDEN CONCEPTS):
+
+You absolutely cannot use the following words and phrases. Make sure your
+final output doesn't have any of these:
+
+- "hidden gem"
+- "passion"
+- "authentic"
+- "craft beer enthusiast"
+- "beer connoisseur"
+- "journey"
+
+#### FORBIDDEN WRITING PATTERNS
+
+The following patterns are common AI writing pitfalls and must not appear in
+the bio:
+
+- Negative parallelism constructions: "It's not X, it's Y"
+- Inflated significance phrases: "stands as a testament," "plays a vital
+  role," "deeply rooted"
+- Superficial trailing analyses: sentences ending in -ing words that add
+  opinion without content
+- Promotional travel-copy tone: "breathtaking," "must-visit," "vibrant"
+- Overused conjunctive transitions used as sentence openers: "Moreover,"
+  "Furthermore," "In addition"
+- Rule of three: do not consistently organise ideas or examples in triplets

tooling/pipeline/runpod/pod-template.yaml

@@ -10,11 +10,10 @@ dockerStartCmd: []
 isPublic: false
 isServerless: false
 env:
-  BIERGARTEN_MODE: live
   BIERGARTEN_MODEL_PATH: /workspace/models/google_gemma-4-E4B-it-Q6_K.gguf
-  BIERGARTEN_PROMPT_DIR: /workspace/app/build/prompts
   BIERGARTEN_OUTPUT_DIR: /workspace/output
   BIERGARTEN_LOG_PATH: /workspace/logs/pipeline.log
+  BIERGARTEN_GL_LAYERS: "40"
   BIERGARTEN_TEMPERATURE: "1.0"
   BIERGARTEN_TOP_P: "0.95"
   BIERGARTEN_TOP_K: "64"

tooling/pipeline/src/application_options/parse_arguments.cc

@@ -15,8 +15,6 @@ std::optional<ApplicationOptions> ParseArguments(
 
   opt("help,h", "Produce help message");
 
-  // Defaults sourced from SamplingOptions{} so the CLI and LlamaGenerator
-  // share a single source of truth — changing the struct updates both.
   auto add_sampling_options = [&]() -> void {
     const SamplingOptions sampling_defaults{};
     opt("temperature",
@@ -152,7 +150,6 @@ std::optional<ApplicationOptions> ParseArguments(
 
     options.generator.use_mocked = use_mocked;
     options.generator.model_path = model_path;
-    // options.generator.n_gpu_layers = n_gpu_layers;
 
     // Only populate sampling config when the user explicitly overrides at
     // least one value. Leaving it as std::nullopt lets LlamaGenerator fall

tooling/pipeline/src/biergarten_pipeline_orchestrator/generate_users.cc

@@ -0,0 +1,186 @@
+/**
+ * @file biergarten_pipeline_orchestrator/generate_users.cc
+ * @brief BiergartenDataGenerator::GenerateUsers() implementation.
+ */
+
+#include <cctype>
+#include <chrono>
+#include <format>
+#include <optional>
+#include <random>
+#include <stdexcept>
+#include <string>
+#include <string_view>
+#include <unordered_set>
+
+#include "biergarten_pipeline_orchestrator.h"
+#include "json_handling/json_loader.h"
+#include "services/logging/logger.h"
+
+namespace {
+
+std::string Sanitize(std::string_view value) {
+  std::string out;
+  out.reserve(value.size());
+  for (const char character : value) {
+    if (std::isalnum(static_cast<unsigned char>(character)) != 0) {
+      out.push_back(
+          static_cast<char>(std::tolower(static_cast<unsigned char>(character))));
+    }
+  }
+  return out;
+}
+
+std::string BuildEmail(const Name& name,
+                       std::unordered_set<std::string>& used_local_parts) {
+  const std::string base =
+      std::format("{}.{}", Sanitize(name.first_name), Sanitize(name.last_name));
+
+  std::string local_part = base;
+  for (int suffix = 1; used_local_parts.contains(local_part); ++suffix) {
+    local_part = std::format("{}{}", base, suffix);
+  }
+  used_local_parts.insert(local_part);
+
+  return std::format("{}@thebiergarten.app", local_part);
+}
+
+std::string GenerateDateOfBirth(std::mt19937& rng) {
+  using namespace std::chrono;
+
+  constexpr int kMinAge = 19;
+  constexpr int kMaxAge = 48;
+  constexpr int kMaxDayOffset = 364;
+
+  std::uniform_int_distribution<int> age_dist(kMinAge, kMaxAge);
+  std::uniform_int_distribution<int> day_offset_dist(0, kMaxDayOffset);
+
+  const year_month_day today{floor<days>(system_clock::now())};
+  const year_month_day birth_year_anchor{today.year() - years{age_dist(rng)},
+                                         today.month(), today.day()};
+  const sys_days birth_date =
+      sys_days{birth_year_anchor} - days{day_offset_dist(rng)};
+  const year_month_day birth_ymd{birth_date};
+
+  return std::format("{:04}-{:02}-{:02}",
+                     static_cast<int>(birth_ymd.year()),
+                     static_cast<unsigned>(birth_ymd.month()),
+                     static_cast<unsigned>(birth_ymd.day()));
+}
+
+std::string GenerateRandomPassword(std::mt19937& rng) {
+  constexpr size_t kPasswordLength = 32;
+  constexpr std::string_view kCharset =
+      "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*";
+
+  std::uniform_int_distribution<size_t> char_dist(0, kCharset.size() - 1);
+
+  std::string password;
+  password.reserve(kPasswordLength);
+  for (size_t i = 0; i < kPasswordLength; ++i) {
+    password.push_back(kCharset[char_dist(rng)]);
+  }
+  return password;
+}
+
+}  // namespace
+
+void BiergartenPipelineOrchestrator::GenerateUsers(
+    std::span<const EnrichedCity> cities) {
+  logger_->Log({.level = LogLevel::Info,
+                .phase = PipelinePhase::UserGeneration,
+                .message = "=== SAMPLE USER GENERATION ==="});
+
+  const std::vector<UserPersona> personas =
+      JsonLoader::LoadPersonas("personas.json", logger_);
+  if (personas.empty()) {
+    throw std::runtime_error(
+        "No personas available in personas.json for user generation");
+  }
+
+  const NamesByCountry names_by_country = JsonLoader::LoadNamesByCountry(
+      "forenames-by-country.json", "surnames-by-country.json", logger_);
+
+  std::mt19937 rng(std::random_device{}());
+  std::uniform_int_distribution<size_t> persona_dist(0, personas.size() - 1);
+
+  generated_users_.clear();
+  std::unordered_set<std::string> used_email_local_parts;
+  size_t skipped_count = 0;
+  size_t export_failed_count = 0;
+
+  for (const auto& city : cities) {
+    const std::optional<Name> sampled_name =
+        names_by_country.SampleName(city.location.iso3166_1, rng);
+
+    if (!sampled_name.has_value()) {
+      ++skipped_count;
+      logger_->Log(
+          {.level = LogLevel::Warn,
+           .phase = PipelinePhase::UserGeneration,
+           .message = std::format(
+               "[Pipeline] Skipping city '{}' ({}): no names available for "
+               "country '{}'",
+               city.location.city, city.location.country,
+               city.location.iso3166_1)});
+      continue;
+    }
+
+    const UserPersona& persona = personas[persona_dist(rng)];
+
+    try {
+      const UserResult user =
+          generator_->GenerateUser(city, persona, *sampled_name);
+
+      const GeneratedUser generated_user{
+          .location = city.location,
+          .user = user,
+          .email = BuildEmail(*sampled_name, used_email_local_parts),
+          .date_of_birth = GenerateDateOfBirth(rng),
+          .password = GenerateRandomPassword(rng),
+      };
+
+      generated_users_.push_back(generated_user);
+
+      try {
+        exporter_->ProcessRecord(generated_user);
+      } catch (const std::exception& export_exception) {
+        ++export_failed_count;
+
+        logger_->Log(
+            {.level = LogLevel::Warn,
+             .phase = PipelinePhase::UserGeneration,
+             .message = std::format(
+                 "[Pipeline] Generated user for '{}' ({}) but SQLite export failed: {}",
+                 city.location.city, city.location.country,
+                 export_exception.what())});
+      }
+    } catch (const std::exception& e) {
+      ++skipped_count;
+      logger_->Log(
+          {.level = LogLevel::Warn,
+           .phase = PipelinePhase::UserGeneration,
+           .message = std::format(
+               "[Pipeline] Skipping city '{}' ({}): user generation failed: {}",
+               city.location.city, city.location.country, e.what())});
+    }
+  }
+
+  if (skipped_count > 0) {
+    logger_->Log(
+        {.level = LogLevel::Warn,
+         .phase = PipelinePhase::UserGeneration,
+         .message = std::format(
+             "[Pipeline] Skipped {} city/cities during user generation",
+             skipped_count)});
+  }
+
+  if (export_failed_count > 0) {
+    logger_->Log(
+        {.level = LogLevel::Warn,
+         .phase = PipelinePhase::Teardown,
+         .message = std::format(
+             "[Pipeline] Failed to export {} generated user/users to SQLite",
+             export_failed_count)});
+  }
+}

tooling/pipeline/src/biergarten_pipeline_orchestrator/log_results.cc

@@ -10,11 +10,12 @@
 #include "../../includes/json_handling/pretty_print.h"
 #include "biergarten_pipeline_orchestrator.h"
 #include "services/logging/logger.h"
+
 void BiergartenPipelineOrchestrator::LogResults() const {
-  boost::json::array output;
+  boost::json::array brewery_output;
 
   for (const auto& [location, brewery] : generated_breweries_) {
-    output.push_back(boost::json::object{
+    brewery_output.push_back(boost::json::object{
         {"name_en", brewery.name_en},
         {"description_en", brewery.description_en},
         {"name_local", brewery.name_local},
@@ -29,9 +30,31 @@ void BiergartenPipelineOrchestrator::LogResults() const {
                      }}});
   }
 
-  std::ostringstream oss;
+  std::ostringstream brewery_oss;
-  PrettyPrint(oss, output);
+  PrettyPrint(brewery_oss, brewery_output);
   logger_->Log({.level = LogLevel::Info,
                 .phase = PipelinePhase::Teardown,
-                .message = oss.str()});
+                .message = brewery_oss.str()});
+
+  boost::json::array user_output;
+
+
+  for (const auto& generated_user : generated_users_) {
+    user_output.push_back(boost::json::object{
+        {"first_name", generated_user.user.first_name},
+        {"last_name", generated_user.user.last_name},
+        {"gender", generated_user.user.gender},
+        {"username", generated_user.user.username},
+        {"bio", generated_user.user.bio},
+        {"activity_weight", generated_user.user.activity_weight},
+        {"email", generated_user.email},
+        {"date_of_birth", generated_user.date_of_birth},
+    });
+  }
+
+  std::ostringstream user_oss;
+  PrettyPrint(user_oss, user_output);
+  logger_->Log({.level = LogLevel::Info,
+                .phase = PipelinePhase::Teardown,
+                .message = user_oss.str()});
 }

tooling/pipeline/src/biergarten_pipeline_orchestrator/run.cc

@@ -22,9 +22,6 @@ bool BiergartenPipelineOrchestrator::Run() {
     for (auto& city : cities) {
       try {
         std::string region_context = context_service_->GetLocationContext(city);
-        // logger_->Log(LogLevel::Debug, PipelinePhase::UserGeneration,
-        //              "[Pipeline] Context for '" + city.city + "' (" +
-        //              city.iso3166_2 + ") gathered:\n" + region_context);
 
         enriched.push_back(
             EnrichedCity{.location = std::move(city),
@@ -33,7 +30,7 @@ bool BiergartenPipelineOrchestrator::Run() {
         ++skipped_count;
         logger_->Log(
             {.level = LogLevel::Warn,
-             .phase = PipelinePhase::UserGeneration,
+             .phase = PipelinePhase::Enrichment,
              .message = std::format(
                  "[Pipeline] Skipping city '{}' ({}): context lookup failed: {}",
                  city.city, city.country, exception.what())});
@@ -42,12 +39,13 @@ bool BiergartenPipelineOrchestrator::Run() {
 
     if (skipped_count > 0) {
       logger_->Log({.level = LogLevel::Warn,
-                    .phase = PipelinePhase::UserGeneration,
+                    .phase = PipelinePhase::Enrichment,
                     .message = std::format(
                         "[Pipeline] Skipped {} city/cities due to context lookup errors",
                         skipped_count)});
     }
 
+    this->GenerateUsers(enriched);
     this->GenerateBreweries(enriched);
     exporter_->Finalize();
     this->LogResults();

tooling/pipeline/src/data_generation/llama/generate_brewery.cc

@@ -91,7 +91,6 @@ BreweryResult LlamaGenerator::GenerateBrewery(
   std::string last_error;
 
   // Token budget: too small risks truncating valid JSON mid-string.
-  // Start conservatively but allow adaptive increases on truncation.
   int max_tokens = kBreweryInitialMaxTokens;
 
   // Limit output length to keep it concise and focused

tooling/pipeline/src/data_generation/llama/generate_user.cc

@@ -1,24 +1,121 @@
 /**
  * @file data_generation/llama/generate_user.cc
- * @brief Generates locale-aware user profiles with strict two-line formatting,
+ * @brief Builds persona/name-grounded user prompts, performs retry-based
- * retry handling, and output sanitization for downstream parsing.
+ * inference, and validates structured JSON output for user records.
  */
 
-
 #include <format>
+#include <optional>
+#include <stdexcept>
 #include <string>
+#include <string_view>
 
 #include "data_generation/llama_generator.h"
 #include "data_generation/llama_generator_helpers.h"
 
-// TODO: Implement locale-aware user profile generation.
+// GBNF grammar for structured user JSON output.
-// Current implementation returns a hardcoded test value and ignores the
+static constexpr std::string_view kUserJsonGrammar = R"json_user(
-// locale parameter. Future implementation should:
+root ::= thought-block "{" ws "\"username\"" ws ":" ws string ws "," ws "\"bio\"" ws ":" ws string ws "," ws "\"activity_weight\"" ws ":" ws number ws "}" ws
-// 1. Load a USER_GENERATION.md prompt template with locale context
+thought-block ::= [^{]*
-// 2. Perform LLM inference with locale-specific username/bio generation
+ws ::= [ \t\n\r]*
-// 3. Parse and validate JSON output with retry handling (similar to brewery)
+string ::= "\"" char+ "\""
-// 4. Return locale-aware username and biography
+char ::= [^"\\\x7F\x00-\x1F] | [\\] escape
-UserResult LlamaGenerator::GenerateUser(const std::string& locale) {
+escape ::= ["\\/bfnrt] | "u" hex hex hex hex
-  return {.username = "test_user",
+hex ::= [0-9a-fA-F]
-          .bio = std::format("This is a test user profile from {}.", locale)};
+number ::= "-"? ("0" | [1-9] [0-9]*) ("." [0-9]+)?
+)json_user";
+
+static constexpr int kUserInitialMaxTokens = 1200;
+
+UserResult LlamaGenerator::GenerateUser(const EnrichedCity& city,
+                                        const UserPersona& persona,
+                                        const Name& name) {
+  std::string style_affinities;
+  for (const std::string& style : persona.style_affinities) {
+    if (!style_affinities.empty()) {
+      style_affinities += ", ";
+    }
+    style_affinities += style;
+  }
+
+  const std::string system_prompt = prompt_directory_->Load("USER_GENERATION");
+
+  std::string user_prompt = std::format(
+      "## NAME:\n{} {}\n\n## GENDER:\n{}\n\n## CITY:\n{}\n\n## COUNTRY:\n{}\n\n"
+      "## PERSONA:\n{}\n\n## PERSONA DESCRIPTION:\n{}\n\n## STYLE "
+      "AFFINITIES:\n{}",
+      name.first_name, name.last_name, name.gender, city.location.city,
+      city.location.country, persona.name, persona.description,
+      style_affinities);
+
+  const std::string retry_context =
+      std::format("Name: {} {}\nCity: {}, {}\nPersona: {}", name.first_name,
+                 name.last_name, city.location.city, city.location.country,
+                 persona.name);
+
+  constexpr int max_attempts = 3;
+  std::string raw;
+  std::string last_error;
+  int max_tokens = kUserInitialMaxTokens;
+
+  for (int attempt = 0; attempt < max_attempts; ++attempt) {
+    raw = this->Infer(system_prompt, user_prompt, max_tokens,
+                      kUserJsonGrammar);
+    if (logger_) {
+      logger_->Log(
+          {.level = LogLevel::Debug,
+           .phase = PipelinePhase::UserGeneration,
+           .message = std::format("LlamaGenerator: raw output (attempt {}): {}",
+                      attempt + 1, raw)});
+    }
+
+    UserResult user;
+    const std::optional<std::string> validation_error =
+        ValidateUserJson(raw, user);
+
+    if (!validation_error.has_value()) {
+      if (logger_) {
+        logger_->Log(
+            {.level = LogLevel::Info,
+             .phase = PipelinePhase::UserGeneration,
+             .message = std::format("LlamaGenerator: successfully generated user data on attempt {}",
+                        attempt + 1)});
+      }
+
+      user.first_name = name.first_name;
+      user.last_name = name.last_name;
+      user.gender = name.gender;
+      return user;
+    }
+
+    last_error = *validation_error;
+    if (logger_) {
+      logger_->Log(
+          {.level = LogLevel::Warn,
+           .phase = PipelinePhase::UserGeneration,
+           .message =
+               std::format("LlamaGenerator: malformed user JSON (attempt {}): {}",
+               attempt + 1, *validation_error)});
+    }
+
+    user_prompt = std::format(
+        "Your previous response was invalid. Error: {}\nReturn the thought "
+        "process before the JSON if needed, then return ONLY valid JSON with "
+        "exactly these keys, in this exact order: {{\"username\": \"<handle "
+        "derived from the given name>\", \"bio\": \"<first-person bio "
+        "grounded in the persona>\", \"activity_weight\": <number between 0 "
+        "and 1>}}.\nDo not include markdown, comments, extra keys, or "
+        "literal placeholder values.\n\n{}",
+        *validation_error, retry_context);
+  }
+
+  if (logger_) {
+    logger_->Log(
+        {.level = LogLevel::Error,
+         .phase = PipelinePhase::UserGeneration,
+       .message = std::format(
+         "LlamaGenerator: malformed user response after {} attempts: {}",
+         max_attempts, last_error.empty() ? raw : last_error)});
+  }
+  throw std::runtime_error("LlamaGenerator: malformed user response");
 }

tooling/pipeline/src/data_generation/llama/helpers.cc

@@ -9,6 +9,7 @@
 #include <boost/json.hpp>
 #include <cctype>
 #include <optional>
+#include <span>
 #include <stdexcept>
 #include <string>
 #include <string_view>
@@ -76,7 +77,7 @@ bool ReadRequiredTrimmedStringField(const boost::json::object& obj,
   return !out.empty();
 }
 
-bool HasSchemaPlaceholder(const std::array<std::string*, 4>& values) {
+bool HasSchemaPlaceholder(std::span<std::string* const> values) {
   for (const std::string* value : values) {
     std::string lowered = *value;
     std::ranges::transform(lowered, lowered.begin(),
@@ -207,3 +208,58 @@ std::optional<std::string> ValidateBreweryJson(const std::string& raw,
 
   return std::nullopt;
 }
+
+std::optional<std::string> ValidateUserJson(const std::string& raw,
+                                            UserResult& user_out) {
+  boost::system::error_code error_code;
+  const std::string_view raw_view(raw);
+  const size_t opening_brace = raw_view.find('{');
+  if (opening_brace == std::string_view::npos) {
+    return "JSON parse error: missing opening brace '{'";
+  }
+
+  const std::string_view json_payload = raw_view.substr(opening_brace);
+  boost::json::value json_value = boost::json::parse(json_payload, error_code);
+  if (error_code) {
+    return "JSON parse error: " + error_code.message();
+  }
+
+  if (!json_value.is_object()) {
+    return "JSON root must be an object";
+  }
+
+  const auto& obj = json_value.get_object();
+  if (obj.size() != 3) {
+    return "JSON object must contain exactly three keys";
+  }
+
+  std::string validation_error;
+  if (!ReadRequiredTrimmedStringField(obj, "username", user_out.username,
+                                      &validation_error)) {
+    return validation_error;
+  }
+
+  if (!ReadRequiredTrimmedStringField(obj, "bio", user_out.bio,
+                                      &validation_error)) {
+    return validation_error;
+  }
+
+  const boost::json::value* activity_weight_field =
+      obj.if_contains("activity_weight");
+  if (activity_weight_field == nullptr || !activity_weight_field->is_number()) {
+    return "Missing or invalid numeric field: activity_weight";
+  }
+
+  const double activity_weight = activity_weight_field->to_number<double>();
+  if (activity_weight < 0.0 || activity_weight > 1.0) {
+    return "activity_weight must be between 0 and 1";
+  }
+  user_out.activity_weight = static_cast<float>(activity_weight);
+
+  const std::array schema_placeholders = {&user_out.username, &user_out.bio};
+  if (HasSchemaPlaceholder(schema_placeholders)) {
+    return "JSON appears to be a schema placeholder, not content";
+  }
+
+  return std::nullopt;
+}

tooling/pipeline/src/data_generation/mock/deterministic_hash.cc

@@ -14,3 +14,13 @@ size_t MockGenerator::DeterministicHash(const Location& location) {
   boost::hash_combine(seed, location.country);
   return seed;
 }
+
+size_t MockGenerator::DeterministicHash(const Location& location,
+                                        const UserPersona& persona,
+                                        const Name& name) {
+  size_t seed = DeterministicHash(location);
+  boost::hash_combine(seed, persona.name);
+  boost::hash_combine(seed, name.first_name);
+  boost::hash_combine(seed, name.last_name);
+  return seed;
+}

tooling/pipeline/src/data_generation/mock/generate_user.cc

@@ -1,22 +1,31 @@
 /**
  * @file data_generation/mock/generate_user.cc
- * @brief Generates deterministic mock user profiles by hashing locale values
+ * @brief Generates deterministic mock user profiles by hashing city, persona,
- * into predefined username and bio collections.
+ * and sampled name into predefined username and bio collections.
  */
 
-#include <functional>
-#include <string>
 #include <string_view>
 
 #include "data_generation/mock_generator.h"
 
-UserResult MockGenerator::GenerateUser(const std::string& locale) {
+UserResult MockGenerator::GenerateUser(const EnrichedCity& city,
-  const size_t hash = std::hash<std::string>{}(locale);
+                                       const UserPersona& persona,
+                                       const Name& name) {
+  const size_t hash = DeterministicHash(city.location, persona, name);
 
-  UserResult result;
   const std::string_view username = kUsernames[hash % kUsernames.size()];
   const std::string_view bio = kBios[hash / kBioHashStride % kBios.size()];
-  result.username = username;
+  const float activity_weight =
-  result.bio = bio;
+      static_cast<float>(hash / kActivityWeightHashStride %
-  return result;
+                         kActivityWeightHashRange) /
+      static_cast<float>(kActivityWeightHashRange);
+
+  return {
+      .first_name = name.first_name,
+      .last_name = name.last_name,
+      .gender = name.gender,
+      .username = std::string(username),
+      .bio = std::string(bio),
+      .activity_weight = activity_weight,
+  };
 }

tooling/pipeline/src/data_model/names_by_country.cc

@@ -0,0 +1,41 @@
+/**
+ * @file data_model/names_by_country.cc
+ * @brief NamesByCountry::SampleName() implementation.
+ */
+
+#include "data_model/names_by_country.h"
+
+#include <utility>
+
+NamesByCountry::NamesByCountry(
+    std::unordered_map<std::string, std::vector<ForenameEntry>>
+        forenames_by_country,
+    std::unordered_map<std::string, std::vector<std::string>>
+        surnames_by_country)
+    : forenames_by_country_(std::move(forenames_by_country)),
+      surnames_by_country_(std::move(surnames_by_country)) {}
+
+std::optional<Name> NamesByCountry::SampleName(const std::string& iso3166_1,
+                                               std::mt19937& rng) const {
+  const auto forenames_it = forenames_by_country_.find(iso3166_1);
+  const auto surnames_it = surnames_by_country_.find(iso3166_1);
+
+  if (forenames_it == forenames_by_country_.end() ||
+      surnames_it == surnames_by_country_.end() ||
+      forenames_it->second.empty() || surnames_it->second.empty()) {
+    return std::nullopt;
+  }
+
+  const std::vector<ForenameEntry>& forenames = forenames_it->second;
+  const std::vector<std::string>& surnames = surnames_it->second;
+
+  std::uniform_int_distribution<size_t> forename_dist(0,
+                                                       forenames.size() - 1);
+  std::uniform_int_distribution<size_t> surname_dist(0, surnames.size() - 1);
+
+  const ForenameEntry& forename = forenames[forename_dist(rng)];
+
+  return Name{.first_name = forename.name,
+              .last_name = surnames[surname_dist(rng)],
+              .gender = forename.gender};
+}

tooling/pipeline/src/json_handling/json_loader.cc

@@ -16,6 +16,8 @@
 #include <stdexcept>
 #include <string>
 #include <string_view>
+#include <unordered_map>
+#include <utility>
 
 static std::string ReadRequiredString(const boost::json::object& object,
                                       const char* key) {
@@ -59,24 +61,53 @@ static std::vector<std::string> ReadRequiredStringArray(
   return items;
 }
 
-std::vector<Location> JsonLoader::LoadLocations(
+namespace {
-    const std::filesystem::path& filepath, std::shared_ptr<ILogger> logger) {
+
+boost::json::value ParseJsonFile(const std::filesystem::path& filepath,
+                                 const char* what) {
   std::ifstream input(filepath);
   if (!input.is_open()) {
-    throw std::runtime_error("Failed to open locations file: " +
+    throw std::runtime_error(std::format("Failed to open {} file: {}", what,
-                             filepath.string());
+                                         filepath.string()));
   }
 
   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);
+  boost::json::value root = boost::json::parse(buffer.str(), error);
   if (error) {
-    throw std::runtime_error("Failed to parse locations JSON: " +
+    throw std::runtime_error(
-                             error.message());
+        std::format("Failed to parse {} JSON: {}", what, error.message()));
   }
+  return root;
+}
+
+/// @brief Returns the first element of a string array field, falling back to
+/// `fallback_key` if `key` is missing/empty (some source entries only have a
+/// "localized" form and no "romanized" form).
+std::string ReadFirstOfStringArray(const boost::json::object& object,
+                                   const char* key,
+                                   const char* fallback_key) {
+  for (const char* candidate_key : {key, fallback_key}) {
+    const boost::json::value* value = object.if_contains(candidate_key);
+    if (value == nullptr || !value->is_array()) {
+      continue;
+    }
+    const auto& array = value->as_array();
+    if (!array.empty() && array.front().is_string()) {
+      return std::string(array.front().as_string());
+    }
+  }
+  throw std::runtime_error(
+      std::format("Missing or invalid string array field: {}", key));
+}
+
+}  // namespace
+
+std::vector<Location> JsonLoader::LoadLocations(
+    const std::filesystem::path& filepath, std::shared_ptr<ILogger> logger) {
+  const boost::json::value root = ParseJsonFile(filepath, "locations");
 
   if (!root.is_array()) {
     throw std::runtime_error(
@@ -108,3 +139,100 @@ std::vector<Location> JsonLoader::LoadLocations(
 
   return locations;
 }
+
+std::vector<UserPersona> JsonLoader::LoadPersonas(
+    const std::filesystem::path& filepath, std::shared_ptr<ILogger> logger) {
+  const boost::json::value root = ParseJsonFile(filepath, "personas");
+
+  if (!root.is_array()) {
+    throw std::runtime_error(
+        "Invalid personas JSON: root element must be an array");
+  }
+
+  std::vector<UserPersona> personas;
+  const auto& items = root.as_array();
+  personas.reserve(items.size());
+
+  for (const auto& item : items) {
+    if (!item.is_object()) {
+      throw std::runtime_error(
+          "Invalid personas JSON: each entry must be an object");
+    }
+
+    const auto& object = item.as_object();
+    personas.push_back(UserPersona{
+        .name = ReadRequiredString(object, "name"),
+        .description = ReadRequiredString(object, "description"),
+        .style_affinities =
+            ReadRequiredStringArray(object, "style_affinities"),
+    });
+  }
+
+  return personas;
+}
+
+NamesByCountry JsonLoader::LoadNamesByCountry(
+    const std::filesystem::path& forenames_filepath,
+    const std::filesystem::path& surnames_filepath,
+    std::shared_ptr<ILogger> logger) {
+  const boost::json::value forenames_root =
+      ParseJsonFile(forenames_filepath, "forenames-by-country");
+  const boost::json::value surnames_root =
+      ParseJsonFile(surnames_filepath, "surnames-by-country");
+
+  if (!forenames_root.is_object() || !surnames_root.is_object()) {
+    throw std::runtime_error(
+        "Invalid names-by-country JSON: root element must be an object "
+        "keyed by ISO 3166-1 country code");
+  }
+
+  std::unordered_map<std::string, std::vector<ForenameEntry>>
+      forenames_by_country;
+  for (const auto& [country_code, regions] : forenames_root.as_object()) {
+    if (!regions.is_array()) {
+      continue;
+    }
+    std::vector<ForenameEntry> entries;
+    for (const auto& region : regions.as_array()) {
+      if (!region.is_object()) {
+        continue;
+      }
+      const boost::json::value* names = region.as_object().if_contains("names");
+      if (names == nullptr || !names->is_array()) {
+        continue;
+      }
+      for (const auto& name_value : names->as_array()) {
+        if (!name_value.is_object()) {
+          continue;
+        }
+        const auto& name_object = name_value.as_object();
+        entries.push_back(ForenameEntry{
+            .name = ReadFirstOfStringArray(name_object, "romanized",
+                                           "localized"),
+            .gender = ReadRequiredString(name_object, "gender"),
+        });
+      }
+    }
+    forenames_by_country.emplace(country_code, std::move(entries));
+  }
+
+  std::unordered_map<std::string, std::vector<std::string>>
+      surnames_by_country;
+  for (const auto& [country_code, name_entries] : surnames_root.as_object()) {
+    if (!name_entries.is_array()) {
+      continue;
+    }
+    std::vector<std::string> surnames;
+    for (const auto& name_value : name_entries.as_array()) {
+      if (!name_value.is_object()) {
+        continue;
+      }
+      surnames.push_back(ReadFirstOfStringArray(name_value.as_object(),
+                                                "romanized", "localized"));
+    }
+    surnames_by_country.emplace(country_code, std::move(surnames));
+  }
+
+  return NamesByCountry(std::move(forenames_by_country),
+                        std::move(surnames_by_country));
+}

tooling/pipeline/src/main.cc

@@ -53,6 +53,7 @@ int main(const int argc, char** argv) {
       std::make_shared<LogProducer>(log_channel);
 
   std::thread log_thread([&log_dispatcher] { log_dispatcher->Run(); });
+
   auto shutdown = [&](const int exit_code) {
     log_channel.Close();
     log_thread.join();

tooling/pipeline/src/services/enrichment/wikipedia/fetch_extract.cc

@@ -21,7 +21,7 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
       cache_it != this->extract_cache_.end()) {
     if (logger_) {
       logger_->Log({.level = LogLevel::Debug,
-                    .phase = PipelinePhase::UserGeneration,
+                    .phase = PipelinePhase::Enrichment,
                     .message = std::format("Wikipedia: Cache hit for {}!", cache_key)});
     }
     return cache_it->second;
@@ -47,7 +47,7 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
     if (logger_) {
       logger_->Log(
           {.level = LogLevel::Warn,
-           .phase = PipelinePhase::UserGeneration,
+           .phase = PipelinePhase::Enrichment,
            .message = std::format("WikipediaService: JSON parse error for '{}': {}",
                       std::string(query), ec.message())});
     }
@@ -60,7 +60,7 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
     if (logger_) {
       logger_->Log(
           {.level = LogLevel::Warn,
-           .phase = PipelinePhase::UserGeneration,
+           .phase = PipelinePhase::Enrichment,
            .message =
                std::format("WikipediaService: Expected root object for '{}'",
                std::string(query))});
@@ -78,7 +78,7 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
     if (logger_) {
       logger_->Log(
           {.level = LogLevel::Warn,
-           .phase = PipelinePhase::UserGeneration,
+           .phase = PipelinePhase::Enrichment,
            .message =
                std::format("WikipediaService: Missing query.pages for '{}'",
                std::string(query))});
@@ -92,7 +92,7 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
     if (logger_) {
       logger_->Log(
           {.level = LogLevel::Warn,
-           .phase = PipelinePhase::UserGeneration,
+           .phase = PipelinePhase::Enrichment,
            .message = std::format("WikipediaService: No pages returned for '{}'",
                       std::string(query))});
     }
@@ -108,7 +108,7 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
     if (logger_) {
       logger_->Log(
           {.level = LogLevel::Warn,
-           .phase = PipelinePhase::UserGeneration,
+           .phase = PipelinePhase::Enrichment,
            .message =
                std::format("WikipediaService: Unexpected page format for '{}'",
                std::string(query))});
@@ -122,7 +122,7 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
   if (page.contains("missing")) {
     if (logger_) {
       logger_->Log({.level = LogLevel::Warn,
-                    .phase = PipelinePhase::UserGeneration,
+                    .phase = PipelinePhase::Enrichment,
                     .message = std::format("WikipediaService: Page '{}' does not exist",
                                std::string(query))});
     }
@@ -136,7 +136,7 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
     if (logger_) {
       logger_->Log(
           {.level = LogLevel::Warn,
-           .phase = PipelinePhase::UserGeneration,
+           .phase = PipelinePhase::Enrichment,
            .message =
                std::format("WikipediaService: No extract string found for '{}'",
                std::string(query))});
@@ -149,7 +149,7 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
   std::string extract(extract_ptr->as_string());
   if (logger_) {
     logger_->Log({.level = LogLevel::Info,
-                  .phase = PipelinePhase::UserGeneration,
+                  .phase = PipelinePhase::Enrichment,
                   .message = std::format("WikipediaService: Fetched {} chars for '{}'",
                              extract.size(), std::string(query))});
   }

tooling/pipeline/src/services/enrichment/wikipedia/get_summary.cc

@@ -16,7 +16,7 @@ std::string WikipediaEnrichmentService::GetLocationContext(
   if (!this->client_) {
     if (logger_) {
       logger_->Log({.level = LogLevel::Warn,
-                    .phase = PipelinePhase::UserGeneration,
+                    .phase = PipelinePhase::Enrichment,
                     .message = "Wikipedia client is nullptr."});
     }
     return {};
@@ -24,13 +24,6 @@ std::string WikipediaEnrichmentService::GetLocationContext(
 
   std::string result;
 
-  // std::string region_query(loc.city);
-  // if (!loc.country.empty()) {
-  //   region_query += loc.state_province,
-  //   region_query += ", ";
-  //   region_query += loc.country;
-  // }
-
   constexpr std::string_view brewing_query = "brewing";
   const std::string location_query =
       std::format("{}, {}", loc.city, loc.iso3166_2);
@@ -51,7 +44,7 @@ std::string WikipediaEnrichmentService::GetLocationContext(
     append_extract(FetchExtract(beer_query));
     if (logger_) {
       logger_->Log({.level = LogLevel::Info,
-                    .phase = PipelinePhase::UserGeneration,
+                    .phase = PipelinePhase::Enrichment,
                     .message = std::format("Done fetching for {}. Sleeping for 10 seconds.",
                                location_query)});
     }
@@ -61,7 +54,7 @@ std::string WikipediaEnrichmentService::GetLocationContext(
     if (logger_) {
       logger_->Log(
           {.level = LogLevel::Debug,
-           .phase = PipelinePhase::UserGeneration,
+           .phase = PipelinePhase::Enrichment,
            .message = std::format("WikipediaService lookup failed for '{}': {}",
                       location_query, e.what())});
     }

tooling/pipeline/src/services/logging/log_dispatcher.cc

@@ -19,6 +19,8 @@ namespace {
   switch (phase) {
     case PipelinePhase::Startup:
       return "Startup";
+    case PipelinePhase::Enrichment:
+      return "Enrichment";
     case PipelinePhase::UserGeneration:
       return "User Generation";
     case PipelinePhase::BreweryAndBeerGeneration:

tooling/pipeline/src/services/sqlite/finalize.cc

@@ -14,6 +14,7 @@ void SqliteExportService::Finalize() {
   }
 
   try {
+    insert_user_stmt_.reset();
     insert_brewery_stmt_.reset();
     insert_location_stmt_.reset();
     if (transaction_open_) {

tooling/pipeline/src/services/sqlite/initialize.cc

@@ -33,6 +33,9 @@ void SqliteExportService::InitializeSchema() const {
   sqlite_export_service_internal::ExecSql(
       db_handle_, sqlite_export_service_internal::kCreateBreweriesTableSql,
       "Failed to create SQLite breweries table");
+  sqlite_export_service_internal::ExecSql(
+      db_handle_, sqlite_export_service_internal::kCreateUsersTableSql,
+      "Failed to create SQLite users table");
 }
 
 void SqliteExportService::PrepareStatements() {
@@ -42,6 +45,9 @@ void SqliteExportService::PrepareStatements() {
   insert_brewery_stmt_ = sqlite_export_service_internal::PrepareStatement(
       db_handle_, sqlite_export_service_internal::kInsertBrewerySql,
       "Failed to prepare SQLite brewery insert statement");
+  insert_user_stmt_ = sqlite_export_service_internal::PrepareStatement(
+      db_handle_, sqlite_export_service_internal::kInsertUserSql,
+      "Failed to prepare SQLite user insert statement");
 }
 
 void SqliteExportService::RollbackAndCloseNoThrow() noexcept {
@@ -54,6 +60,7 @@ void SqliteExportService::RollbackAndCloseNoThrow() noexcept {
     transaction_open_ = false;
   }
 
+  insert_user_stmt_.reset();
   insert_brewery_stmt_.reset();
   insert_location_stmt_.reset();
   db_handle_.reset();

tooling/pipeline/src/services/sqlite/process_record.cc

@@ -1,6 +1,7 @@
 /**
  * @file services/sqlite/process_record.cc
- * @brief SqliteExportService::ProcessRecord() implementation.
+ * @brief SqliteExportService::ProcessRecord(GeneratedBrewery) implementation
+ * and the shared location-resolution helper.
  */
 
 #include <iomanip>
@@ -29,83 +30,85 @@ std::string SqliteExportService::BuildLocationKey(const Location& location) {
   return key_stream.str();
 }
 
-uint64_t SqliteExportService::ProcessRecord(const GeneratedBrewery& brewery) {
+sqlite3_int64 SqliteExportService::ResolveLocationId(const Location& location) {
-  if (db_handle_ == nullptr || !transaction_open_) {
+  const std::string location_key = BuildLocationKey(location);
-    throw std::runtime_error("SQLite export service is not initialized");
+  const auto cached_location = location_cache_.find(location_key);
+  if (cached_location != location_cache_.end()) {
+    return cached_location->second;
   }
 
-  const std::string location_key = BuildLocationKey(brewery.location);
-  const auto cached_location = location_cache_.find(location_key);
-  sqlite3_int64 location_id = 0;
-
-  if (cached_location != location_cache_.end()) {
-    location_id = cached_location->second;
-  } else {
   const std::string local_languages_json =
       sqlite_export_service_internal::SerializeVector(
-            brewery.location.local_languages);
+          location.local_languages);
 
   sqlite_export_service_internal::Bind(
       insert_location_stmt_,
       sqlite_export_service_internal::BindParam<std::string_view>{
           .index = sqlite_export_service_internal::kLocationCityBindIndex,
-            .value = brewery.location.city,
+          .value = location.city,
           .action = "Failed to bind SQLite location city"});
   sqlite_export_service_internal::Bind(
       insert_location_stmt_,
       sqlite_export_service_internal::BindParam<std::string_view>{
           .index =
               sqlite_export_service_internal::kLocationStateProvinceBindIndex,
-            .value = brewery.location.state_province,
+          .value = location.state_province,
           .action = "Failed to bind SQLite location state/province"});
   sqlite_export_service_internal::Bind(
       insert_location_stmt_,
       sqlite_export_service_internal::BindParam<std::string_view>{
           .index = sqlite_export_service_internal::kLocationIso31662BindIndex,
-            .value = brewery.location.iso3166_2,
+          .value = location.iso3166_2,
           .action = "Failed to bind SQLite location ISO 3166-2 code"});
   sqlite_export_service_internal::Bind(
       insert_location_stmt_,
       sqlite_export_service_internal::BindParam<std::string_view>{
           .index = sqlite_export_service_internal::kLocationCountryBindIndex,
-            .value = brewery.location.country,
+          .value = location.country,
           .action = "Failed to bind SQLite location country"});
   sqlite_export_service_internal::Bind(
       insert_location_stmt_,
       sqlite_export_service_internal::BindParam<std::string_view>{
           .index = sqlite_export_service_internal::kLocationIso31661BindIndex,
-            .value = brewery.location.iso3166_1,
+          .value = location.iso3166_1,
           .action = "Failed to bind SQLite location ISO 3166-1 code"});
   sqlite_export_service_internal::Bind(
       insert_location_stmt_,
       sqlite_export_service_internal::BindParam<std::string_view>{
-            .index =
+          .index = sqlite_export_service_internal::kLocationLanguagesBindIndex,
-                sqlite_export_service_internal::kLocationLanguagesBindIndex,
           .value = local_languages_json,
           .action = "Failed to bind SQLite location languages"});
   sqlite_export_service_internal::Bind(
       insert_location_stmt_,
       sqlite_export_service_internal::BindParam{
           .index = sqlite_export_service_internal::kLocationLatitudeBindIndex,
-            .value = brewery.location.latitude,
+          .value = location.latitude,
           .action = "Failed to bind SQLite location latitude"});
   sqlite_export_service_internal::Bind(
       insert_location_stmt_,
       sqlite_export_service_internal::BindParam{
-            .index =
+          .index = sqlite_export_service_internal::kLocationLongitudeBindIndex,
-                sqlite_export_service_internal::kLocationLongitudeBindIndex,
+          .value = location.longitude,
-            .value = brewery.location.longitude,
           .action = "Failed to bind SQLite location longitude"});
 
   sqlite_export_service_internal::StepStatement(
-        db_handle_, insert_location_stmt_,
+      db_handle_, insert_location_stmt_, "Failed to insert SQLite location row");
-        "Failed to insert SQLite location row");
 
-    location_id = sqlite_export_service_internal::LastInsertRowId(db_handle_);
+  const sqlite3_int64 location_id =
+      sqlite_export_service_internal::LastInsertRowId(db_handle_);
   location_cache_.emplace(location_key, location_id);
   sqlite_export_service_internal::ResetStatement(insert_location_stmt_);
+
+  return location_id;
 }
 
+uint64_t SqliteExportService::ProcessRecord(const GeneratedBrewery& brewery) {
+  if (db_handle_ == nullptr || !transaction_open_) {
+    throw std::runtime_error("SQLite export service is not initialized");
+  }
+
+  const sqlite3_int64 location_id = ResolveLocationId(brewery.location);
+
   sqlite_export_service_internal::Bind(
       insert_brewery_stmt_,
       sqlite_export_service_internal::BindParam<sqlite3_int64>{

tooling/pipeline/src/services/sqlite/process_user_record.cc

@@ -0,0 +1,85 @@
+/**
+ * @file services/sqlite/process_user_record.cc
+ * @brief SqliteExportService::ProcessRecord(GeneratedUser) implementation.
+ */
+
+#include <stdexcept>
+
+#include "services/database/sqlite_export_service.h"
+#include "services/database/sqlite_export_service_helpers.h"
+
+uint64_t SqliteExportService::ProcessRecord(const GeneratedUser& user) {
+  if (db_handle_ == nullptr || !transaction_open_) {
+    throw std::runtime_error("SQLite export service is not initialized");
+  }
+
+  const sqlite3_int64 location_id = ResolveLocationId(user.location);
+
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<sqlite3_int64>{
+          .index = sqlite_export_service_internal::kUserLocationIdBindIndex,
+          .value = location_id,
+          .action = "Failed to bind SQLite user location id"});
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<std::string_view>{
+          .index = sqlite_export_service_internal::kUserFirstNameBindIndex,
+          .value = user.user.first_name,
+          .action = "Failed to bind SQLite user first name"});
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<std::string_view>{
+          .index = sqlite_export_service_internal::kUserLastNameBindIndex,
+          .value = user.user.last_name,
+          .action = "Failed to bind SQLite user last name"});
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<std::string_view>{
+          .index = sqlite_export_service_internal::kUserGenderBindIndex,
+          .value = user.user.gender,
+          .action = "Failed to bind SQLite user gender"});
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<std::string_view>{
+          .index = sqlite_export_service_internal::kUserUsernameBindIndex,
+          .value = user.user.username,
+          .action = "Failed to bind SQLite user username"});
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<std::string_view>{
+          .index = sqlite_export_service_internal::kUserBioBindIndex,
+          .value = user.user.bio,
+          .action = "Failed to bind SQLite user bio"});
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<double>{
+          .index = sqlite_export_service_internal::kUserActivityWeightBindIndex,
+          .value = static_cast<double>(user.user.activity_weight),
+          .action = "Failed to bind SQLite user activity weight"});
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<std::string_view>{
+          .index = sqlite_export_service_internal::kUserEmailBindIndex,
+          .value = user.email,
+          .action = "Failed to bind SQLite user email"});
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<std::string_view>{
+          .index = sqlite_export_service_internal::kUserDateOfBirthBindIndex,
+          .value = user.date_of_birth,
+          .action = "Failed to bind SQLite user date of birth"});
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<std::string_view>{
+          .index = sqlite_export_service_internal::kUserPasswordBindIndex,
+          .value = user.password,
+          .action = "Failed to bind SQLite user password"});
+
+  sqlite_export_service_internal::StepStatement(
+      db_handle_, insert_user_stmt_, "Failed to insert SQLite user row");
+
+  sqlite_export_service_internal::ResetStatement(insert_user_stmt_);
+
+  return sqlite_export_service_internal::LastInsertRowId(db_handle_);
+}

tooling/pipeline/src/web_client/http_web_client.cc

@@ -57,7 +57,7 @@ std::string HttpWebClient::Get(const std::string& url) {
     if (logger_) {
       logger_->Log(
           {.level = LogLevel::Error,
-           .phase = PipelinePhase::UserGeneration,
+           .phase = PipelinePhase::Enrichment,
          .message =
            std::format("[HttpWebClient] Request failed for URL: {}", url)});
     }