First impressions of Loom

[bwalsh]

ADR: Evaluation of Loom as a FHIR-Native Cohort Discovery and DataFrame Platform

• Status: Proposed
• Date: 2026-06-23
• Authors: Architecture Review
• Decision Type: Technical Evaluation

---

Context

The Loom project aims to bridge the gap between FHIR interoperability data models and practical biomedical analytics.

FHIR resources are highly expressive and interoperable but are often difficult to use directly for cohort discovery, translational research, and analytical workflows. Researchers typically require flat, analysis-ready tables rather than deeply nested FHIR JSON documents.

Loom addresses this challenge by:

1. Ingesting FHIR NDJSON resources.
2. Building graph relationships between resources.
3. Discovering populated fields and references.
4. Generating dataframe-oriented outputs.
5. Exposing results through GraphQL and API services.

This review evaluates Loom from the perspectives of:

• Biomedical informatics
• Bioinformatics
• Data engineering
• GraphQL architecture
• Long-term platform strategy

---

Decision Drivers

The primary evaluation criteria are:

• Ability to support cohort discovery
• Ability to preserve FHIR fidelity
• Suitability for biomedical research workflows
• Extensibility across disease domains
• Ease of use for scientists and analysts
• Architectural sustainability
• Backend portability
• Production readiness

---

Summary Assessment

Dimension	Assessment
FHIR Fidelity	Strong
Cohort Discovery	Strong
Biomedical Metadata Analysis	Strong
Molecular Analysis	Limited
DataFrame Generation	Strong
GraphQL Architecture	Promising
End User Usability	Moderate
Portability	Moderate
Production Readiness	Moderate-Low
Strategic Potential	High

---

Findings

Finding 1: Strong FHIR-to-Analytics Architecture

The most compelling aspect of Loom is its architecture.

FHIR NDJSON
      ↓
 Graph Construction
      ↓
 Metadata Discovery
      ↓
 DataFrame Builder
      ↓
 GraphQL / Export

Rather than forcing users to query raw FHIR resources directly, Loom constructs graph-linked analytical views suitable for cohort discovery and metadata exploration.

This is a meaningful improvement over traditional FHIR repositories where users must manually navigate complex resource relationships.

Assessment

Positive.

---

Finding 2: Biomedical Semantics Are Preserved

The graph model reflects real-world translational research workflows.

Example relationships:

Patient
 ├── Condition
 ├── ResearchSubject
 ├── MedicationAdministration
 └── Specimen
         └── DocumentReference

This structure closely aligns with common biomedical reasoning patterns:

• Patient-centric cohorts
• Specimen tracking
• Study enrollment
• Treatment history
• Assay inventory

Assessment

Strong positive.

---

Finding 3: DataFrame Builder Is the Strategic Asset

The most valuable component appears to be:

internal/dataframe

The subsystem supports:

• Traversals
• Field selection
• Aggregations
• Pivots
• Representative slices

Conceptually, this functions as a semantic query planner rather than a collection of fixed reports.

The design enables future low-code cohort construction and analytical export workflows.

Assessment

Highest-value component of the platform.

---

Finding 4: Current Focus Is Metadata Rather Than Biology

Loom currently answers questions such as:

• Which assays exist?
• Which files are available?
• Which specimens are linked to a patient?
• Which studies contain a patient?

It does not yet answer:

• Which patients contain TP53 mutations?
• Which tumors overexpress EGFR?
• Which samples contain a specific pathway signature?

The platform is currently a metadata-discovery engine rather than a molecular-analysis engine.

Assessment

Expected limitation for current scope.

---

Finding 5: Current Implementation Is GDC-Oriented

Many assumptions appear tied to:

• GDC terminology
• Oncology workflows
• Specific identifier systems
• Specific coding conventions
• US Core extensions

This creates uncertainty regarding portability across:

• Rare disease repositories
• Pediatric research repositories
• Infectious disease repositories
• Longitudinal clinical datasets

Assessment

Moderate architectural risk.

---

Finding 6: GraphQL Architecture Is Promising

The GraphQL implementation demonstrates several strong characteristics:

Strengths

• Semantic query model
• Validation before execution
• Authorization-aware planning
• Separation of API from AQL execution

Concerns

• Contract duplication across layers
• Selector mini-language complexity
• Arango-oriented execution assumptions
• Incomplete separation between semantic and execution models

Assessment

Strong foundation requiring additional refinement.

---

Architectural Strengths

Cohort-Oriented Thinking

The system is designed around cohort construction rather than document retrieval.

Preservation of Raw FHIR

Original payloads remain available for traceability and validation.

Validation Against Actual Data

The platform validates requests against populated fields and references rather than relying solely on schema definitions.

Future Low-Code Potential

The dataframe abstraction creates a path toward scientist-facing cohort builders.

---

Architectural Risks

Risk: Hardcoded Biomedical Assumptions

Current implementations rely heavily on GDC-specific conventions.

Impact

Medium

Mitigation

Introduce configurable semantic mappings and terminology abstraction layers.

---

Risk: User Experience Gap

