iSamples MVP Cleanup & Simplification Strategy

[rdhyee]

Overview

This issue documents the cleanup strategy for tying a bow around the iSamples project (this round). Goal: simplify to an MVP, then refine.

Date: 2026-01-29
Scope: 3 repositories (isamplesorg-metadata, isamples-python/examples, isamplesorg.github.io)

---

The Stack at a Glance

┌─────────────────────────────────────────────────────────────────────┐
│                        USER EXPERIENCE                               │
├──────────────────────────────┬──────────────────────────────────────┤
│  isamplesorg.github.io       │  isamples-python (examples)          │
│  (Browser - Zero Install)    │  (Jupyter - Developer)               │
│  • isamples_explorer.qmd     │  • isamples_explorer.ipynb           │
│  • parquet_cesium_*.qmd      │  • geoparquet.ipynb                  │
│  • DuckDB-WASM + Cesium      │  • DuckDB + Lonboard                 │
└──────────────────────────────┴──────────────────────────────────────┘
                                    │
                          ┌─────────▼─────────┐
                          │   DATA LAYER      │
                          │   Cloudflare R2   │
                          │   Wide: 280MB     │
                          │   Narrow: 850MB   │
                          └─────────┬─────────┘
                                    │
┌───────────────────────────────────▼─────────────────────────────────┐
│                     METADATA STANDARD                                │
│                   isamplesorg-metadata                               │
│  • 8 Entity Types (MaterialSampleRecord, SamplingEvent, etc.)       │
│  • 14 Predicates (produced_by, has_material_category, etc.)         │
│  • JSON Schema, JSON-LD, SKOS vocabularies                          │
└─────────────────────────────────────────────────────────────────────┘

---

MVP Definition: What to Keep

Tier 1: Essential (The Core Product)

Component	Location	Purpose
Data on R2	Cloudflare	Wide parquet (280MB) - single source of truth
Schema	isamplesorg-metadata	isamples_core.yaml + JSON Schema
Browser Explorer	isamplesorg.github.io	isamples_explorer.qmd - main discovery UX
3D Globe	isamplesorg.github.io	parquet_cesium_isamples_wide.qmd
Jupyter Explorer	isamples-python	isamples_explorer.ipynb - developer entry point
Visualization Patterns	isamples-python	geoparquet.ipynb - Lonboard patterns

Tier 2: Educational (Keep for Learning)

Component	Location	Purpose
PQG Demo	isamples-python	pqg_demo.ipynb - property graph queries
Schema Comparison	isamples-python	schema_comparison.ipynb - narrow vs wide
SQL Deep Dive	isamplesorg.github.io	zenodo_isamples_analysis.qmd
Graph Documentation	isamplesorg-metadata	src/docs/UNDERSTANDING_THE_GRAPH.md

---

Cleanup Actions

