ThothII/docs/superpowers/plans/2026-08-22-datamart-builder-test-route.md

Datamart Builder Test Route Implementation Plan

Goal: Expose the new ThothII release at /datamart-builder-test/ through the existing portal domain while leaving /datamart-builder/ unchanged until manual acceptance.

Architecture: Django remains the page and capability gate. The portal Nginx receives the test path and proxies its page/assets/API/SSE to an isolated ThothII test frontend/core pair on the existing Docker network. The test instance trusts the portal's normalized Authentik identity; no local ThothII login is introduced for this server.

Tech Stack: Django, Nginx, Docker Compose, React/Vite, Fastify/TypeScript, existing omics_portal_omics_network.

Global Constraints

• Do not change DNS or the external load balancer.
• Preserve /datamart-builder/ until the user explicitly accepts the test route.
• Do not stop or replace the current ThothII instance during the test phase.
• Do not expose the canonical authentication root or bypass the Django capability gate.
• Use the existing portal Authentik session and normalized principal headers.
• Keep secrets and generated runtime state outside Git.

Task 1: Isolated test service and prefix contract

Files:

• Modify: compose.yaml / an approved deployment override used on the server

• Modify: frontend/vite.config.ts and frontend runtime routing only if required by tests

• Test: frontend/backend route and same-origin API tests

• Build an isolated test frontend/core service pair with unique service/container names and no host port collision.

• Configure the test frontend public base as /datamart-builder-test/ and its API contract as /datamart-builder-test/api/, or implement an equivalent internal rewrite that preserves the browser same-origin contract.

• Configure the core for trusted upstream identity headers and the public URL https://aritmolab.policlinicosandonato.it/datamart-builder-test/.

• Attach only the existing portal Docker network needed for Nginx-to-test-service traffic.

• Run focused frontend/backend tests and render the test Compose configuration without starting the stack.

Task 2: Django test page and menu entry

Files:

• Modify: /home/chirone/omics_portal/omics_portal/urls.py

• Modify: /home/chirone/omics_portal/kokoro/datamart_catalog_views.py or a focused test view module

• Modify: /home/chirone/omics_portal/templates/partials/left-sidebar.html

• Modify: /home/chirone/omics_portal/templates/kokoro/datamart_builder.html or add a test-specific template

• Test: Django URL, capability, menu, and template tests

• Add /datamart-builder-test/ using the same capability check as the existing Datamart Builder page.

• Add a visible Datamart Builder Test menu item without changing the existing item.

• Ensure the test template emits asset URLs with the test prefix and does not expose credentials.

• Run the focused Django tests and collect static/template validation output.

Task 3: Portal Nginx test routing

Files:

• Modify: /home/chirone/omics_portal/nginx/nginx.conf

• Test: nginx -t in the portal container and deterministic config/route checks

• Add test-path locations for page, assets, API, and SSE.

• Reuse the internal Django auth subrequest and normalized principal headers; clear client-controlled identity, cookie, and authorization headers before the core hop.

• Proxy only to the isolated test frontend/core upstreams.

• Verify /datamart-builder/ remains byte-for-byte on its existing upstream rules.

• Reload only the portal Nginx after config validation; do not reload the external balancer.

Task 4: Manual test checkpoint

• Report the exact URL https://aritmolab.policlinicosandonato.it/datamart-builder-test/ and test procedure.
• Stop implementation and wait for the user's manual acceptance or failure report.

Task 5: Cutover after explicit PASS

• Repoint the existing Datamart Builder Django menu/page and Nginx locations to the accepted new service.
• Preserve the same Authentik capability gate and normalized identity contract.
• Run automated checks and wait for the user's second manual acceptance.

Task 6: Remove test-only surface after explicit PASS

• Remove the Datamart Builder Test menu entry and Django route.
• Remove test-only Nginx locations/upstreams and test service definitions.
• Leave only the accepted new implementation behind /datamart-builder/.
• Validate Nginx, Django, Compose, and browser-facing health checks; report the final diff.