Add light mode theme toggle

.gitignore

@@ -18,6 +18,7 @@ venv/
 
 # Data (never commit)
 data/
+!src/api/rcars/data/
 *.db
 *.sqlite
 
@@ -48,4 +49,4 @@ ansible/vars/dev.yml
 ansible/vars/prod.yml
 node_modules
 tsconfig.tsbuildinfo
-OPERATIONS.md
+/OPERATIONS.md

README.md

@@ -1,27 +1,43 @@
 # RCARS — RHDP Content Advisory & Recommendation System
 
-Recommendation engine that matches RHDP catalog items to events, booth opportunities,
-and field requests. Analyzes Showroom content and uses semantic search + LLM reasoning
-to recommend the best assets for any given use case.
+AI-powered content intelligence for the Red Hat Demo Platform. RCARS reads every lab and demo in the RHDP catalog, understands what each one teaches, and uses that understanding to help teams find the right content, detect duplicate material, and identify items that should be retired.
 
-## Quick Start
+## What It Does
 
-```bash
-# Install dependencies
-pip install -e ".[dev]"
+- **Recommendations** — Ask a question in plain English ("what should we show at a Kubernetes conference?") and get a ranked list of catalog items with rationales
+- **Content Overlap Detection** — Pairwise semantic comparison across the catalog to surface duplicate or near-duplicate labs
+- **Retirement Analysis** — Scores every catalog item based on provisions, sales impact, cost, and age to identify retirement candidates
+- **Infrastructure Metadata** — Extracts workload mappings, cloud providers, and platform details from AgnosticD v2 configurations
+- **Catalog Browse** — Filterable view of all catalog items with curator controls for content management
+
+## Architecture
+
+Four deployments on OpenShift: React frontend, FastAPI API, arq workers (scan + recommend), PostgreSQL with pgvector. LLM analysis via LiteMaaS (primary) with Vertex AI fallback. Nightly pipeline handles catalog refresh, stale detection, workload scanning, content similarity, and reporting sync.
 
-# Set up PostgreSQL (local dev)
-podman run -d --name rcars-db -p 5432:5432 \
-  -e POSTGRESQL_USER=rcars -e POSTGRESQL_PASSWORD=dev \
-  -e POSTGRESQL_DATABASE=rcars \
-  registry.redhat.io/rhel9/postgresql-16:latest
+## Documentation
 
-# Configure
-export RCARS_DATABASE_URL="postgresql://rcars:dev@localhost:5432/rcars"
+Full documentation is published at **[rhpds.github.io/rcars](https://rhpds.github.io/rcars/)**.
 
-# Refresh catalog from Babylon CRDs (requires oc login)
-rcars refresh
+- [Overview](https://rhpds.github.io/rcars/overview/) — What RCARS is and how it works
+- [Web Guide](https://rhpds.github.io/rcars/user/web-guide/) — Using the web interface
+- [CLI Guide](https://rhpds.github.io/rcars/admin/cli-guide/) — Command-line reference
+- [System Design](https://rhpds.github.io/rcars/architecture/system-design/) — Architecture and data model
+- [Operations](https://rhpds.github.io/rcars/admin/operations/) — Deployment, monitoring, and maintenance
+- [Development](https://rhpds.github.io/rcars/admin/development/) — Local setup and contributing
 
-# Check status
-rcars status
+## Deployment
+
+RCARS is deployed to OpenShift via Ansible. See `ansible/` for playbooks and `ansible/vars/common.yml` for shared configuration. Environment-specific vars (`dev.yml`, `prod.yml`) are gitignored.
+
+```bash
+ansible-playbook ansible/deploy.yml -e env=dev --tags deploy
 ```
+
+## Local Development
+
+```bash
+./dev-services.sh start    # PostgreSQL, Redis, API, workers, frontend
+./dev-services.sh stop
+```
+
+See the [Development guide](https://rhpds.github.io/rcars/admin/development/) for full setup instructions.

ansible/deploy.yml

@@ -17,6 +17,8 @@
 #   ansible-playbook ansible/deploy.yml -e env=dev --tags builds          # Build all
 #   ansible-playbook ansible/deploy.yml -e env=dev --tags apply           # App manifests only (no build)
 #   ansible-playbook ansible/deploy.yml -e env=dev --tags migrate         # Just run migrations
+#   ansible-playbook ansible/deploy.yml -e env=dev --tags update          # Build all + migrate (correct order)
+#   ansible-playbook ansible/deploy.yml -e env=dev --tags smoke-test      # Advisor end-to-end test only
 #
 # Prerequisites:
 #   - ansible-galaxy collection install -r ansible/requirements.yml
@@ -98,8 +100,8 @@
       ansible.builtin.include_tasks:
         file: tasks/apply-infra.yml
         apply:
-          tags: [deploy]
-      tags: [deploy]
+          tags: [deploy, apply]
+      tags: [deploy, apply]
 
     - name: Apply app manifests
       ansible.builtin.include_tasks:
@@ -119,54 +121,89 @@
       ansible.builtin.include_tasks:
         file: tasks/build-frontend.yml
         apply:
-          tags: [build-frontend]
-      tags: [build-frontend]
+          tags: [build-frontend, update]
+      tags: [build-frontend, update]
 
     - name: Build API + workers only
       ansible.builtin.include_tasks:
         file: tasks/build-api.yml
         apply:
-          tags: [build-api]
-      tags: [build-api]
+          tags: [build-api, update]
+      tags: [build-api, update]
 
     - name: Run database migrations
       block:
-        - name: Wait for ready app pod
-          kubernetes.core.k8s_info:
+        - name: Wait for API rollout to complete
+          ansible.builtin.command:
+            cmd: >-
+              oc rollout status deployment/{{ app_name }}-api
+              -n {{ target_namespace }}
+              --kubeconfig={{ kubeconfig | expanduser }}
+              --timeout=300s
+          changed_when: false
+
+        - name: Find running API pod
+          ansible.builtin.command:
+            cmd: >-
+              oc get pods -n {{ target_namespace }}
+              --kubeconfig={{ kubeconfig | expanduser }}
+              -l app={{ app_name }},component=api
+              --field-selector=status.phase=Running
+              --no-headers -o custom-columns=NAME:.metadata.name
+          register: app_pods
+          until: app_pods.stdout_lines | default([]) | length > 0
+          retries: 10
+          delay: 10
+
+        - name: Select migration target pod
+          ansible.builtin.set_fact:
+            migrate_pod: "{{ app_pods.stdout_lines[0] }}"
+
+        - name: Run database schema setup (create tables)
+          kubernetes.core.k8s_exec:
             kubeconfig: "{{ kubeconfig }}"
-            kind: Pod
             namespace: "{{ target_namespace }}"
-            label_selectors:
-              - "app={{ app_name }}"
-              - "component=api"
-          register: app_pods
-          until: >-
-            app_pods.resources | default([]) | length > 0 and
-            (app_pods.resources
-             | selectattr('status.phase', 'eq', 'Running')
-             | selectattr('status.containerStatuses', 'defined')
-             | list | length > 0) and
-            (app_pods.resources
-             | selectattr('status.phase', 'eq', 'Running')
-             | selectattr('status.containerStatuses', 'defined')
-             | first).status.containerStatuses[0].ready | bool
-          retries: 30
-          delay: 15
-          failed_when: app_pods.resources | default([]) | length == 0
-
-        - name: Run database schema setup
+            pod: "{{ migrate_pod }}"
+            command: rcars init-db
+          register: schema_result
+          changed_when: false
+
+        - name: Run alembic migrations (alter existing tables)
           kubernetes.core.k8s_exec:
             kubeconfig: "{{ kubeconfig }}"
             namespace: "{{ target_namespace }}"
-            pod: >-
-              {{ (app_pods.resources
-                  | selectattr('status.phase', 'eq', 'Running')
-                  | selectattr('status.containerStatuses', 'defined')
-                  | first).metadata.name }}
-            command: rcars status
+            pod: "{{ migrate_pod }}"
+            command: alembic upgrade head
           register: migrate_result
-          changed_when: false
-      tags: [deploy, migrate]
+          changed_when: "'Running upgrade' in (migrate_result.stdout | default(''))"
+
+        - name: Get expected alembic head from code
+          kubernetes.core.k8s_exec:
+            kubeconfig: "{{ kubeconfig }}"
+            namespace: "{{ target_namespace }}"
+            pod: "{{ migrate_pod }}"
+            command: alembic heads --resolve-dependencies
+          register: expected_version
+
+        - name: Get current alembic version from database
+          kubernetes.core.k8s_exec:
+            kubeconfig: "{{ kubeconfig }}"
+            namespace: "{{ target_namespace }}"
+            pod: "{{ migrate_pod }}"
+            command: alembic current
+          register: actual_version
+          until: expected_version.stdout | default('') | trim in (actual_version.stdout | default(''))
+          retries: 6
+          delay: 30
+          failed_when: expected_version.stdout | default('') | trim not in (actual_version.stdout | default(''))
+      tags: [deploy, migrate, update]
+
+    - name: Advisor smoke test (end-to-end LLM verification)
+      ansible.builtin.include_tasks:
+        file: tasks/smoke-test.yml
+        apply:
+          tags: [deploy, apply, smoke-test]
+      tags: [deploy, apply, smoke-test]
 
   post_tasks:
     - name: Get pod status

ansible/tasks/apply-infra.yml

@@ -13,24 +13,6 @@
     state: present
     apply: true
 
-- name: Ensure RCARS API can validate SA tokens (TokenReview access)
-  kubernetes.core.k8s:
-    kubeconfig: "{{ kubeconfig }}"
-    state: present
-    definition:
-      apiVersion: rbac.authorization.k8s.io/v1
-      kind: ClusterRoleBinding
-      metadata:
-        name: "rcars-token-review-{{ env }}"
-      roleRef:
-        apiGroup: rbac.authorization.k8s.io
-        kind: ClusterRole
-        name: system:auth-delegator
-      subjects:
-        - kind: ServiceAccount
-          name: default
-          namespace: "{{ target_namespace }}"
-
 - name: Clean up rendered infra manifests
   ansible.builtin.file:
     path: "/tmp/rcars-{{ env }}-infra.yaml"

ansible/tasks/build-api.yml

@@ -30,18 +30,11 @@
      | last).status.phase in ['Failed', 'Error', 'Cancelled']
   changed_when: false
 
-- name: Wait for API rollout
-  kubernetes.core.k8s_info:
-    kubeconfig: "{{ kubeconfig }}"
-    api_version: apps/v1
-    kind: Deployment
-    namespace: "{{ target_namespace }}"
-    name: "{{ app_name }}-api"
-  register: api_rollout
-  until: >-
-    api_rollout.resources | default([]) | length > 0 and
-    (api_rollout.resources[0].status.readyReplicas | default(0) | int) ==
-    (api_rollout.resources[0].spec.replicas | default(1) | int)
-  retries: 20
-  delay: 10
+- name: Wait for new API rollout to complete
+  ansible.builtin.command:
+    cmd: >-
+      oc rollout status deployment/{{ app_name }}-api
+      -n {{ target_namespace }}
+      --kubeconfig={{ kubeconfig | expanduser }}
+      --timeout=300s
   changed_when: false

ansible/tasks/mgmt-rbac.yml

@@ -97,6 +97,24 @@
           name: "{{ mgmt_service_account.name }}"
           namespace: "{{ target_namespace }}"
 
+- name: Ensure RCARS API can validate SA tokens (TokenReview access)
+  kubernetes.core.k8s:
+    kubeconfig: "{{ kubeconfig }}"
+    state: present
+    definition:
+      apiVersion: rbac.authorization.k8s.io/v1
+      kind: ClusterRoleBinding
+      metadata:
+        name: "rcars-token-review-{{ env }}"
+      roleRef:
+        apiGroup: rbac.authorization.k8s.io
+        kind: ClusterRole
+        name: system:auth-delegator
+      subjects:
+        - kind: ServiceAccount
+          name: default
+          namespace: "{{ target_namespace }}"
+
 # ── Long-lived token + kubeconfig generation ──────────────────────────────────
 
 - name: Ensure long-lived token Secret exists

ansible/tasks/smoke-test.yml

@@ -0,0 +1,94 @@
+---
+# End-to-end advisor smoke test — verifies the full pipeline:
+# vector search → LLM triage → LLM rationale → recommendations
+#
+# Runs a simple query against the advisor API from inside the cluster
+# and checks that results come back without errors.
+
+- name: Wait for recommend-worker rollout
+  ansible.builtin.command:
+    cmd: >-
+      oc rollout status deployment/{{ app_name }}-recommend-worker
+      -n {{ target_namespace }}
+      --kubeconfig={{ kubeconfig | expanduser }}
+      --timeout=120s
+  changed_when: false
+
+- name: Wait for API rollout
+  ansible.builtin.command:
+    cmd: >-
+      oc rollout status deployment/{{ app_name }}-api
+      -n {{ target_namespace }}
+      --kubeconfig={{ kubeconfig | expanduser }}
+      --timeout=120s
+  changed_when: false
+
+- name: Find running API pod
+  ansible.builtin.command:
+    cmd: >-
+      oc get pods -n {{ target_namespace }}
+      --kubeconfig={{ kubeconfig | expanduser }}
+      -l app={{ app_name }},component=api
+      --field-selector=status.phase=Running
+      --no-headers -o custom-columns=NAME:.metadata.name
+  register: smoke_api_pods
+  until: smoke_api_pods.stdout_lines | default([]) | length > 0
+  retries: 10
+  delay: 5
+
+- name: Select API pod for smoke test
+  ansible.builtin.set_fact:
+    smoke_pod: "{{ smoke_api_pods.stdout_lines[0] }}"
+
+- name: Submit advisor query
+  kubernetes.core.k8s_exec:
+    kubeconfig: "{{ kubeconfig }}"
+    namespace: "{{ target_namespace }}"
+    pod: "{{ smoke_pod }}"
+    command: >-
+      curl -sf --max-time 30 -X POST http://localhost:{{ app_port }}/api/v1/advisor/query
+      -H 'Content-Type: application/json'
+      -H 'X-Forwarded-Email: smoke-test@redhat.com'
+      -d '{"query": "OpenShift getting started demo", "include_zt": false}'
+  register: smoke_query
+  failed_when: smoke_query.rc != 0
+
+- name: Parse query job ID
+  ansible.builtin.set_fact:
+    smoke_job_id: "{{ (smoke_query.stdout | from_json).job_id }}"
+
+- name: "Poll advisor result (job {{ smoke_job_id }})"
+  kubernetes.core.k8s_exec:
+    kubeconfig: "{{ kubeconfig }}"
+    namespace: "{{ target_namespace }}"
+    pod: "{{ smoke_pod }}"
+    command: >-
+      curl -sf --max-time 30 http://localhost:{{ app_port }}/api/v1/advisor/query/{{ smoke_job_id }}/result
+      -H 'X-Forwarded-Email: smoke-test@redhat.com'
+  register: smoke_result
+  until: >-
+    (smoke_result.stdout | from_json).status | default('') in ['complete', 'failed']
+  retries: 30
+  delay: 5
+  failed_when: smoke_result.rc != 0
+
+- name: Parse smoke test result
+  ansible.builtin.set_fact:
+    smoke_parsed: "{{ smoke_result.stdout | from_json }}"
+    smoke_candidates: "{{ (smoke_result.stdout | from_json).result.candidates | default([]) }}"
+
+- name: Verify advisor returned results
+  ansible.builtin.assert:
+    that:
+      - smoke_parsed.status == 'complete'
+      - smoke_candidates | length > 0
+    fail_msg: >-
+      Advisor smoke test FAILED.
+      Status: {{ smoke_parsed.status | default('unknown') }}.
+      Error: {{ smoke_parsed.error | default('none') }}.
+      Candidates: {{ smoke_candidates | length }}.
+      This usually means the LLM provider (LiteMaaS/Vertex) is unreachable or
+      returned an authentication error. Check recommend-worker logs:
+        oc logs deployment/{{ app_name }}-recommend-worker -n {{ target_namespace }} --tail=50
+    success_msg: >-
+      Advisor smoke test PASSED — {{ smoke_candidates | length }} candidates returned.