Pipeline: rename Location to City, wire postal code into breweries

docs/pipeline/diagrams/planned/activity.puml

@@ -39,7 +39,7 @@ fork
   :JsonLoader::LoadBeerStyles("beer-styles.json");
   :EnrichmentService::PreWarmBeerStyleCache(beer_styles);
 fork again
-  :JsonLoader::LoadLocations("locations.json");
+  :JsonLoader::LoadCities("cities.json");
   :EnrichmentService::PreWarmLocationCache(sampled_locations);
 end fork
 fork
@@ -75,7 +75,7 @@ fork
 fork again
   |LLM Worker|
   while (loc_ch has items?) is (yes)
-    :Receive Location;
+    :Receive City;
 
     :GetLocationContextFromCache(location);
     note right
@@ -146,13 +146,13 @@ end fork
 fork
   |Orchestrator|
   :Loop: Sample User from user_pool_
-  and pair with Location;
-  :Send BreweryTask(Location, User) -> loc_ch;
+  and pair with City;
+  :Send BreweryTask(City, User) -> loc_ch;
   :Close loc_ch;
 fork again
   |LLM Worker|
   while (loc_ch has items?) is (yes)
-    :Receive BreweryTask(Location, User);
+    :Receive BreweryTask(City, User);
 
     :GetLocationContextFromCache(task.location);
     note right

docs/pipeline/diagrams/planned/class.puml

