Feature/clickhouse explorer

Dockerfile

@@ -4,6 +4,17 @@
 FROM node:22-slim AS builder
 WORKDIR /gen3
 
+ARG NEXT_PUBLIC_GEN3_API
+ARG NEXT_PUBLIC_GEN3_DOMAIN
+ARG NEXT_PUBLIC_GEN3_LOOM_API
+ARG NEXT_PUBLIC_GEN3_REDIRECT_URL
+ARG NEXT_PUBLIC_GEN3_COMMONS_NAME=cbds
+ENV NEXT_PUBLIC_GEN3_API=$NEXT_PUBLIC_GEN3_API
+ENV NEXT_PUBLIC_GEN3_DOMAIN=$NEXT_PUBLIC_GEN3_DOMAIN
+ENV NEXT_PUBLIC_GEN3_LOOM_API=$NEXT_PUBLIC_GEN3_LOOM_API
+ENV NEXT_PUBLIC_GEN3_REDIRECT_URL=$NEXT_PUBLIC_GEN3_REDIRECT_URL
+ENV NEXT_PUBLIC_GEN3_COMMONS_NAME=$NEXT_PUBLIC_GEN3_COMMONS_NAME
+
 # Copy everything
 COPY . .
 
@@ -42,4 +53,4 @@ ENV NODE_ENV=production
 ENV PORT=3000
 
 EXPOSE 3000
-CMD ["/bin/bash", "./start.sh"]
+CMD ["/bin/bash", "./start.sh"]

docs/Configuration/Query.md

@@ -0,0 +1,64 @@
+# Query configuration
+
+Query configuration uses version 2 endpoint and mode records. The page loads
+the configured service, fetches its GraphQL schema, and uses the selected mode
+to provide its default query and variables.
+
+```json
+{
+  "version": 2,
+  "endpoints": {
+    "loomGraph": {
+      "url": "/loom/graphql/graph",
+      "service": "loom",
+      "surface": "graph"
+    },
+    "loomFlat": {
+      "url": "/loom/graphql/flat",
+      "service": "loom",
+      "surface": "flat"
+    }
+  },
+  "modes": [
+    {
+      "id": "loom-fhir-graph",
+      "label": "Loom Graph",
+      "endpoint": "loomGraph",
+      "preset": "loom-fhir-graph"
+    },
+    {
+      "id": "loom-fhir-dataframe",
+      "label": "Loom Dataframe",
+      "endpoint": "loomGraph",
+      "preset": "loom-fhir-dataframe"
+    },
+    {
+      "id": "loom-flat",
+      "label": "Loom Flat",
+      "endpoint": "loomFlat",
+      "preset": "loom-flat"
+    }
+  ],
+  "defaultMode": "loom-flat"
+}
+```
+
+Supported services and presets are:
+
+- `loom-fhir-graph`: binds the selected `PROGRAM-PROJECT` to `input.project`.
+- `loom-fhir-dataframe`: binds the selected `PROGRAM-PROJECT` to `input.project`.
+- `loom-flat`: adds a `project_id EQ PROGRAM-PROJECT` filter to the flat input.
+- `guppy-flat`: adds `auth_resource_path` using `/programs/PROGRAM/projects/PROJECT`.
+- `generic`: executes the configured query without automatic project binding.
+
+The Query page reads the canonical project selector from `project_id`. The
+legacy `project` query parameter is accepted once and rewritten to
+`project_id`. Accessible projects come from Gecko, and the Run button is
+disabled when a project-bound mode has no valid accessible project selected.
+
+Endpoint URLs may be absolute HTTP/HTTPS URLs or root-relative paths. URLs
+with credentials, fragments, protocol-relative syntax, or unsafe schemes are
+rejected. Loom graph and flat endpoints must use their matching GraphQL path.
+
+Older configurations containing only `graphQLEndpoint` are normalized locally
+for compatibility. New configuration should use version 2.

docs/loom-etl-work-packages/EXPLORER_LOOM_MAPPING_INVENTORY.md

@@ -0,0 +1,27 @@
+# Explorer read-path inventory
+
+The Explorer configuration still uses its established `guppyConfig.dataType`
+values. The adapter boundary is `packages/core/src/features/loom/mapping.ts`;
+all requests below use the canonical value returned by `toLoomDataType`.
+
+| Explorer surface | Previous request | Loom request | Existing consumer shape |
+| --- | --- | --- | --- |
+| `pages/Explorer/data.ts` shared-field discovery | Guppy `_mapping` | `dataframeDataset` column metadata | `SharedFieldMapping` |
+| `CohortPanel` facets | Guppy grouped aggregations | `dataframeAggregate` COUNT by field | `AggregationsData` |
+| `CohortPanel` total | Guppy count aggregation | `dataframeAggregate` COUNT | `number` |
+| `ExplorerTable` rows | Guppy offset rows/count | `dataframeRows` with opaque cursor | `JSONObject[]`, row count |
+| `QueryRowDetailsPanel` | Guppy single-row query | `dataframeRows` with an ID filter | one `JSONObject` |
+| download actions | Guppy download endpoint | Loom dataframe export | JSON/CSV/TSV blob or JSON rows |
+
+The canonical mapping is:
+
+- `file` and `document_reference` -> `DocumentReference`
+- `research_subject` -> `ResearchSubject`
+- `specimen` -> `Specimen`
+- `medication_administration` -> `MedicationAdministration`
+- `group_member` -> `GroupMember`
+
+Loom metadata is also the availability boundary. Explorer distinguishes an
+unsupported type, transport/authorization failure, missing dataset, a
+non-`READY` dataset, and a `READY` dataset with zero rows. There is no Guppy
+runtime fallback.