The dataframe model still exposes technical concepts such as:

• Traversal labels
• Selector syntax
• Resource paths

Impact

High

Mitigation

Develop:

• Templates
• Wizards
• Field catalogs
• Autocomplete-driven builders

---

Risk: Backend Coupling

The dataframe compiler remains closely aligned with ArangoDB execution semantics.

Impact

Medium

Mitigation

Introduce an explicit intermediate representation between semantic plans and backend execution plans.

---

Strategic Opportunities

Scientist-Facing Cohort Builder

The strongest opportunity is creation of a no-code cohort builder.

Desired workflow:

Show one row per patient with diagnosis, specimen type, RNA-seq availability, WGS availability, and study membership.

without requiring knowledge of:

• Graph traversal
• FHIRPath
• AQL
• GraphQL internals

---

Cross-Repository FHIR Analytics

Loom could become a generic analytics layer for:

• NCPI repositories
• Gen3 deployments
• Institutional FHIR repositories
• Research data commons

if semantic assumptions become configurable.

---

Recommendation

Continue Investment In

• Dataframe Builder
• GraphQL abstraction layer
• Metadata discovery services
• Template-driven cohort extraction
• Backend portability efforts

Deprioritize

• Additional hardcoded GDC-specific exports
• Specialized oncology-only reports

Prioritize Next

1. Scientist-facing cohort builder UI/REPL/Library
2. Template library
3. Semantic field catalog
4. Backend-neutral execution planning
5. Domain-independent terminology mapping

---

Decision

Loom should be viewed primarily as:

A FHIR-native cohort discovery and dataframe generation platform.

It should not currently be viewed as:

A molecular analytics platform.

The architecture demonstrates significant promise and is aligned with long-term goals for biomedical interoperability and cohort construction.

The dataframe builder subsystem represents the most strategically valuable component and should become the center of future platform investment.

---

Consequences

Positive

• Preserves FHIR fidelity
• Enables cohort discovery
• Supports graph-based biomedical traversal
• Provides foundation for low-code analytics
• Creates path toward reusable research data platforms

Negative

• Not yet suitable for direct molecular discovery
• Requires stronger abstraction from GDC-specific assumptions
• Requires substantial UX/Library work before broad scientist adoption
• Remains partially coupled to ArangoDB execution semantics

---

Final Verdict

Loom is a strong architectural prototype and emerging platform for FHIR-native cohort discovery.

Its greatest value is not the current set of hardcoded cohort reports, but the underlying dataframe-builder architecture that could eventually provide a reusable analytical layer across diverse biomedical FHIR repositories.

[bwalsh]

From a bioinformatician’s point of view, this repository is interesting and potentially useful as a cohort/dataframe extraction prototype, but it is not yet a mature analysis platform. Its strongest idea is that it turns FHIR NDJSON into graph-linked case/sample/file tables suitable for downstream cohort selection and metadata-driven analysis. Its main weakness is that it remains hardcoded around a few specific oncology/GDC-style traversals, with limited evidence of generalized biological query flexibility or production-grade reproducibility.

Overall review

What I like

• It is built around a real biomedical data problem: turning messy FHIR resources into analyzable case/file/sample matrices instead of leaving them as nested documents.
• It clearly understands important translational data relationships: Patient ↔ Specimen ↔ Group ↔ DocumentReference, plus Condition, ResearchSubject, and MedicationAdministration. That is exactly the kind of linking a bioinformatician needs for cohort definition and assay inventory.
• The repository explicitly supports two biologically meaningful outputs:
  • a file/sample/case matrix for per-file analyses, and
  • a case/assay matrix for cohort discovery and assay availability summaries.
• It preserves the original FHIR payload while also deriving flatter tables, which is a good compromise between traceability and analysis usability.

What concerns me

• The repo is still a prototype, and it says so repeatedly.
• It appears optimized around metadata-level discovery, not molecular-level querying. The README explicitly says a query like “find everyone with TP53 mutation” would require a second phase that indexes variant payload contents.
• It is highly specific to GDC-like semantics and coded assumptions about fields such as data_category, experimental_strategy, diagnosis coding, and us-core-* extensions.
• The setup and docs are still partly developer-centric and local-path-oriented, not yet shaped for reproducible bioinformatics deployment.

---

What this repo is biologically good for

This codebase is best understood as a FHIR-to-analysis bridge.

A bioinformatician usually does not want raw FHIR documents directly. We want questions like:

• Which cases have tumor specimens?
• Which cases have WXS, RNA-seq, CNV, or methylation evidence?
• Which files belong to which patient / specimen / study / diagnosis?
• Can I produce a dataframe for downstream filtering, survival modeling, or assay selection?

That is exactly what this repo is aiming at.

The README describes three hardcoded traversals, with the most important being:

• gdc_file_sample_matrix
• gdc_case_assay_matrix
  in addition to an older flattened_document_reference compatibility path. The case-assay matrix is explicitly described as the metadata-level starting point for questions like “find cases with tumor samples, annotated somatic mutation files, expression files, and slides.” That is a very sensible bioinformatics use case.

