AGENTS.md - modGallery

This file provides authoritative guidance for all AI agents when working with the modGallery repository.

Repository Overview

modGallery is a comprehensive Shiny module package that provides artwork gallery display and detailed artwork information functionality for the Artalytics platform. It serves as the primary interface for viewing individual artworks, their metadata, analytics, and verification status.

Current Version

  • Package Version: 0.3.1.9000
  • Status: Active Development
  • Branch: feature/dynamic-benchmarks

Key Features

  • Artwork Gallery Display: High-resolution artwork viewing with multiple variants
  • Dynamic Benchmark Scoring: Three-category percentile-based scoring system (Time & Effort, Skill & Artistry, Complexity & Detail)
  • Metadata Management: Comprehensive artwork information and statistics
  • Verification System: Artwork authenticity verification workflows
  • Analytics Dashboard: Creation statistics and 3D visualization metrics
  • Artist Profiles: Artist information and contact functionality
  • NFT Integration: OpenSea and blockchain integration for verified works

Architecture

Module Structure

R/
├── app-ui.R                    # Main module UI (modGalleryUI)
├── app-server.R                # Main module server (modGalleryServer)
├── app-utils.R                 # Utility functions (abtn_factory, etc.)
├── mod-contactArtist.R         # Artist contact functionality
├── mod-scoreBox.R              # Dynamic benchmark scoring with gauges
├── mod-showProfile.R           # Artist profile display
├── mod-showVerify.R            # Verification status and workflow
├── mod-stats3D.R               # 3D statistics visualization
└── modGallery-package.R        # Package documentation

Key Dependencies

  • Core Artalytics: artcore, artutils
  • UI Framework: shiny, bslib, flexdashboard
  • Data Processing: data.table
  • Visualization: flexdashboard (gauges), plotly (3D charts)

Development Workflows

Quick Start

# Install dependencies
Rscript -e "pak::local_install_dev_deps(\".\")"

# Load package for development
Rscript -e "devtools::load_all()"

# Run the test app
Rscript inst/app/app.R

Testing

# Run unit tests
Rscript -e "devtools::test()"

# Run R CMD check
Rscript -e "devtools::check()"

# Test specific module
Rscript -e "shiny::runApp('inst/app')"

Building

# Build package
Rscript -e "devtools::build()"

# Install local package
Rscript -e "pak::pkg_install(\".\")"

Current Implementation Details

Dynamic Benchmark System

The scoreBox module displays three benchmark categories: - Time & Effort: Based on drawing time, drawing speed, canvas coverage - Skill & Artistry: Based on blending smoothness, brushing consistency, color range - Complexity & Detail: Based on brushing precision, brushing density, color variability

Each gauge: - Shows percentile score (0-100) - Is clickable for drill-down modal with component metrics - Uses color coding: green (71-100), yellow (36-70), red (0-35) - Displays confidence level based on portfolio size

Recent Updates

  • Fixed gauge display issues by using abtn_factory() instead of shiny::actionButton()
  • Added confidence badge to box header with tooltip
  • Implemented drill-down modals for metric details
  • Resolved button alignment issues in gallery UI
  • Integrated with artutils benchmark calculations

Environment Setup

Required Environment Variables

# Database connection
ART_DB_HOST=your_host
ART_DB_USER=your_user
ART_DB_PASSWORD=your_password
ART_DB_NAME=artprod

# CDN configuration
ART_CDN_BASE_URL=your_cdn_url

# OpenSea API (optional)
ART_OPENSEA_KEY=your_key

System Requirements

  • R >= 4.1.0
  • RStudio (recommended for development)
  • ImageMagick (for image processing)
  • Git for version control

Active TODOs and Known Issues

Pending Items

  • Package/App Unit Tests: Unit Test Files contain placeholders (See files in tests/testthat/*)
  • Review for legacy code: Confirm all assets come from CDNs, no locally stored artwork data files
  • Deployment script: Located at inst/setup-env.sh - needs implementation
  • Issue #34: AGENTS.md standardization (in progress)

Known Issues

  • Gauge rendering requires specific use of abtn_factory() wrapper
  • Confidence calculation requires minimum 1 artwork in portfolio
  • Modal dialogs need explicit easyClose = TRUE for mobile compatibility

Common Troubleshooting

Gauge Display Issues

If gauges don’t display: 1. Ensure using abtn_factory() not shiny::actionButton() 2. Check flexdashboard is properly loaded 3. Verify gauge outputs are correctly named in server

Database Connection Issues

# Test connection
artcore::testDatabaseConnection()

# Check configuration
Sys.getenv("ART_DB_HOST")

CDN Asset Loading

# Verify CDN paths
artutils::pathGalleryAsset(artist_id, artwork_id, "variant-1.png")

Integration with Main Platform

This module integrates with the main appPlatform application:

# In appPlatform
tabItem(
  tabName = "gallery",
  modGallery::modGalleryUI("gallery_module")
)

# Server integration
modGallery::modGalleryServer(
  "gallery_module",
  r = reactive_values
)

Code Standards

  • Use package::function() notation for external packages
  • Prefer |> over %>% for pipes
  • Follow tidyverse style guide
  • Document all exported functions with roxygen2
  • Use reactive expressions for data flow

Testing Guidelines

Manual Testing Checklist

Automated Tests

Located in tests/testthat/: - test-app-utils.R: Utility function tests - test-benchmarks.R: Score calculation tests - test-ui-components.R: UI rendering tests

  • Main platform: ../../CLAUDE.md
  • artutils package: ../../Core/artutils/AGENTS.md
  • Metrics documentation: ../../Sites/site-metrics/

Contact and Support

Last Updated: 2025-10-03 Maintained By: Artalytics Development Team