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)