In the actual AQL query for gdc_case_assay_matrix, the code computes biologically relevant fields such as:

• case_id, case_submitter_id
• primary_diagnosis, diagnosis_body_site
• study_id, study_name, study_title
• specimen_count, specimen_types, preservation_methods
• assay/file presence flags and counts like has_wxs, has_wgs, has_rnaseq, has_expression, has_cnv, has_methylation, has_slide
• representative files for several assay classes

That is very much the shape of a usable cohort discovery table, not just a technical graph demo.

---

What the repository is actually doing

At a high level, the repo:

1. Loads FHIR NDJSON resource files.
2. Stores each resource in a backend database, primarily ArangoDB, with experimental support for SurrealDB and Postgres.
3. Builds explicit graph edges in fhir_edge.
4. Profiles observed fields into a catalog.
5. Runs hardcoded or builder-driven dataframe traversals through the graph.
6. Exposes both:
   • a CLI (cmd/arango-fhir-proto/main.go)
   • an HTTP/GraphQL server (cmd/arango-fhir-server/main.go)

The loader in internal/proto/load.go is not trivial glue code; it does substantial work:

• discovers NDJSON files by resource type,
• bootstraps collections,
• validates and builds rows,
• writes vertices and edges concurrently,
• records field catalog metadata.

That means this is not just a query repo; it is trying to own the ingest → graph construction → dataframe output pipeline.

---

Strengths from a bioinformatics perspective

1. The data model matches real translational workflows

The best part of the repo is that it respects biological context rather than flattening too early.

The AQL in queries/gdc_file_sample_matrix_rows.aql and queries/gdc_case_assay_matrix_arango_rows.aql follows realistic paths:

• DocumentReference → Specimen / Group / Patient
• Patient → Condition
• Patient → ResearchSubject / ResearchStudy
• Patient → MedicationAdministration

That matches how researchers think:

• files belong to specimens or case-level entities,
• diagnoses belong to patients,
• studies and treatment context matter,
• specimen types and preservation methods matter to downstream assay interpretation.

2. It distinguishes metadata discovery from variant-level interpretation

This is scientifically honest.

The README explicitly states that the current repo supports metadata-level questions, but not yet direct variant-content biology like “who has TP53 mutation.” That matters because many bioinformatics systems overpromise here. This repo does not.

3. Preservation of raw payloads

The loader keeps:

• payload
• id
• project
• resourceType
• _key = project::id

That is good scientific hygiene. If a derived dataframe column looks wrong, you can still inspect the original source representation.

4. Cohort-builder direction is promising

The GraphQL schema and the portability document show a move toward a FHIR-native dataframe builder, where users specify:

• root resource type,
• traversals,
• field selectors,
• pivots,
• preview/export mode.

For a bioinformatician, this is attractive because it suggests a future where one could define cohort extractions without writing AQL manually.

---

Weaknesses from a bioinformatics perspective

1. Too hardcoded for broad biological reuse

Right now, the repo is biologically useful only if your data resembles the author’s target use case.

Examples:

• diagnosis extraction depends on assumptions about coding systems containing strings like "primary_diagnosis"
• case IDs and submitter IDs are found via identifier systems containing "case_id" and "case_submitter_id"
• race/ethnicity/birth sex come from specific us-core-* extensions
• assay classification depends on data_category, data_type, and experimental_strategy values matching GDC conventions

That is fine for a prototype, but as a bioinformatician I would worry about:

• portability to non-GDC FHIR exports,
• different coding conventions,
• pediatric, infectious disease, rare disease, or longitudinal clinical datasets.

2. Limited evidence of sample lineage depth

The file/sample matrix is already useful, but more advanced biospecimen reasoning seems limited.

For example, there is some support for:

• specimen_parent_refs
• preservation_method
• group membership

But I do not see a broader biological model for:

• aliquots vs parent specimens,
• tumor/normal pairing,
• longitudinal collections,
• repeated sampling,
• timepoint-aware analyses,
• molecular observation linkage beyond file presence.

These are common pain points in real cohort analysis.

3. It is still mostly a metadata engine

The key limitation is that it summarizes what files exist, not what the biology says.

A bioinformatician often needs:

• gene-level mutation presence,
• expression thresholds,
• pathway signatures,
• copy-number status,
• tumor purity or ploidy,
• clinical endpoints.

This repo currently stops one level earlier: it tells you whether the infrastructure to answer those questions may exist, not the answer itself.

4. Reproducibility is not yet polished

The README includes local absolute paths like /Users/peterkor/Desktop/..., which is a red flag for portability. It does describe commands such as make build, make test, and make docker-build, but some repository files referenced in the README were not present at the top level through the API paths I checked, and the docs still feel prototype-stage rather than release-stage.

5. Some dependency hygiene concerns

go.mod includes local replace directives for:

• github.com/bmeg/jsonschemagraph
• github.com/bmeg/jsonschema/v6

That is inconvenient for outside users and especially for scientific reproducibility, where clean rebuilds matter.

---

Scientific usefulness: where I would and would not use it

