Refactor comments and update documentation for backend and pipeline (#246)

* Remove restating comments in backend

* Remove restating comments in frontend stories

* Remove restating comments in pipeline

* Remove restating comments in pipeline scripts

* Restore location-clear comment in BreweryRepository

* Remove stale/restating comments found in second pass

* Restore mock curated-data branch comment in main.cc

* Remove more restating/filler comments in backend

* Document account-management endpoints, compose files, and env generator

* Squashed commit of the following:

commit a8a5b8abd9969859c695092fae6990d03b2135ed
Author: Aaron Po <aaron.po97@gmail.com>
Date:   Sun Aug 23 23:53:56 2026 -0400

    Add reverse geocoding for brewery street addresses (#245)

    * Add geocoding to seed application, remove postal codes from generator

    Update comments

* Update pipeline class diagram for OpenAI generator

* Update pipeline activity diagram for brewery coordinates and OpenAI backend

* Add mailpit, production, db-only, and minimal environments to deployment diagram

* Fix authentication flow diagram for Identity migration

* Add account-management flows to authentication diagram

* Fix database schema diagram note referencing removed AuthRepository

docs/pipeline/diagrams/current/activity.puml

@@ -66,7 +66,7 @@ note right
 end note
 
 |#EAF0E8|BiergartenPipelineOrchestrator|
-:QueryCitiesWithCountries();
+:QueryLocations();
 
 |#E2EBDC|JsonLoader|
 :JsonLoader::LoadLocations("locations.json");
@@ -118,7 +118,7 @@ while (For each EnrichedCity?) is (Remaining cities)
     |#E5EDE1|DataGenerator|
     if (Generator Mode) then (MockGenerator)
       :DeterministicHash & Format;
-    else (LlamaGenerator)
+    elseif (Generator Mode) then (LlamaGenerator)
       :prompt_directory_->Load("USER_GENERATION");
       note right
         Resolves to USER_GENERATION.md inside --prompt-dir.
@@ -133,15 +133,43 @@ while (For each EnrichedCity?) is (Remaining cities)
           :Append validation error to retry prompt;
         endif
       repeat while (Attempt < 3?) is (yes)
+    else (OpenAIGenerator)
+      :prompt_directory_->Load("USER_GENERATION");
+      note right
+        Same prompt file as LlamaGenerator - content
+        is backend-agnostic.
+      end note
+      repeat
+        :CallChatCompletionsApi(system_prompt, user_prompt,\nkUserJsonSchema, max_tokens);
+        :ValidateUserJson(raw, user);
+        if (Is JSON Valid?) then (yes)
+          break
+        else (no)
+          :Attempt++;
+          :Append validation error to retry prompt;
+        endif
+      repeat while (Attempt < 2?) is (yes)
+      note right
+        Structured Outputs (response_format:
+        json_schema, strict: true) already
+        guarantees schema shape, so only 2
+        attempts are needed - retries here cover
+        transient failures / placeholder text,
+        not malformed JSON.
+      end note
     endif
 
     |#EAF0E8|BiergartenPipelineOrchestrator|
     if (Generation successful?) then (yes)
+      :GetRandomCoordsWithinRange(city_centre, 5km, rng);
       :BuildEmail(name, used_email_local_parts);
       :GenerateDateOfBirth(rng);
       note right
         email and date_of_birth are generated
         programmatically, never LLM-authored.
+        Generation + coordinate jitter run inside
+        one try/catch per record. UserRecord.address
+        now carries {city, longitude, latitude}.
       end note
 
       |#E0EAE0|SqliteExportService|
@@ -171,7 +199,7 @@ endwhile (Done)
 while (For each EnrichedCity?) is (Remaining cities)
   if (Generator Mode) then (MockGenerator)
     :DeterministicHash & Format;
-  else (LlamaGenerator)
+  elseif (Generator Mode) then (LlamaGenerator)
     :PrepareRegionContext;
     :prompt_directory_->Load("BREWERY_GENERATION");
     note right
@@ -191,10 +219,40 @@ while (For each EnrichedCity?) is (Remaining cities)
       max_tokens is fixed across retries —
       it is not raised on truncation.
     end note
+  else (OpenAIGenerator)
+    :PrepareRegionContext;
+    :prompt_directory_->Load("BREWERY_GENERATION");
+    note right
+      Same prompt file as LlamaGenerator - content
+      is backend-agnostic.
+    end note
+    repeat
+      :CallChatCompletionsApi(system_prompt, user_prompt,\nkBreweryJsonSchema, max_tokens);
+      :ValidateBreweryJson(raw, brewery);
+      if (Is JSON Valid?) then (yes)
+        break
+      else (no)
+        :Attempt++;
+        :Append validation error to retry prompt;
+      endif
+    repeat while (Attempt < 2?) is (yes)
+    note right
+      Structured Outputs already guarantees schema
+      shape, so only 2 attempts are needed - retries
+      here cover transient failures / placeholder
+      text, not malformed JSON.
+    end note
   endif
 
   |#EAF0E8|BiergartenPipelineOrchestrator|
   if (Generation successful?) then (yes)
+    :GetRandomCoordsWithinRange(city_centre, 5km, rng);
+    note right
+      Generation + coordinate jitter run inside one
+      try/catch per record. BreweryRecord.address
+      now carries {city, longitude, latitude}.
+    end note
+
     |#E0EAE0|SqliteExportService|
     :ProcessRecord(GeneratedBrewery);
     if (Location in cache?) then (yes)

docs/pipeline/diagrams/current/class.puml

@@ -35,12 +35,20 @@ class BiergartenPipelineOrchestrator {
   - generated_breweries_ : std::vector<BreweryRecord>
   - generated_users_ : std::vector<UserRecord>
   + Run() : bool
-  - QueryCitiesWithCountries() : std::vector<Location>
+  - QueryLocations() : std::vector<City>
   - GenerateBreweries(cities : std::span<const EnrichedCity>) : void
   - GenerateUsers(cities : std::span<const EnrichedCity>) : void
-  - LogResults() : void
+  - LogResults() const : void
 }
 
+note right of BiergartenPipelineOrchestrator
+  GenerateBreweries and GenerateUsers both call the
+  free function GetRandomCoordsWithinRange()
+  (biergarten_pipeline_orchestrator/coords.h) to jitter
+  a coordinate pair uniformly within 5km of the city
+  centre for each generated record's address.
+end note
+
 class LogLevel <<enumeration>> {
   Debug
   Info
@@ -50,6 +58,7 @@ class LogLevel <<enumeration>> {
 
 class PipelinePhase <<enumeration>> {
   Startup
+  Enrichment
   UserGeneration
   BreweryAndBeerGeneration
   CheckinGeneration
@@ -115,12 +124,12 @@ class HttpWebClient {
 }
 
 interface DataGenerator <<interface>> {
-  + GenerateBrewery(location : const Location&, region_context : const std::string&) : BreweryResult
+  + GenerateBrewery(city : const EnrichedCity&) : BreweryResult
   + GenerateUser(city : const EnrichedCity&, persona : const UserPersona&, name : const Name&) : UserResult
 }
 
 class MockGenerator {
-  + GenerateBrewery(location : const Location&, region_context : const std::string&) : BreweryResult
+  + GenerateBrewery(city : const EnrichedCity&) : BreweryResult
   + GenerateUser(city : const EnrichedCity&, persona : const UserPersona&, name : const Name&) : UserResult
   - DeterministicHash(location : const Location&) : size_t
   - DeterministicHash(location : const Location&, persona : const UserPersona&, name : const Name&) : size_t
@@ -139,6 +148,25 @@ class LlamaGenerator {
   - InferFormatted(...) : std::string
 }
 
+class OpenAIGenerator {
+  - api_key_ : std::string
+  - model_ : std::string
+  - logger_ : std::shared_ptr<ILogger>
+  - prompt_directory_ : std::unique_ptr<IPromptDirectory>
+  - web_client_ : std::unique_ptr<WebClient>
+  + GenerateBrewery(city : const EnrichedCity&) : BreweryResult
+  + GenerateUser(city : const EnrichedCity&, persona : const UserPersona&, name : const Name&) : UserResult
+  - CallChatCompletionsApi(...) : std::string
+}
+
+note right of OpenAIGenerator
+  Chat Completions with Structured Outputs
+  (response_format: json_schema, strict: true)
+  guarantees schema-valid JSON, replacing
+  llama.cpp's GBNF grammar constraint -
+  no IPromptFormatter needed.
+end note
+
 interface IPromptFormatter <<interface>> {
   + Format(system_prompt : std::string_view, user_prompt : std::string_view) : std::string
 }
@@ -252,10 +280,14 @@ WebClient <|.. HttpWebClient : implements
 
 DataGenerator <|.. MockGenerator : implements
 DataGenerator <|.. LlamaGenerator : implements
+DataGenerator <|.. OpenAIGenerator : implements
 
 LlamaGenerator *-- IPromptFormatter : uses
 LlamaGenerator *-- IPromptDirectory : uses
 
+OpenAIGenerator *-- IPromptDirectory : uses
+OpenAIGenerator *-- WebClient : uses
+
 IPromptFormatter <|.. Gemma4JinjaPromptFormatter : implements
 IPromptDirectory <|.. PromptDirectory : implements