Feature/recommendation system improvements

.gitignore

@@ -69,4 +69,10 @@ CLAUDE.md
 /app/assets/builds/*
 !/app/assets/builds/.keep
 .cursorindexingignore
-.specstory
+.specstory
+# Local Claude Code workspace artifacts
+.claude/
+
+# AI / working docs — kept locally, not committed to the shared repo
+/docs/
+/style-guide/

CHANGELOG.md

@@ -1,3 +1,14 @@
+27.05.2026
+* Recommendation system v2: per-user auction sorting backed by
+  domain_classifications, time-decayed bid/wishlist/view affinity,
+  and nightly LLM enrichment as a k8s CronJob
+  (rake recommendation:classify_unclassified). No shared-infrastructure
+  changes — no RDS extensions, no Docker image bumps for the shared
+  dev Postgres. See docs/architecture/recommendation-system.md and
+  docs/architecture/adr-001-recommendation-v2.md.
+* Batch impressions on /auctions index via insert_all (one query
+  regardless of page size), debounced score recompute on user actions.
+
 30.12.2025
 * Allow comma in billing profile street field https://github.com/internetee/auction_center/issues/1502
 * Fixed false error message bug on billing profile update https://github.com/internetee/auction_center/issues/1503

README.md

@@ -59,6 +59,84 @@ To send out emails and perform other asynchronous tasks, we use a background pro
 
 Part of running the application according to EIS business rules includes creating new auctions at the beginning of the day. Jobs are scheduled outside of the application, as the exact times are no concern of the application.
 
+## Recommendation system
+
+The public auction list is personalised: each user sees auctions ranked by how
+well every domain matches their behaviour and stated interests. Ranking is
+built on a single embedding space ("magnets") — everything about a user (bids,
+wishlist, views, selected categories, free-text interests) becomes a vector,
+and domains are ranked by their pull towards those vectors.
+
+### Prerequisite: feature flag
+
+The whole system is gated by the OpenAI integration. In
+`config/customization.yml`:
+
+```yaml
+openai:
+  enabled: true
+  access_token: 'sk-...'
+```
+
+When disabled, no classification, embedding or scoring runs and the list falls
+back to the global `ai_score` / default order. A running job worker
+(`bundle exec rails jobs:work`) is required for every `*_later` job below.
+
+### What runs automatically (event-driven, no manual action)
+
+| Trigger | Job | Effect |
+|---|---|---|
+| A new auction is created | `ClassifyDomainJob` (`Auction after_create`) | Classifies + embeds that domain |
+| A user bids / wishlists / views a domain | `RefreshSingleUserAuctionScoresJob` (30 s debounce, via `EventTracker`) | Re-scores that one user |
+| A user saves their interest profile | `RefreshSingleUserAuctionScoresJob` (debounced) | Re-scores that user |
+| A user adds/edits free-text ("other") interests | `EmbedCustomInterestsJob` | Embeds the new interests, then re-scores |
+| An admin adds/renames an interest category | `EnrichInterestCategoriesJob` | Generates description + keywords + embedding for that category |
+
+In normal operation this is all that happens — the system keeps itself current
+as auctions, bids and profiles change.
+
+### What runs on a schedule (cron)
+
+Only two scheduled commands (outside the app, like the other cron jobs):
+
+```bash
+bundle exec rake recommendation:init          # the whole pipeline, incremental
+bundle exec rake recommendation:prune_events  # retention: events >6mo (impressions >1mo)
+```
+
+`init` is the single pipeline entry point. It is incremental (`force: false`):
+it enriches interest categories, backfills embeddings for existing users' custom
+interests, then **drains the batched classify + embed passes itself** — picking
+up any domain that is unclassified, stale (>6mo), or whose vector was built under
+an older embedding-input format (`DomainEmbedder::INPUT_VERSION`, so a format
+bump rolls out on the next run with no extra command) — refreshes the global
+`ai_score`, and recomputes every participant's personal scores. Already-done work
+is **not** redone. Run it on every deploy; the same run also serves as the cron
+catch-up, so there is no separate classify/embed cron task.
+
+### What you run manually (rarely)
+
+| Command / action | When to use |
+|---|---|
+| `rake recommendation:backfill` | **Once**, when first enabling the feature — classifies the full historical domain set (ended auctions, wishlist, offer histories, results), a wider universe than `init` (active only), so past-bid domains get embeddings and can form magnets |
+| `rake recommendation:init_demo` | Staging/test only — seeds mock active auctions + signals, then runs the pipeline |
+| `Recommendation::RebuildRecommendationsJob` on **/admin/jobs** | Full re-tag of **every** domain (`force: true`): re-classifies via the LLM (fills the `description` field) and re-embeds. Run after the interest-category catalog changes, or once to backfill descriptions after the embedding-enrichment change |
+
+### Where to see the results (admin)
+
+- **/admin/interest_categories** — each category shows its AI status
+  (enriched / pending); the edit page shows the generated description,
+  keywords and embedding details.
+- **/admin/auctions/:id** — the auction detail page shows the domain's full LLM
+  classification (category, tags, keywords, audience, languages, brandability,
+  confidence, embedding status).
+
+### Experimental: tags on the public list
+
+`auction_tags_display_enabled` in `config/customization.yml` (default `false`)
+swaps the "auction type" column on the public auction list for the domain's
+LLM-derived tags. A missing key is treated as `false`.
+
 ## Audits
 
 Due to various regulatory requirements, all database tables are audited according to the following procedure:

app/assets/stylesheets/components/_account.scss

@@ -157,6 +157,8 @@
 
 .c-acount__buttons {
     gap: 5px;
+    // Separate the Billing / Delete row from the "Edit interests" button above it.
+    margin-top: 24px;
 
     @include mq(mobile) {
         gap: 10px;

app/assets/stylesheets/components/_badge.scss

@@ -60,6 +60,21 @@
 }
 
 
+// Removable interest tag: spacing + a bare "x" button. Shared by the
+// server-rendered tags (recommendation_profiles/_fields) and the ones the
+// custom-interest-tags Stimulus controller injects, so the two can't drift.
+.c-badge--interest {
+  margin: rem(4px) rem(8px) rem(4px) 0;
+}
+
+.c-badge__remove {
+  border: none;
+  background: transparent;
+  cursor: pointer;
+  padding: 0;
+  line-height: 1;
+}
+
 .c-badge--gray {
   background-color: $grey-100-color;
   color: $grey-400-color;

app/components/common/header/component.rb

@@ -57,6 +57,7 @@ def admin_menu_list_items
          { name: t(:invoices_name), path: admin_invoices_path },
          { name: t(:jobs_name), path: admin_jobs_path },
          { name: t(:settings_name), path: admin_settings_path },
+         { name: t(:interest_categories_name), path: admin_interest_categories_path },
          { name: t(:paid_deposits_name), path: admin_paid_deposits_path },
          { name: t(:statistics_name), path: admin_statistics_path }]
       end

app/components/pages/auction/auction_action_button/component.html.erb

@@ -6,7 +6,17 @@
   <% else %>
     <%# if need to create new offer for english auction %>
     <%= component 'common/links/link_button', link_title: deposit_value[:link_title], href: new_auction_english_offer_path(auction_uuid: auction.uuid),
-                  color: deposit_value[:color], options: { data: { turbo_frame: 'modal' } } %>
+                  color: deposit_value[:color],
+                  options: {
+                    data: {
+                      turbo_frame: 'modal',
+                      controller: 'recommendation-tracker',
+                      action: 'click->recommendation-tracker#track',
+                      recommendation_tracker_auction_uuid_value: auction.uuid,
+                      recommendation_tracker_source_value: 'auction_action_new_english_offer',
+                      recommendation_tracker_event_type_value: 'auction_click'
+                    }
+                  } %>
   <% end %>
 
 <% else %>
@@ -17,7 +27,17 @@
   <% else %>
     <%# if need to create new offer for blind auction %>
     <%= component 'common/links/link_button', link_title: t('auctions.bid'), href: new_auction_offer_path(auction_uuid: auction.uuid),
-                  color: 'green', options: { data: { turbo_frame: 'modal' } } %>
+                  color: 'green',
+                  options: {
+                    data: {
+                      turbo_frame: 'modal',
+                      controller: 'recommendation-tracker',
+                      action: 'click->recommendation-tracker#track',
+                      recommendation_tracker_auction_uuid_value: auction.uuid,
+                      recommendation_tracker_source_value: 'auction_action_new_blind_offer',
+                      recommendation_tracker_event_type_value: 'auction_click'
+                    }
+                  } %>
   <% end %>
 
 <% end %>

app/components/pages/auction/auction_action_button/edit_and_remove_blind_offer/component.html.erb

@@ -1,6 +1,16 @@
 <div class="c-btn-group c-btn-group--ghost">
   <%= component 'common/links/link_button', link_title: nil, href: edit_offer_path(@auction.users_offer_uuid),
-                color: 'ghost', options: { data: { turbo_frame: 'modal' } } do %>
+                color: 'ghost',
+                options: {
+                  data: {
+                    turbo_frame: 'modal',
+                    controller: 'recommendation-tracker',
+                    action: 'click->recommendation-tracker#track',
+                    recommendation_tracker_auction_uuid_value: @auction.uuid,
+                    recommendation_tracker_source_value: 'auction_action_edit_blind_offer',
+                    recommendation_tracker_event_type_value: 'auction_click'
+                  }
+                } do %>
     <span class="o-edit-icon"></span>
   <% end %>
   <%= component 'common/buttons/button_to', title_caption: nil, href: offer_path(@auction.offer_from_user(@user).uuid), color: 'ghost',

app/components/pages/auction/auction_action_button/edit_english_offer/component.html.erb

@@ -1,6 +1,16 @@
 <div class="c-btn-group c-btn-group--ghost">
   <%= component 'common/links/link_button', link_title: nil, href: edit_english_offer_path(@auction.users_offer_uuid),
-                color: 'ghost', options: { data: { turbo_frame: 'modal' } } do %>
+                color: 'ghost',
+                options: {
+                  data: {
+                    turbo_frame: 'modal',
+                    controller: 'recommendation-tracker',
+                    action: 'click->recommendation-tracker#track',
+                    recommendation_tracker_auction_uuid_value: @auction.uuid,
+                    recommendation_tracker_source_value: 'auction_action_edit_english_offer',
+                    recommendation_tracker_event_type_value: 'auction_click'
+                  }
+                } do %>
     <span class="o-edit-icon"></span>
   <% end %>
 </div>

app/controllers/admin/auctions_controller.rb

@@ -37,6 +37,7 @@ def index
 
     # GET /admin/auctions/1
     def show
+      @classification = DomainClassification.find_by(domain_name: @auction.domain_name.to_s.downcase)
       @offers = @auction.offers.order(cents: :desc)
       users = User.search_deposit_participants(params)
       @pagy, @users = pagy(users, items: params[:per_page] ||= 20, link_extra: 'data-turbo-action="advance"')

app/controllers/admin/interest_categories_controller.rb

@@ -0,0 +1,64 @@
+module Admin
+  class InterestCategoriesController < BaseController
+    before_action :authorize_user
+    before_action :set_interest_category, only: %i[edit update destroy]
+
+    # GET /admin/interest_categories
+    def index
+      @interest_categories = InterestCategory.ordered
+    end
+
+    # GET /admin/interest_categories/new
+    def new
+      @interest_category = InterestCategory.new(active: true, position: next_position)
+    end
+
+    # POST /admin/interest_categories
+    def create
+      @interest_category = InterestCategory.new(interest_category_params)
+
+      if @interest_category.save
+        redirect_to admin_interest_categories_path, notice: t(:created)
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    # GET /admin/interest_categories/1/edit
+    def edit; end
+
+    # PUT /admin/interest_categories/1
+    def update
+      if @interest_category.update(interest_category_params)
+        redirect_to admin_interest_categories_path, notice: t(:updated)
+      else
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    # DELETE /admin/interest_categories/1
+    def destroy
+      @interest_category.destroy
+      redirect_to admin_interest_categories_path, notice: t(:deleted)
+    end
+
+    private
+
+    def set_interest_category
+      @interest_category = InterestCategory.find(params[:id])
+    end
+
+    def interest_category_params
+      params.require(:interest_category)
+            .permit(:code, :name_en, :name_et, :position, :active)
+    end
+
+    def next_position
+      (InterestCategory.maximum(:position) || 0) + 1
+    end
+
+    def authorize_user
+      authorize! :manage, InterestCategory
+    end
+  end
+end

app/controllers/auctions_controller.rb

@@ -14,6 +14,10 @@ def index
       limit: per_page_count,
       link_extra: 'data-turbo-action="advance"'
     )