I would use it for

• Cohort inventory
• Assay availability discovery
• Building case/file/sample metadata tables
• Evaluating whether FHIR exports preserve the relationships needed for downstream analysis
• Benchmarking graph backends for biomedical metadata traversal

I would not yet use it for

• primary biological discovery
• mutation-driven cohort selection
• end-to-end omics analysis
• clinically regulated workflows
• generalized FHIR analytics across many disease domains without substantial adaptation

---

Repository organization, in practical terms

The most important directories are:

cmd/
  arango-fhir-proto/    CLI for load/query/benchmark/discovery
  arango-fhir-server/   HTTP + GraphQL service
  generate/             code generation tooling

internal/
  dataframe/            dataframe builder/planner/compiler
  dbio/                 backend selection (Arango/Postgres/Surreal)
  fhir/                 large generated FHIR model/extract/validate code
  graphqlapi/           GraphQL schema, resolver, introspection, run service
  proto/                core ingest/query orchestration
  writeapi/             import API, auth/scope, async job service

queries/
  *.aql                 Arango queries for edge building and dataframe export

queries_surreal/
  *.surql               SurrealDB equivalents / probes

docs/
  DATAFRAME_BUILDER_PORTABILITY.md

For a bioinformatician, the biologically most meaningful files are:

• queries/gdc_case_assay_matrix_arango_rows.aql
• queries/gdc_file_sample_matrix_rows.aql
• internal/graphqlapi/schema.graphqls
• docs/DATAFRAME_BUILDER_PORTABILITY.md

Those tell you what biological questions the system can currently express.

---

Bottom-line verdict

My review: this is a strong prototype for biomedical metadata graph traversal and dataframe generation, especially for GDC-like FHIR datasets, but it is not yet a general-purpose bioinformatics analysis system.

If I were evaluating it as a bioinformatician, I would say:

• Biological relevance: high
• Generalizability across datasets: moderate to low
• Production readiness: low
• Usefulness for cohort construction and assay inventory: high
• Usefulness for direct molecular discovery: low for now
• Conceptual promise: high

Final recommendation

If your goal is:

• “Can we turn FHIR cancer metadata into usable cohort tables?” → Yes, this repo looks promising.
• “Can we support exploratory cohort-building across files, specimens, diagnoses, studies, and treatments?” → Yes, especially for GDC-shaped data.
• “Can we ask gene- or variant-level biological questions directly?” → Not yet.

---

Here’s the second-pass review: internal/dataframe/ is the part of the repo with the most direct promise for non-engineer bioinformatics users, but today it still behaves more like a query compiler for technically mediated workflows than a genuinely user-friendly cohort builder.

Bottom line

From a bioinformatics use-case perspective, internal/dataframe/ is trying to solve an important problem:

“How can a scientist describe the cohort table they want, using biological concepts, without hand-writing backend queries?”

That is the right problem to solve.

From the perspective of an end user with limited engineering skills, though, this subsystem is not yet easy enough on its own. It has strong conceptual foundations—resource traversal, field selection, pivoting, aggregations, representative file slices—but the user-facing contract still assumes a lot of hidden technical structure:

• FHIR resource types
• graph traversal labels
• selector syntax
• pivot semantics
• backend/data availability constraints

So my summary is:

• Excellent direction
• Strong for power users with informatics support
• Too technical for most bench scientists, clinical researchers, or junior analysts without a UI/helper layer

---

What internal/dataframe/ is doing

This package is the repo’s dataframe definition and compilation engine.

It defines structures like:

• Builder
• TraversalStep
• FieldSelect
• PivotSelect
• AggregateSelect
• RepresentativeSlice

in internal/dataframe/dataframe.go.

That means the user is not supposed to ask for raw graph edges directly. Instead, they define:

• a root resource type such as Patient
• fields to extract
• traversals to related resources like Specimen, Condition, or DocumentReference
• pivots
• counts/distinct-values/existence checks
• “representative” nested summaries

Then the package validates the request against observed fields/references and compiles it into an executable AQL query.

That is exactly the architecture you would want if your end goal is:

• cohort builder UI,
• study feasibility tool,
• file inventory explorer,
• no-code/low-code biomedical table builder.

So conceptually, this is the right layer.

---

Why this matters for low-engineering-skill users

A scientist with limited engineering skills usually does not want to think in terms of:

• Arango queries
• graph edges
• field catalogs
• selector parsing
• bind vars

They want to ask questions like:

• “Give me one row per case.”
• “Include diagnosis, specimen type, and whether RNA-seq exists.”
• “Show file categories available per patient.”
• “Count WXS files per case.”
• “Give me example slide files for each patient.”

internal/dataframe/ is clearly trying to become the layer that turns those intentions into queries.

That is a major strength.

But the current implementation still exposes too many technical seams.

---

Biggest strengths for bioinformatics users

1. The abstraction is biologically meaningful

The best part is that the abstraction is not database-first. It is biomedical traversal-first.

The Builder object centers on:

• root resource type
• traversals
• fields
• pivots
• aggregates
• representative slices