@@ -12,17 +12,40 @@ title Biergarten Data Pipeline — Class Diagram
 
 package "Domain: Models" {
 
-  class Location {
+  class City {
     + city : std::string
     + state_province : std::string
     + iso3166_2 : std::string
     + country : std::string
     + iso3166_1 : std::string
+    + postal_regex : std::vector<std::string>
+    + postal_code_examples : std::vector<std::string>
     + local_languages : std::vector<std::string>
     + latitude : double
     + longitude : double
   }
 
+  note right of City
+    postal_regex / postal_code_examples are
+    sourced from each cities.json entry's
+    postal_code.city_regex / postal_code.examples
+    (implemented today, ahead of the rest of this
+    diagram -- see ROADMAP.md §1/§2). Renamed from
+    Location to City to match the web backend's
+    City/CityId vocabulary -- see ROADMAP.md §1.
+  end note
+
+  class Address {
+    + postal_code : std::string
+  }
+
+  note right of Address
+    Mirrors the web backend's BreweryPostLocation.
+    Only postal_code is populated today --
+    address_line1/address_line2 have no fixture
+    data or generator yet. See ROADMAP.md §9.
+  end note
+
   class LocationContext {
     + text : std::string
     + completeness : Completeness
@@ -36,7 +59,7 @@ package "Domain: Models" {
   }
 
   class EnrichedCity {
-    + location : Location
+    + location : City
     + context : LocationContext
   }
 
@@ -130,7 +153,8 @@ package "Domain: Models" {
 
   class GeneratedBrewery {
     + brewery_id : uint64_t
-    + location : Location
+    + location : City
+    + address : Address
     + brewery : BreweryResult
     + context_completeness : LocationContext::Completeness
     + metadata : GenerationMetadata
@@ -139,7 +163,7 @@ package "Domain: Models" {
   class GeneratedBeer {
     + beer_id : uint64_t
     + brewery_id : uint64_t
-    + location : Location
+    + location : City
     + style : BeerStyle
     + beer : BeerResult
     + metadata : GenerationMetadata
@@ -147,7 +171,7 @@ package "Domain: Models" {
 
   class GeneratedUser {
     + user_id : uint64_t
-    + location : Location
+    + location : City
     + user : UserResult
     + email : std::string
     + date_of_birth : std::string
@@ -227,27 +251,27 @@ package "Domain: Application Configuration" {
 package "Domain: Policy" {
 
   interface ContextStrategy <<interface>> {
-    + QueriesFor(loc : const Location&) : std::vector<std::string>
+    + QueriesFor(loc : const City&) : std::vector<std::string>
     + MaxContextChars() : size_t
   }
 
   class BreweryContextStrategy {
-    + QueriesFor(loc : const Location&) : std::vector<std::string>
+    + QueriesFor(loc : const City&) : std::vector<std::string>
     + MaxContextChars() : size_t
   }
 
   class BeerContextStrategy {
-    + QueriesFor(loc : const Location&) : std::vector<std::string>
+    + QueriesFor(loc : const City&) : std::vector<std::string>
     + MaxContextChars() : size_t
   }
 
   interface SamplingStrategy <<interface>> {
-    + Sample(locations : const std::vector<Location>&) : std::vector<Location>
+    + Sample(locations : const std::vector<City>&) : std::vector<City>
   }
 
   class UniformSamplingStrategy {
     - sample_size_ : size_t
-    + Sample(locations : const std::vector<Location>&) : std::vector<Location>
+    + Sample(locations : const std::vector<City>&) : std::vector<City>
   }
 
   interface BeerSelectionStrategy <<interface>> {
@@ -369,7 +393,7 @@ package "Infrastructure: Pipeline Channel" {
 package "Infrastructure: Data Preloading" {
 
   interface ICuratedDataService <<interface>> {
-    + LoadLocations(filepath : const std::filesystem::path&) : const std::vector<Location>&
+    + LoadCities(filepath : const std::filesystem::path&) : const std::vector<City>&
     + LoadBeerStyles(filepath : const std::filesystem::path&) : const std::vector<BeerStyle>&
     + LoadPersonas(filepath : const std::filesystem::path&) : const std::vector<UserPersona>&
     + LoadForenamesByCountry(forenames_filepath : const std::filesystem::path&) : const std::unordered_map<std::string, forename_list>&
@@ -377,7 +401,7 @@ package "Infrastructure: Data Preloading" {
   }
 
   class JsonLoader {
-    + LoadLocations(filepath : const std::filesystem::path&) : const std::vector<Location>&
+    + LoadCities(filepath : const std::filesystem::path&) : const std::vector<City>&
     + LoadBeerStyles(filepath : const std::filesystem::path&) : const std::vector<BeerStyle>&
     + LoadPersonas(filepath : const std::filesystem::path&) : const std::vector<UserPersona>&
     + LoadForenamesByCountry(forenames_filepath : const std::filesystem::path&) : const std::unordered_map<std::string, forename_list>&
@@ -391,7 +415,7 @@ package "Infrastructure: Data Preloading" {
   end note
 
   class MockCuratedDataService {
-    + LoadLocations(filepath : const std::filesystem::path&) : const std::vector<Location>&
+    + LoadCities(filepath : const std::filesystem::path&) : const std::vector<City>&
     + LoadBeerStyles(filepath : const std::filesystem::path&) : const std::vector<BeerStyle>&
     + LoadPersonas(filepath : const std::filesystem::path&) : const std::vector<UserPersona>&
     + LoadForenamesByCountry(forenames_filepath : const std::filesystem::path&) : const std::unordered_map<std::string, forename_list>&
@@ -410,13 +434,13 @@ package "Infrastructure: Data Preloading" {
 package "Infrastructure: Enrichment" {
 
   interface EnrichmentService <<interface>> {
-    + GetLocationContext(loc : const Location&,\n  strategy : const ContextStrategy&) : LocationContext
+    + GetLocationContext(loc : const City&,\n  strategy : const ContextStrategy&) : LocationContext
   }
 
   class WikipediaService {
     - client_ : std::unique_ptr<WebClient>
     - extract_cache_ : std::unordered_map<std::string, std::string>
-    + GetLocationContext(loc : const Location&,\n  strategy : const ContextStrategy&) : LocationContext
+    + GetLocationContext(loc : const City&,\n  strategy : const ContextStrategy&) : LocationContext
     - FetchExtract(query : std::string_view) : std::string
   }
 
@@ -432,6 +456,39 @@ package "Infrastructure: Enrichment" {
 
 }
 
+package "Infrastructure: Postal Code Generation" {
+
+  interface IPostalCodeService <<interface>> {
+    + GeneratePostalCode(location : const City&) : std::string
+  }
+
+  class MockPostalCodeService {
+    + GeneratePostalCode(location : const City&) : std::string
+  }
+
+  class XegerPostalCodeService {
+    + GeneratePostalCode(location : const City&) : std::string
+  }
+
+  note right of MockPostalCodeService
+    Implemented today: ignores postal_regex and
+    returns postal_code_examples.front(). Not yet
+    bound in main.cc's DI graph or used by
+    BiergartenPipelineOrchestrator.
+  end note
+
+  note right of XegerPostalCodeService
+    Not implemented yet. Picks one of
+    location.postal_regex and generates a random
+    string matching it (a "xeger" -- the inverse of
+    regex matching) instead of always replaying a
+    fixed example. See ROADMAP.md §9.
+  end note
+
+  IPostalCodeService <|.. MockPostalCodeService
+  IPostalCodeService <|.. XegerPostalCodeService
+}
+
 package "Infrastructure: Prompting" {
 
   interface IPromptDirectory <<interface>> {
@@ -451,8 +508,8 @@ package "Infrastructure: Prompting" {
 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
+    + GenerateBrewery(location : const City&,\n  context : const LocationContext&) : BreweryResult
+    + GenerateBeer(brewery_id : uint64_t,\n  location : const City&,\n  context : const LocationContext&,\n  style : const BeerStyle&) : BeerResult
     + 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
@@ -464,7 +521,7 @@ package "Infrastructure: Data Generation" {
     + GenerateUser(...) : UserResult
     + GenerateCheckin(...) : CheckinResult
     + GenerateRating(...) : RatingResult
-    - DeterministicHash(location : const Location&) : size_t
+    - DeterministicHash(location : const City&) : size_t
   }
 
   class LlamaGenerator {
@@ -566,8 +623,8 @@ class BiergartenPipelineOrchestrator {
   - follow_pool_ : std::vector<GeneratedFollow>
   --
   + Run() : bool
-  - RunUserPhase(locations : const std::vector<Location>&) : void
-  - RunBreweryAndBeerPhase(locations : const std::vector<Location>&) : void
+  - RunUserPhase(locations : const std::vector<City>&) : void
+  - RunBreweryAndBeerPhase(locations : const std::vector<City>&) : void
   - RunCheckinPhase() : void
   - RunRatingPhase() : void
   - RunFollowPhase() : void
@@ -625,16 +682,17 @@ PipelineLogger                 o--  BoundedChannel : logs to
 LogWorker                      o--  BoundedChannel : drains from
 
 ' --- Domain Containment ---
-EnrichedCity                   *--  Location
+EnrichedCity                   *--  City
 EnrichedCity                   *--  LocationContext
-GeneratedBrewery               *--  Location
+GeneratedBrewery               *--  City
+GeneratedBrewery               *--  Address
 GeneratedBrewery               *--  BreweryResult
 GeneratedBrewery               *--  GenerationMetadata
-GeneratedBeer                  *--  Location
+GeneratedBeer                  *--  City
 GeneratedBeer                  *--  BeerStyle
 GeneratedBeer                  *--  BeerResult
 GeneratedBeer                  *--  GenerationMetadata
-GeneratedUser                  *--  Location
+GeneratedUser                  *--  City
 GeneratedUser                  *--  UserResult
 GeneratedUser                  *--  GenerationMetadata
 GeneratedCheckin               *--  CheckinResult