Modularization and Contributing update

.github/workflows/test.yml

@@ -2,7 +2,9 @@ name: Run tests
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+        - 'main'
+        - 'dev'
 
 jobs:
   test:

.zenodo.json

@@ -31,9 +31,9 @@
       "searchability"
     ],
     "title": "Imageomics Catalog",
-    "version": "4.2.0",
+    "version": "4.3.0",
     "license": "MIT",
-    "publication_date": "2026-05-22",
+    "publication_date": "2026-07-08",
     "grants": [
         {
             "id": "021nxhr62::2118240"

AGENTS.md

@@ -31,10 +31,12 @@ Path | Purpose
 `public/tag-groups.js` | **Secondary customization point.** Canonical tag aliases; maps raw tags to normalized display tags.
 `index.html` | Static HTML shell; config values are applied dynamically.
 `style.css` | Custom styles; colors are set via CSS custom properties populated from `config.yaml`.
-`main.js` | All application logic: config loading, API calls, filtering, sorting, and rendering.
-`src/` | Pure utility modules imported by `main.js` and the build scripts.
+`main.js` | Application orchestrator. Wires up event listeners and coordinates data flow between UI and API layers.
+`src/api/` | Data fetching modules (`fetchCodeRepos.js`, `fetchHfRepos.js`, etc.).
+`src/ui/` | DOM manipulation, HTML templating (`render.js`), and URL/State routing.
+`src/utils/` | Pure utility functions (filtering, sorting, tag normalization).
 `scripts/` | Build-time Node scripts (`fetch-releases.js`, `export-tags.js`).
-`tests/` | Vitest unit and integration tests.
+`tests/` | Vitest unit and integration tests. Subdirectories mirror the `src/` folder layout.
 `docs/` | Developer-facing documentation.
 `.github/workflows/` | CI/CD: tests on PR, deploy on push to `main`, weekly tag scan.
 
@@ -64,7 +66,7 @@ Spaces | `https://huggingface.co/spaces/{owner}/{repo}`
 
 The bulk `models?author={org}&full=true` list response does **not** return `cardData` for models. `cardData` (which contains `model_name`, `description`, tags, etc.) is only available when each model is fetched individually.
 
-`main.js` handles this with an extra parallel fetch after the list call (search `Step 2: If we are fetching models`). **Any change to model fetching must preserve this secondary per-model call.**
+`src/api/fetchHfRepos.js` handles this with an extra parallel fetch after the list call (search `Step 2: If we are fetching models`). **Any change to model fetching must preserve this secondary per-model call.**
 
 ### `cardData` Key Differences Across Resource Types
 
@@ -74,7 +76,7 @@ Datasets | `cardData.pretty_name` | `cardData.description`
 Models | `cardData.model_name` | `cardData.model_description`
 Spaces | `cardData.title` | `cardData.description`
 
-Code that accesses card metadata must account for all three shapes. The rendering function `renderHubItemCard` in `main.js` already does this with fallback chains.
+Code that accesses card metadata must account for all three shapes. The rendering function `renderHubItemCard` in `src/ui/render.js` already does this with fallback chains.
 
 ## Testing
 
@@ -90,17 +92,18 @@ npm run test:watch  # watch mode
 Current test files:
 - `tests/validateConfig.test.js` — unit tests for `src/validateConfig.js`
 - `tests/config.integration.test.js` — confirms `public/config.yaml` passes validation
-- `tests/filterAndSort.test.js` — unit tests for `src/filterAndSort.js`
-- `tests/filterNewAdditionalEntries.test.js` — unit tests for `src/filterNewAdditionalEntries.js`
-- `tests/normalizeTag.test.js` — unit tests for `src/normalizeTag.js`
+- `tests/utils/filterAndSort.test.js` — unit tests for `src/utils/filterAndSort.js`
+- `tests/utils/filterNewAdditionalEntries.test.js` — unit tests for `src/utils/filterNewAdditionalEntries.js`
+- `tests/utils/normalizeTag.test.js` — unit tests for `src/utils/normalizeTag.js`
 
 When adding a new utility to `src/`, add a corresponding test file. Do **not** add tests that make live network calls.
 
 ## Configuration
 
 All runtime behavior is controlled by `public/config.yaml`. It is fetched at page load (not bundled), so changes take effect on the next page load without a rebuild. Key fields:
 
-- `ORGANIZATION_NAME` — used in all API calls (must be lowercase)
+- `ORGANIZATION_NAME` — used in all code repository platform API calls (GitHub is not case-sensitive)
+- `HF_ORGANIZATION_NAME` — used in all Hugging Face API calls (**case-sensitive**)
 - `API_BASE_URL` — Hugging Face API base (default: `https://huggingface.co/api/`)
 - `PLATFORM` — code repository platform; only `github` is currently supported
 - `ADDITIONAL_REPOS` — forked or external GitHub repos to include
@@ -117,11 +120,15 @@ npm run build     # production build → dist/
 npm run preview   # preview production build locally
 ```
 
+## Contributing Workflow
+
+Changes should be made on a branch off of `dev`. All new features and development are submitted to the `dev` branch for PR review and staging before merging to `main`. Do not open pull requests to `main`; the existing GitHub Action Tag Scan workflow directed to `main` is allowed behavior, distinct from these instructions.
+
 ## CI Workflows
 
 Workflow | Trigger | Purpose
 ---|---|---
-`test.yml` | PR to `main` | Runs `npm test`
+`test.yml` | PR to `main` and `dev` | Runs `npm test`
 `deploy.yml` | Push to `main`, daily schedule, manual | Builds and deploys to GitHub Pages
 `weekly-tag-scan.yml` | Weekly schedule, manual, PR close cleanup | Detects new tags and opens a PR to update `tag-groups.js`
 `validate-zenodo.yaml` | Push (paths filter) | Validates `.zenodo.json`

CITATION.cff

@@ -11,14 +11,14 @@ authors:
   given-names: "Balaji"
   affiliation: "The Ohio State University"
 cff-version: 1.2.0
-date-released: "2026-05-22"
+date-released: "2026-07-08"
 identifiers:
-  - description: "The GitHub release URL of tag v4.2.0."
+  - description: "The GitHub release URL of tag v4.3.0."
     type: url
-    value: "https://github.com/Imageomics/catalog/releases/tag/v4.2.0"
-  - description: "The GitHub URL of the commit tagged with v4.2.0."
+    value: "https://github.com/Imageomics/catalog/releases/tag/v4.3.0"
+  - description: "The GitHub URL of the commit tagged with v4.3.0."
     type: url
-    value: "https://github.com/Imageomics/catalog/tree/238dbf5624b0fb9b61c795624d22b082f4591cd5" # Update on release
+    value: "https://github.com/Imageomics/catalog/tree/<commit-hash>" # Update on release
 keywords:
   - imageomics
   - code
@@ -37,6 +37,6 @@ license: MIT
 message: "If you use this software, please cite it as below."
 repository-code: "https://github.com/Imageomics/catalog"
 title: "Imageomics Catalog"
-version: "4.2.0"
+version: "4.3.0"
 doi: "10.5281/zenodo.17602801"
 type: software

CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to the Catalog
+
+Thank you for your interest in contributing to the catalog! This document outlines the standards and guidelines for contributing to this template repository.
+
+## Overview
+
+This catalog is built with JavaScript and relies on API calls to code, data, model, and spaces repositories to populate the web app in real time. Deployment only requires a static site-capable web server. The [Imageomics instance](https://catalog.imageomics.org) is currently deployed via GitHub Pages.
+
+This is a template repository designed to be copied (with "Use this Template") and customized by different organizations to present their code, data, models, and spaces in a dynamic, searchable site. The default setup is for the Imageomics Institute's GitHub and Hugging Face products.
+
+## Getting Started
+
+Follow [development guidance](README.md#development-prerequisites) for local setup and formatting expectations. 
+
+### Testing Changes
+
+Always test your changes locally with `npm test` before submitting a PR to ensure:
+
+- Content renders correctly.
+- Fetching, sorting, and filtering appear as intended.
+- No build errors occur.
+
+UI features should be tested locally through running a preview.
+
+## Coding Style, Conventions, and Project Structure
+
+Please refer to our [AGENTS.md](AGENTS.md). This also includes special notes on key differences between the repo types (datasets, models, and spaces) in Hugging Face API calls and returns,  as well as important considerations for the templated design of this repository.
+
+## Contribution Process
+
+1. **Create an issue** describing the problem or necessary change **in your own words**.
+    - Check existing [issues](https://github.com/Imageomics/catalog/issues) first.
+    - If you'd like to work on an existing issue, please comment on it to express interest or describe your potential fix.
+2. **Create a feature branch** from `dev`. 
+    - It is important that a repo fork includes the `dev` branch content since updates are staged there.
+3. **Make your changes** following the standards above.
+4. **Test locally** with `npm test`
+5. **Run linter/formatter** to ensure formatting consistency
+   - See [formatting standard](README.md#formatting-standard)
+6. **Submit a pull request** with:
+   - Clear description of changes **in your own words**.
+   - Reference to related issue.
+   - Screenshots if UI changes are involved.
+
+> [!IMPORTANT]
+> Please describe your changes or issues in your own words, not with AI-generated text. We understand that AI is sometimes used to help refine or improve writing; this is fine. AI has been used collaboratively in developing this template, and similar use is acceptable, though **AI use in PRs must be acknowledged and checked by the PR author**.
+
+### Pull Request Guidelines
+
+- Keep PRs focused on a single topic when possible.
+- Include tests and documentation updates for changes, as needed.
+- Follow commit message conventions (see below).
+- Test that the site builds without errors.
+
+### Commit Message Guidelines
+
+Commit messages should be **descriptive** and the PR should be **self-contained** (code change accompanied by tests and documentation of new functionality). We use squash merges for this repository, so strict adherence to, e.g., the [Conventional Commits](https://www.conventionalcommits.org/) format for commit messages is not necessary, but helpful for PR titles. 
+
+### Content Review
+
+When reviewing content:
+
+- Verify functionality and local build without errors.
+- Check for consistency with existing setup, especially for end-user consistency.
+- Test compatibility with various filter and sort options.
+
+## Code of Conduct
+
+Following the [Imageomics core values](https://imageomics.github.io/Imageomics-guide/CODE_OF_CONDUCT/#values), we expect contributors to be respectful and kind.
+
+---
+
+Thank you for helping improve the Catalog! Your contributions help make research products more discoverable.

README.md

@@ -2,7 +2,7 @@
 
 Repository for web-based catalog of Imageomics code, data, models, and spaces. This template catalog is designed to fetch live data from an organization's code repository platform (e.g., GitHub) API and dataset, model, and spaces repository data from the Hugging Face API to render a searchable, filterable catalog page as a static site via GitHub Pages. The default setup is for the Imageomics Institute's [GitHub](https://github.com/Imageomics) and [Hugging Face](https://huggingface.co/imageomics) organizations.
 
-For those interested in creating a similar catalog website, instructions for use and personalization are provided below, under [How to Use this Template](#how-to-use-this-template). More background on this site's creation is provided in the [docs](docs/).
+For those interested in creating a similar catalog website or contributing to this template, instructions for use and personalization are provided below, under [How to Use this Template](#how-to-use-this-template). More background on this site's creation is provided in the [docs](docs/).
 
 ## Features
 
@@ -28,18 +28,25 @@ The site runs based on four primary files:
 * `public/config.yaml`: Contains all customizable settings including organization names, colors, branding, and API settings. This is the main file to edit for personalization. Placed in `public/` so Vite copies it to `dist/` without bundling, keeping it editable after deployment.
 * `index.html`: The main HTML file that provides the structure of the webpage and links to the CSS and JavaScript files. Config values are applied dynamically from `config.yaml`.
 * `style.css`: Custom styling for the application, including color schemes, layout, and animations. Colors are set via CSS custom properties that are populated from `config.yaml`.
-* `main.js`: Handles the application's logic, including config loading, API calls, data filtering, sorting, and dynamic rendering of the catalog items. Relies on the build-time Node script `fetch-releases.js` for version-tag badge feature.
+* `main.js`: Application manager, handles config loading, event listeners, and coordinates UI updates based on API fetches for dynamic rendering of the catalog items.
+* `src/`: Modular application logic, organized by purpose:
+    * `api/`: Data fetching modules for external platforms (GitHub and Hugging Face).
+    * `ui/`: DOM manipulation, HTML templating, and URL/State routing.
+    * `utils/`: Utility functions such as data filtering, sorting, and tag (keyword) normalization. 
 
 Two additional files support the build tooling:
 
 * `package.json`: Declares npm dependencies (`vite`, `tailwindcss`, `@tailwindcss/vite`) and defines the `dev`, `build`, and `preview` scripts.
 * `vite.config.js`: Vite configuration that registers the Tailwind CSS plugin.
+* `scripts/fetch-releases.js`: Build-time Node script to fetch GitHub repo release data for version-tag badge feature.
 
 ## How to Use This Template
 
 This Catalog is set up as a template repository. To build a personalized version of the Catalog, select "Use this Template" at the top of the repo to generate your own version. This will create a new repository (generated from the template repo) that does not share the commit history of the template. Updates can still be added from the template upstream through `git cherry-pick`.[^1] 
 [^1]: We recommend following the [Git Cherry-pick Guide](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/Git-Cherry-Pick-Guide/) from the [Collaborative Distributed Science Guide](https://imageomics.github.io/Collaborative-distributed-science-guide/) for those unfamiliar with this process.
 
+For those looking to contribute to the template, please read our [contributing guide](CONTRIBUTING.md) and fork the repository.
+
 ### Personalizing Your Catalog
 
 The primary way to personalize this catalog is through the `config.yaml` file, which contains all customizable settings. After using the template, follow the [personalization guide](docs/personalization.md) to update the [config file](public/config.yaml), [package.json](package.json), and [tag groups](public/tag-groups.js) for your organization.

docs/personalization.md

@@ -8,8 +8,9 @@ Welcome to your new catalog repo! The primary way to personalize this catalog is
 
 ### Organization & Repository Settings
 
-  * `ORGANIZATION_NAME`: Your GitHub/Hugging Face organization name (lowercase for API calls)
-  * `ORG_NAME`: Display name for your organization (can differ from API name); used as fallback site title if `CATALOG_TITLE` is not set
+  * `ORGANIZATION_NAME`: Your code platform (e.g., GitHub) organization name (for API calls)
+  * `HF_ORGANIZATION_NAME`: Your Hugging Face organization name (**case-sensitive**, for API calls)
+  * `ORG_NAME`: Display name for your organization (can differ from API name); used for logo alt-text and as fallback site title if `CATALOG_TITLE` is not set
   * `CATALOG_REPO_NAME`: Repository name for the catalog itself (used for stats badge)
 
 ### Branding

docs/tag-grouping-process.md

@@ -19,8 +19,7 @@ const TAG_GROUPS = {
 - The **key** (`"canonical tag"`) is the display tag shown in the UI filter dropdown.
 - The **value array** lists every raw API tag that should be normalized to that key.
 - Raw tags not present in any array pass through unchanged and appear as-is in the UI.
-- Raw tags that contain a colon (e.g. `license:mit`, `format:parquet`) are automatically
-  filtered out as Hugging Face system metadata so they never reach the UI. This can be changed in [src/normalizeTag.js](../src/normalizeTag.js), by removing the marked option line.
+- Raw tags that contain a colon (e.g. `license:mit`, `format:parquet`) are automatically filtered out as Hugging Face system metadata so they never reach the UI. This can be changed in [src/normalizeTag.js](../src/normalizeTag.js), by removing the marked option lines in `normalizeTag` and `filterDisplayTags`.
 - Raw tags are maintained and matched-against for keyword searching and do appear in repo cards.
 
 ---