✅ Completed: isamples-python (PR #2 merged)

• Archived defunct API client → archive/defunct-api-client/
• Archived export parquet tools → archive/export-parquet-tools/
• Updated pyproject.toml to examples-only repo
• Updated README, CLAUDE.md, STATUS.md

🔲 TODO: isamples-python (remaining)

• Remove playwright/ directory (-15MB node_modules cruft)
• Clean .ipynb_checkpoints/ across examples

🔲 TODO: isamplesorg.github.io

Action	Impact	Effort
Delete assets/oc_isamples_pqg.parquet	-724MB	5 min
Archive empty stubs (parquet.qmd, etc.)	Clarity	10 min
Update tutorial index to highlight 3 core tutorials	UX	15 min
Add cross-links to isamples-python	Discovery	10 min

🔲 TODO: isamplesorg-metadata

Action	Impact	Effort
Add "Related Repositories" section to README	Discovery	10 min
Archive notes/vocabulary/ (moved to separate repo)	Clarity	5 min
Archive examples/APItesting/	Clarity	5 min
Consolidate README + new PQG docs into "Getting Started"	Onboarding	30 min

---

Cross-Repo Linking

Each repo should include this in README:

## Related iSamples Repositories

| Repo | Purpose | Start Here |
|------|---------|------------|
| [isamplesorg-metadata](https://github.com/isamplesorg/metadata) | Schema definition | `src/schemas/isamples_core.yaml` |
| [isamples-python](https://github.com/isamplesorg/examples) | Jupyter examples | `examples/basic/isamples_explorer.ipynb` |
| [isamplesorg.github.io](https://isamplesorg.github.io/) | Browser tutorials | `tutorials/isamples_explorer.qmd` |
| [vocabularies](https://github.com/isamplesorg/vocabularies) | SKOS terms | Material types, context categories |

---

Canonical Data URLs

All repos should reference:

# Wide format (primary) - 280MB, 20M rows
WIDE_URL = "https://pub-a18234d962364c22a50c787b7ca09fa5.r2.dev/isamples_202601_wide.parquet"

# Narrow format (advanced) - 850MB, 106M rows  
NARROW_URL = "https://pub-a18234d962364c22a50c787b7ca09fa5.r2.dev/isamples_202512_narrow.parquet"

---

The "Bow" Summary

What iSamples MVP delivers:

1. A domain-agnostic metadata standard for material samples (metadata repo)
2. 6.7M samples from 4 sources in efficient geoparquet format (R2)
3. Zero-install browser exploration with Cesium + DuckDB-WASM (website)
4. Developer-friendly Jupyter examples for custom analysis (python repo)

What makes it work:

• Single data source (R2 parquet) - no API dependency
• Consistent schema (8 types, 14 predicates) across all domains
• Two complementary UIs: browser (discovery) + Jupyter (analysis)

[rdhyee]

Wireframe alignment status (April 9, 2026)

Full Figma API scan of iSamples Wireframe 1.0 completed. Here's the current state:

Completed ✅

• Homepage redesign: merge John's visual approach with Hana's wireframe structure #58 Homepage redesign (hero, stats, showcase, accordions)
• Consolidate progressive globe + explorer into one Interactive Explorer page #59 Consolidated Interactive Explorer (search, filters, globe, sample card)
• Restructure navigation to match wireframe IA #60 Restructure nav menus to match April wireframe #85 Navigation restructure (sidebar + navbar match wireframe)
• Restructure About page per wireframe (Objectives, Team, Gallery, History) #61 About page restructure (Objectives, Team, Gallery, History)
• Create 'How to Use' getting-started page #62 How to Use page with Quick Start
• Add Specimen Type filter to Interactive Explorer #70 Add Max Samples slider to Interactive Explorer #71 Add Sample Card panel to Interactive Explorer #72 Explorer: Specimen Type filter, Max Samples slider, Sample Card
• Rename Information Architecture to Architecture and Vocabularies #73 Rename IA → Architecture and Vocabularies
• Merge Published Research and Resources into single sidebar section #74 Merge Published Research + Resources
• Add accordion menus for long-form content pages #86 Accordion menus (Requirements page)
• Create Tutorials landing page #87 Tutorials landing page
• Embed media: YouTube video and PDF viewer #88 YouTube + PDF embeds on Publications
• Set up data.isamples.org custom domain for R2 parquet files #75 data.isamples.org custom domain
• PR Use data.isamples.org for all parquet file URLs #79 URL migration to data.isamples.org

Open — wireframe gaps

• Unify Research & Resources into a single page #96 Unify Research & Resources into single page (add Zenodo/GitHub sections)
• Add navigation arrows to Photo Gallery #97 Photo Gallery navigation arrows/carousel
• Decide: on-site Schema page vs external Metadata Model link #98 Schema page decision (on-site vs external link)
• Create Architecture overview diagram #99 Architecture overview diagram (needs Hana)
• Improve Vocabularies table readability #100 Vocabularies table readability

Open — Explorer improvements

• Add cross-filtering to Explorer facet counts #94 Cross-filtering (PR open)
• Improve search: multi-term AND + relevance ranking (FTS spike) #95 FTS search spike (PR open)
• Tweak animated globe hero: camera angle, speed, styling #77 Globe hero tweaks

Open — infrastructure

• Add backup Cloudflare admin for isamples.org (bus factor) #80 Backup Cloudflare admin
• Design URI structure for data.isamples.org #81 URI structure for data.isamples.org

Analysis generated via Figma API + site comparison by Claude Code.

[rdhyee]

Closing as the umbrella scope has been addressed. Since this was filed in January 2026:

• Interactive Explorer (progressive_globe) became the hero, Search Explorer kept as second door
• 3D Globe Visualization archived (Restructure How to Use menu; archive 3D Globe Visualization #116) since Interactive Explorer subsumes it
• Technical: Narrow vs Wide moved to Architecture & Vocabularies
• Wireframe alignment sprint (April 9-10) closed out Unify Research & Resources into a single page #96, Add navigation arrows to Photo Gallery #97, Improve Vocabularies table readability #100, Add Architecture & Vocabularies and Research & Resources to top navbar #102, Expand BDD test suite to cover wireframe functionality #104
• Palette centralized (Align source color palette across hero globe and Interactive Explorer #113, Centralize SOURCE_COLORS palette; re-capture hero globe (fixes #113) #114) and schema page gained conceptual orientation (upstream metadata repo explorer: add camera.moveEnd URL-write backstop (closes #204) #205, explorer: 'Samples in View' counter is the fetch budget, not the real count (#201 Part 1) #206)

Remaining specifics are already tracked as focused issues (#47 vocab build-time, #57 material category bug, #80 Cloudflare backup, #81 URI structure, #84 FTS, #98 schema page, #99 architecture diagram). Reopen as a fresh strategy doc when planning the next phase.