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/format.sh

@@ -1,6 +1,5 @@
 #!/bin/bash
 
-# Check for -y flag
 SKIP_CONFIRM=false
 if [[ "$1" == "-y" ]]; then
     SKIP_CONFIRM=true

tooling/pipeline/includes/concurrency/bounded_channel.h

@@ -67,7 +67,6 @@ class BoundedChannel {
    void Close();
 };
 
-// Include the template implementation
 #include "bounded_channel.tcc"
 
 #endif  // BIERGARTEN_PIPELINE_INCLUDES_CONCURRENCY_BOUNDED_CHANNEL_H_

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

@@ -24,7 +24,6 @@ using SqliteDatabaseHandle = std::unique_ptr<sqlite3, SqliteDatabaseDeleter>;
 using SqliteStatementHandle =
     std::unique_ptr<sqlite3_stmt, SqliteStatementDeleter>;
 
-// Represents a parameter that is bound to a prepared SQLite statement.
 // N.B. indices are 1 based.
 template <typename T>
 struct BoundParam {

tooling/pipeline/includes/services/datetime/date_time_provider.h

@@ -15,9 +15,6 @@
 
 /**
  * @brief Interface for UTC timestamp providers.
- *
- * @todo Yagni, consider removing this and just use SystemDateTimeProvider
- * directly
  */
 class IDateTimeProvider {
   public:

tooling/pipeline/runpod/start.sh

@@ -9,12 +9,10 @@ PROMPT_DIR="/app/prompts"
 
 echo "--- Starting Biergarten Pipeline Environment Check ---"
 
-# Ensure directories exist
 mkdir -p "$OUTPUT_DIR"
 mkdir -p "$(dirname "$LOG_PATH")"
 mkdir -p "$(dirname "$MODEL_PATH")"
 
-# Download model if missing
 if [ ! -f "$MODEL_PATH" ]; then
     echo "Model not found. Downloading (this may take a while)..."
 
@@ -25,16 +23,13 @@ if [ ! -f "$MODEL_PATH" ]; then
     echo "Download complete."
 fi
 
-# Verify model exists
 if [ ! -f "$MODEL_PATH" ]; then
     echo "ERROR: Model still not found after download attempt."
     exit 1
 fi
 
-# Default GPU layers
 GL_LAYERS="${BIERGARTEN_GL_LAYERS:-40}"
 
-# Build args
 ARGS=(
     "--model"      "$MODEL_PATH"
     "--prompt-dir" "$PROMPT_DIR"
@@ -43,14 +38,12 @@ ARGS=(
     "--n-gpu-layers" "$GL_LAYERS"
 )
 
-# Optional params
 [[ -n "$BIERGARTEN_TEMPERATURE" ]] && ARGS+=("--temperature"  "$BIERGARTEN_TEMPERATURE")
 [[ -n "$BIERGARTEN_TOP_P" ]]       && ARGS+=("--top-p"        "$BIERGARTEN_TOP_P")
 [[ -n "$BIERGARTEN_TOP_K" ]]       && ARGS+=("--top-k"        "$BIERGARTEN_TOP_K")
 [[ -n "$BIERGARTEN_N_CTX" ]]       && ARGS+=("--n-ctx"        "$BIERGARTEN_N_CTX")
 [[ -n "$BIERGARTEN_SEED" ]]        && ARGS+=("--seed"         "$BIERGARTEN_SEED")
 
-# Extra args
 [[ -n "$BIERGARTEN_EXTRA_ARGS" ]] && ARGS+=($BIERGARTEN_EXTRA_ARGS)
 
 echo "--- Executing: $EXECUTABLE ${ARGS[*]} ---"

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");