+    @show_recommendation_prompt = current_user&.recommendation_profile_promptable?
+    @auction_classifications = preloaded_classifications(@auctions)
+
+    track_recommendation_impressions
 
     respond_to do |format|
       format.html
@@ -36,6 +40,17 @@ def cors_preflight_check
 
   def fetch_auctions_list = Auction.active.search(params, current_user)
 
+  # Preload LLM tags for the list only when the experimental tags column is on,
+  # keyed by downcased domain name so the partial avoids an N+1.
+  def preloaded_classifications(auctions)
+    return nil unless AuctionCenter::Application.config.customization[:auction_tags_display_enabled]
+
+    domain_names = auctions.map { |auction| auction.domain_name.to_s.downcase }.uniq
+    DomainClassification
+      .where(domain_name: domain_names)
+      .index_by { |classification| classification.domain_name.to_s.downcase }
+  end
+
   def per_page_count
     count = params[:show_all] == 'true' ? @auctions_list.count : per_page
     count = nil if count.zero?
@@ -60,4 +75,17 @@ def set_access_control_headers
   def authorize_user
     authorize! :read, Auction
   end
+
+  def track_recommendation_impressions
+    return unless current_user
+    return unless request.format.html?
+
+    Recommendation::EventTracker.track_impressions(
+      user: current_user,
+      auctions: @auctions,
+      source: 'auctions#index',
+      request:
+    )
+  end
+
 end