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

tooling/pipeline/src/data_generation/generation_json_validation.cc

@@ -17,9 +17,6 @@
 #include <boost/json.hpp>
 
 namespace {
-/**
- * String trimming: removes leading and trailing whitespace
- */
 std::string Trim(std::string_view value) {
    constexpr std::string_view whitespace = " \t\n\r\f\v";
    const size_t first_index = value.find_first_not_of(whitespace);

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

@@ -17,7 +17,6 @@ using namespace boost;
 std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
    const std::string cache_key(query);
 
-   // 1. Cache Lookup
    if (const auto cache_it = this->extract_cache_.find(cache_key);
        cache_it != this->extract_cache_.end()) {
       if (logger_) {
@@ -42,7 +41,6 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
       std::this_thread::sleep_for(1s);
    }
 
-   // 2. Parse JSON
    system::error_code ec;
    json::value doc = json::parse(body, ec);
 
@@ -57,7 +55,6 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
       return {};
    }
 
-   // 3. Safe Extraction
    const json::object* obj = doc.if_object();
    if (obj == nullptr) {
       if (logger_) {
@@ -118,7 +115,6 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
 
    const json::object& page = page_val.get_object();
 
-   // Handle 404/Missing status
    if (page.contains("missing")) {
       if (logger_) {
          logger_->Log({.level = LogLevel::Warn,
@@ -145,7 +141,6 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
       return {};
    }
 
-   // 4. Success
    std::string extract(extract_ptr->as_string());
    if (logger_) {
       logger_->Log(

tooling/pipeline/src/services/prompt_directory.cc

@@ -15,8 +15,6 @@
 #include <string_view>
 #include <utility>
 
-// PromptDirectory
-
 PromptDirectory::PromptDirectory(const std::filesystem::path& prompt_dir)
     : PromptDirectory(prompt_dir, nullptr) {}
 
@@ -25,14 +23,12 @@ PromptDirectory::PromptDirectory(const std::filesystem::path& prompt_dir,
     : prompt_dir_(prompt_dir), logger_(std::move(logger)) {
    std::error_code ec;
 
-   // Directory must exist.
    if (!std::filesystem::exists(prompt_dir_, ec) || ec) {
       throw std::runtime_error(
           "PromptDirectory: prompt directory does not exist: " +
           prompt_dir_.string());
    }
 
-   // Path must be a directory, not a file.
    if (!std::filesystem::is_directory(prompt_dir_, ec) || ec) {
       throw std::runtime_error(
           "PromptDirectory: prompt directory path is not a directory: " +
@@ -96,7 +92,6 @@ std::string PromptDirectory::Load(std::string_view key) {
                key_str, file_path.string(), content.size())});
    }
 
-   // Cache the loaded content for future calls.
    cache_.emplace(key_str, content);
    return content;
 }

tooling/pipeline/src/services/xeger/xeger_generator.cc

@@ -25,12 +25,11 @@ std::string XegerGenerator::Run(const Node& root) {
 void XegerGenerator::Visit(const Literal& node) { out_ += node.ch; }
 
 void XegerGenerator::Visit(const AnyChar&) {
-   static constexpr int kPrintableLow = ' ';   // empty space - character 32
-   static constexpr int kPrintableHigh = '~';  // tilde - character 126
+   static constexpr int kPrintableLow = ' ';
+   static constexpr int kPrintableHigh = '~';
 
    std::uniform_int_distribution<int> dist(kPrintableLow, kPrintableHigh);
 
-   // assert that the rand number is in the char range
    bool inCharRange = dist.min() >= std::numeric_limits<char>::min() &&
                       dist.max() <= std::numeric_limits<char>::max();
    assert(inCharRange && "Random number is out of char range");