That maps surprisingly well to how translational scientists think about data assembly.

For example:

• start from Patient
• traverse to Specimen
• traverse to DocumentReference
• pull out diagnosis and study metadata
• summarize assay categories

That is much more intuitive than writing joins or graph traversals from scratch.

2. Validation against observed data is a huge win

One of the most scientist-friendly features is that the service validates requests against populated references and populated fields, rather than only against theoretical schema definitions.

In prepareSpec and validateBuilder, the code uses discovery methods to confirm:

• a traversal actually exists,
• a selected field is present,
• a pivotable field is really pivotable.

That matters a lot for low-engineering-skill users because one of the most frustrating experiences in biomedical tooling is:

• the schema says a field exists,
• but the dataset doesn’t actually populate it.

This package tries to protect users from that.

3. Aggregates and slices match common analyst needs

For scientists, raw one-to-many joins quickly become unreadable.

The presence of:

• aggregate operations like COUNT, COUNT_DISTINCT, EXISTS, DISTINCT_VALUES
• representative slices for a few exemplar files/records

is very practical.

A scientist often wants:

• “how many RNA-seq files?”
• “what specimen types are represented?”
• “show me 5 example files”

That is much more useful than dumping the full graph neighborhood.

4. Pivot support is highly relevant for phenotype-style data

The pivoting model—especially around CodeableConcept display values—is promising for:

• categorical clinical descriptors,
• coded observations,
• phenotype expansion into columns.

This can be very useful when users want a matrix-like structure suitable for R/Python/statistical export.

---

Main weaknesses for users with limited engineering skills

1. The user still has to know too much

This is the core problem.

Even though the abstraction is better than raw AQL, the user still needs to know things like:

• RootResourceType = Patient
• traversal labels like subject_Patient
• selector syntax like identifier[].value where system contains "case_id"
• pivot kind semantics
• which fields are pivot candidates
• which resource paths are authorized

A typical bioinformatics user may understand the biology, but not this grammar.

So this is not yet “self-serve” unless there is a UI or an informatics engineer sitting nearby.

2. Selector syntax is still too technical

The selector parser in ParseSelector supports expressions like:

• identifier[].value
• code.coding[].display
• extension[].valueString where url contains "us-core-race"

This is compact and sensible for developers, but for end users with limited engineering skills it is still quite demanding.

A scientist is more likely to think:

• “case ID”
• “primary diagnosis”
• “race”
• “experimental strategy”

not:

• identifier[].value where system contains "case_id"

This is one of the clearest places where a user-friendly metadata dictionary or point-and-click field picker is still needed.

3. Traversal labels are implementation concepts, not user concepts

A user should not need to know:

• subject_Patient
• subject_Specimen
• member_entity_Specimen

These are graph wiring details.

Biologists think in relationships like:

• specimen belongs to patient
• file belongs to specimen
• group contains specimens

The current builder model exposes the internal relationship labels too directly.

4. Error prevention is stronger than guidance

The validation logic is good at rejecting invalid requests.

But for low-skill users, rejection is only half the battle. What they need is:

• suggestion,
• autocomplete,
• “did you mean…”
• recommended field bundles,
• starter recipes.

Right now the package is better at saying no than at helping users say yes in the right way.

---

Specific scenarios: how this would feel for different users

Scenario 1: Bench scientist asking for a case table

User intent:

“I want one row per patient, with diagnosis, specimen type, and whether RNA-seq exists.”

Good news:
This subsystem can likely represent that.

Bad news:
The user probably cannot author the builder request alone unless a UI translates their request into:

• root Patient
• traversal to Specimen
• traversal to DocumentReference
• field selectors
• aggregate or boolean logic for RNA-seq presence

So the package supports the use case conceptually, but not yet in a directly self-service way.

Scenario 2: Clinical/translational researcher exploring cohort feasibility

User intent:

“Do we have enough cases with WXS + RNA-seq + slide images?”

This is exactly the sort of question the current abstractions are well-suited for:

• COUNT
• EXISTS
• file-summary traversal
• categorical aggregation

But again, the user needs either:

• a prebuilt recipe, or
• a front-end wizard.

Without that, they are still blocked by technical builder syntax.

Scenario 3: Bioinformatics analyst with light coding skills

User intent:

“I can work in notebooks, but I don’t want to maintain graph queries.”

This is the ideal near-term user.

Such a person could benefit from:

• curated builder templates,
• documented field refs,
• introspection-driven defaults.

For this user, internal/dataframe/ is actually quite promising. They may not need to understand the full implementation, only the recipe language.

Scenario 4: Multi-study data steward

User intent:

“I need a configurable, reusable export definition for multiple projects.”

This subsystem is also strong here because it formalizes dataframe definitions instead of hardcoding every output query. The presence of Builder, Compile, and advanced builder support suggests reusability.

But usability still depends on whether recipes can be packaged in a human-friendly way.

---

Advanced builder review: promising, but even more technical

advanced_types.go introduces:

• named sets
• unions
• filters
• derived fields
• representative slices
• lookup-study
• document classification operations

From an informatics architecture perspective, this is powerful.

From a low-engineering-skill user perspective, this is too advanced to be directly exposed.

For example, concepts like:

• SetKindTraverse
• SetKindFilter
• SetKindUnion
• DerivedOpCountDistinct
• DerivedOpPivot

are useful internally, but they read like implementation primitives, not scientific actions.

That’s okay if this is a backend engine. It’s not okay if this is the main user contract.

So my assessment is:

• great internal DSL
• poor direct end-user language

---

What works especially well for a future UI

If I were designing a scientist-facing tool on top of this package, these are the parts I’d feel best about:

Introspection-backed field discovery

The package already relies on discovered fields and traversals. That is perfect for building:

• dropdowns,
• search/autocomplete,
• “available related resources” panels,
• field recommendations.

Strong typed operations

Having explicit concepts for:

• field
• pivot
• aggregate
• slice

means a UI can offer clean controls like:

• “add a field”
• “count related records”
• “pivot coded values”
• “include example files”

Validation before execution

This is great for protecting nontechnical users from wasted runs and incomprehensible backend errors.

Compilation to backend query

Users never need to see AQL if the application layer is well designed.

---

What is still missing for limited-skill users

1. Named biological templates

The biggest immediate gap is a library of recipes like:

• Case-level assay availability matrix
• File/sample metadata export
• Tumor specimen inventory
• Study enrollment overview
• Treatment-by-case summary

Nontechnical users need to start from these, not from a blank builder object.

2. Friendly field aliases

The system needs a stable layer of display labels such as:

• Case ID
• Diagnosis
• Specimen type
• Preservation method
• Data category
• Experimental strategy

instead of expecting selector knowledge.

3. Relationship phrasing in plain language

Instead of subject_Patient, users should see:

• linked specimens
• linked diagnoses
• linked files
• linked study enrollment

4. Smart defaults

The best cohort tools do not ask the user to choose everything.
They infer likely defaults:

• root resource type = Patient
• use all authorized resource paths
• choose common identifier fields
• default representative file slice size = 5
• default assay summary columns

5. Example-driven documentation

This package would benefit enormously from “cookbook” examples written for scientists:

• “Build a patient-level assay availability table”
• “Export file-level metadata for RNA-seq”
• “Count treatment categories per case”

---

My bioinformatics verdict on internal/dataframe/

Scientific/product value

High.

Current direct usability for low-engineering-skill end users

Low to moderate.

Suitability as a backend for a no-code/low-code biomedical dataframe builder

High.

Risk

The biggest risk is not technical failure.
The biggest risk is stopping one layer too early—building a very capable compiler that still feels inaccessible to the people who most need it.

---

Practical recommendation

If this subsystem is intended for end users with limited engineering skills, the next priority should not be more compiler power. It should be:

1. recipe templates
2. plain-language field/relationship vocabulary
3. autocomplete/introspection UI
4. guided builder workflow
5. scientist-oriented examples

Without that, internal/dataframe/ will mainly serve:

• backend engineers,
• informatics platform developers,
• advanced analysts

With that layer, it could become genuinely useful to:

• translational scientists,
• disease team analysts,
• clinical data curators,
• bioinformaticians who can script a little but don’t want to write graph queries.

Final one-sentence review

internal/dataframe/ is a strong foundation for a scientist-facing cohort/dataframe builder, but today it is still an expert-oriented engine rather than a truly accessible tool for bioinformatics users with limited engineering skills.

---

From a GraphQL engineer’s perspective, internal/dataframe/ is the most strategically important part of the repository: it is effectively a query-planning layer that turns a constrained GraphQL-ish dataframe specification into validated backend execution. The overall design is strong, but it is sitting in an awkward middle state between domain-level GraphQL contract and internal AQL compiler DSL.

Bottom line

What’s good:
internal/dataframe/ shows a solid architecture for GraphQL-backed analytical querying:

• schema-driven builder input
• introspection/discovery-backed validation
• compile-time query generation
• support for field selection, traversals, pivots, aggregates, and representative slices
• separation between request model and backend query execution

What’s weak:
As a GraphQL engineer, I’d say the package currently has:

• too much coupling to Arango/AQL assumptions
• partial duplication of GraphQL concerns inside Go structs
• a contract that is more “GraphQL-adjacent” than truly GraphQL-native
• validation ergonomics that will become harder to scale as the schema grows
• advanced-builder internals that risk bypassing the clean public GraphQL model

So: good architecture, strong product direction, but the abstraction boundary is not fully settled yet.

---

What internal/dataframe/ appears to be

This package is not just “dataframe logic.” It is really three things combined:

1. public analytical request model

   • Builder
   • TraversalStep
   • FieldSelect
   • PivotSelect
   • AggregateSelect
   • RepresentativeSlice

2. validation layer

   • checks requested traversals against discovered populated references
   • checks field selectors against discovered populated fields
   • checks pivotability and aggregate validity

3. compiler/execution planning layer

   • compiles builder definitions into AQL
   • binds auth paths/project filters
   • executes rows through proto.ExecuteQueryRows

That’s a very reasonable architecture for a GraphQL analytics API. In practice, this package is the real “resolver brain” behind runFhirDataframe.

---

What I like as a GraphQL engineer

1. Strong separation between API intent and storage execution

This is the best architectural choice in the package.

The GraphQL layer does not expose raw backend query syntax. Instead, internal/dataframe/ accepts a structured semantic request and compiles it. That gives you:

• safety
• validation
• future backend flexibility
• control over performance patterns

That’s exactly what a GraphQL engineer wants for analytical APIs, because allowing arbitrary graph/database queries through GraphQL is usually a disaster.

2. Validation against observed data, not just type definitions

This is especially good.

The service validates builder inputs using discovered populated fields and references:

• DiscoverPopulatedReferences
• DiscoverPopulatedFields

That means the API is not merely schema-valid; it is dataset-valid. This is a huge advantage for analytics GraphQL because pure type safety is not enough when most user pain comes from sparse or absent data.

This also pairs nicely with GraphQL introspection-like UX, even though it’s custom discovery rather than standard SDL introspection.

3. The request model maps well to analytical GraphQL

The core primitives are right:

• field selections
• traversals
• pivots
• aggregates
• slices

These are meaningful analytical building blocks that fit well in a mutation-driven or query-driven analytics contract.

In particular, the design avoids trying to express analytical exports as deeply nested GraphQL response graphs, which is wise. GraphQL object trees are often a poor fit for tabular analytical output.

4. Auth scoping is integrated early

prepareSpec resolves auth resource paths before compile/run. That’s the right place to do it. It means auth is part of the logical dataset definition rather than an afterthought in resolver execution.

For GraphQL systems, that helps avoid subtle differences between:

• discoverable fields,
• accessible rows,
• executable requests.

---

Main concerns from a GraphQL engineering perspective

1. Public contract duplication across layers

There is a strong smell of contract duplication between:

• GraphQL schema in internal/graphqlapi/schema.graphqls
• GraphQL model mapping in internal/graphqlapi/*
• builder structs in internal/dataframe/dataframe.go

This is manageable now, but long term it risks:

• drift in semantics,
• drift in nullability/defaults,
• mismatched capabilities,
• complicated resolver translation logic.

For example, internal/dataframe has its own notions of:

• fields
• pivots
• aggregates
• slices
• traversals

while the GraphQL schema defines similar but not identical input structures. As a GraphQL engineer, I’d want one of two clearer outcomes:

• Option A: GraphQL input is the canonical product contract, and dataframe structs are an execution-normalized internal form.
• Option B: dataframe structs are the canonical semantic contract, and GraphQL is generated from or tightly derived from them.

Right now it feels like neither boundary is fully enforced.

2. The API is mutation-shaped but compiler-driven

The schema exposes runFhirDataframe as a mutation, which makes some sense for export-like behavior. But internal/dataframe behaves much more like a deterministic read query planner than a mutating workflow.

As a GraphQL engineer, I’d want a firmer conceptual model:

• Is this a read operation with expensive planning/execution?
• Is it a previewable analytical query?
• Is it an async export job in disguise?

The package seems architecturally prepared for query planning and row return, but less clearly aligned with a long-term GraphQL operation model. That ambiguity will matter once pagination, caching, persisted operations, async exports, and execution observability are added.

3. The selector mini-language is doing too much work

ParseSelector and the selector expression logic are clever, but from a GraphQL API design standpoint this is a compromise that may age poorly.

Why? Because instead of fully modeling field extraction in structured GraphQL input, the system relies on string expressions like:

• identifier[].value
• extension[].valueString where url contains "us-core-race"

That gives flexibility, but it also introduces:

• parser maintenance burden,
• awkward validation surface,
• weaker introspection,
• worse editor/tooling support,
• more brittle client contracts.

A GraphQL engineer generally wants more structure and less embedded string DSL unless there is a very strong payoff. Here the payoff is compactness, but the cost is long-term product ergonomics.

4. Advanced builder risks bypassing the clean GraphQL abstraction

The advanced model in advanced_types.go is powerful:

• named sets
• unions
• filters
• derived fields
• document classification
• study lookup

But it reads like an internal execution DSL, not a GraphQL-facing product model.

That’s fine if it stays internal.
It becomes a problem if future feature pressure causes GraphQL inputs to directly expose these concepts. If that happens, the API may become too implementation-shaped and difficult to stabilize.

As a GraphQL engineer, I would keep this advanced builder strictly behind:

• recipe lowering,
• planner transformations,
• internal optimization passes.

Not as the primary external contract.

5. Compiler is backend-aware in ways that may constrain future evolution

Run currently hard-rejects non-Arango backends for dataframe execution:

• runFhirDataframe currently supports only backend "arango"

Also, the compiler logic in Compile and traversal construction is very AQL-shaped:

• bind vars
• FOR
• LET
• UNIQUE
• FLATTEN
• one-hop inbound traversal logic

That’s okay for now, but it means internal/dataframe/ is not purely semantic. It is already partly a backend-specific query generator.

From a GraphQL platform standpoint, that’s not necessarily bad—but it means the portability story should be told honestly:

• this is a GraphQL analytical layer with Arango as the true execution substrate
• not yet a backend-neutral planner

---

Review of the request/compile design

Builder model

The Builder struct is a good center of gravity. It is broad enough to capture:

• root scope
• traversal tree
• row shape
• summary/pivot logic

That said, it currently mixes:

• user-facing concepts,
• planning hints,
• advanced/internal execution constructs.

That mixture will become harder to reason about over time.

I’d prefer a stricter split like:

• PublicBuilderSpec
• NormalizedBuilderSpec
• ExecutionPlan

Right now Builder is doing too many jobs.

Validation path

prepareSpec, validateBuilder, and expandPivotColumns are well designed as a pipeline:

1. auth resolution
2. semantic validation
3. pivot enrichment
4. optional lowering into advanced builder

That sequence makes sense and is a good foundation for future observability/debuggability.

Compile path

Compile is pragmatic and readable in concept, but the implementation is carrying a lot of string-based query assembly.

As the GraphQL contract grows, I’d worry about:

• compile fragility
• test surface explosion
• difficulty optimizing generated queries
• difficulty reasoning about cost

At some point, this may want a more explicit intermediate representation rather than direct string emission.

---

GraphQL product-fit assessment

Good fit for:

• analytical preview mutations/queries
• cohort/dataframe builder experiences
• guided UI-driven GraphQL clients
• domain-constrained export operations
• introspection-backed builder tooling

Less good fit for:

• arbitrary ad hoc analytical querying
• client-authored freeform selector expressions at scale
• multiple backend execution engines without a stronger IR
• strongly typed long-lived GraphQL client SDKs unless the selector DSL is better structured

---

How this would feel in a real GraphQL engineering team

Scenario 1: Building a cohort-builder UI

This package is very promising.

A frontend can:

• fetch introspection hints,
• present available traversals and fields,
• construct a builder,
• submit to runFhirDataframe.

That is an excellent use case.

Scenario 2: Supporting many external API clients

This is less comfortable.

The more clients directly construct selector-heavy input objects, the more:

• contract education,
• validation messaging,
• versioning pain,
• UX inconsistency

you will have.

This package really wants either:

• a strong first-party UI, or
• a recipe/template layer.

Scenario 3: Evolving the GraphQL schema over time

This is where contract drift risk shows up.

If new capabilities are added first in internal/dataframe, then later mapped into GraphQL, the schema may become inconsistent. Conversely, if schema features are added first, builder lowering may become messy.

The current design is workable, but needs stricter ownership of the product contract.

---

Specific strengths in internal/dataframe/

prepareSpec

Strong orchestration point. Good place for:

• auth resolution,
• builder normalization,
• contract checks,
• lowering.

validateTraversal

Very good pattern: validate requested graph traversals against discovered data, not only schema. This is product-friendly and operationally wise.

fillPivotColumns

Nice ergonomics improvement. Reduces client burden by deriving pivot columns from discovery metadata.

Compile

Despite backend coupling, this is the right conceptual boundary. GraphQL resolvers should not be hand-building AQL themselves.

Selector.CanonicalPath()

A simple but important normalization primitive. Good for matching selector requests to discovered field metadata.

---

Specific weaknesses in internal/dataframe/

Mixed abstraction levels in Builder

Public semantics + planning hints + advanced execution constructs in one aggregate type.

String DSL reliance

Good short-term; questionable long-term.

Compiler string assembly

Likely fine now, but will become harder to optimize, validate, and maintain.

Backend-specific assumptions

Current “semantic builder” is not really storage-neutral.

Implicit lowering behavior

lowerGraphQLBuilder(expanded) suggests hidden transformations that may become difficult to reason about unless thoroughly documented and tested.

---

What I would recommend as a GraphQL engineer

1. Make the contract boundary explicit

Decide whether:

• GraphQL input is the canonical API model, or
• dataframe builder structs are.

Then enforce one-way normalization.

2. Split semantic spec from execution plan

Separate:

• public analytical request
• normalized internal request
• optimized execution plan
• backend query text

That will make the system easier to evolve.

3. Keep advanced builder internal

Use it as a lowering target, not as the first-class public model.

4. Consider structuring selectors more over time

Even if you keep string selectors for now, I’d plan a path toward more structured selector input for better tooling and validation.

5. Add cost/complexity planning hooks

Analytical GraphQL tends to become expensive. internal/dataframe/ is the perfect place to eventually add:

• query complexity scoring
• traversal depth limits
• output width constraints
• aggregate/pivot cost heuristics

---

Final verdict

From a GraphQL engineer’s perspective, internal/dataframe/ is a well-conceived analytical planning layer with strong validation and a sensible execution boundary, but it still needs a cleaner separation between public GraphQL contract, internal semantic model, and backend-specific compilation strategy.

In shorter form:

It’s a good GraphQL analytics engine foundation, but not yet a fully settled GraphQL architecture.