modUpload Agent Instructions

Package Type: Shiny UI Module (Most Complex)
Version: 0.9.1
See Also: Global guidance in D:/workspace/.agents/AGENTS.*.md
Exemplars: modGallery, modBrowse (D:/workspace/platform/app/)

This file contains requirements specific to modUpload and other Artalytics Shiny module (mod) and app (app) packages. General R package requirements are documented in the global AGENTS files.

---

Before Starting Work

1. Read global guidance files:

   • D:/workspace/.agents/AGENTS.organization.md
   • D:/workspace/.agents/AGENTS.style.coding.md
   • D:/workspace/.agents/AGENTS.style.naming.md

2. Check README.md for environment variables required.

3. Review vignettes for module context:

   • vignettes/modUpload.qmd - Overview and ecosystem
   • vignettes/processing-pipeline.qmd - Async processing patterns
   • vignettes/validation-framework.qmd - Input validation
   • vignettes/wizard-workflow.qmd - Multi-step UI design

---

System Requirements

modUpload requires 11 system libraries listed in DESCRIPTION SystemRequirements. These are automatically installed by {pak} during package installation:

• ImageMagick++ (libmagick++-dev)
• FFmpeg/libavfilter (libavfilter-dev)
• Archive (libarchive-dev)
• ExifTool (libimage-exiftool-perl)
• Tesseract OCR (libtesseract-dev, libleptonica-dev, tesseract-ocr-eng)
• Poppler PDF (libpoppler-cpp-dev, poppler-data)
• Armadillo (libarmadillo-dev)
• BLAS/LAPACK (libblas-dev, liblapack-dev)
• ARPACK (libarpack++2-dev)
• FFTW3 (libfftw3-dev)
• Image formats (libjpeg-dev, libpng-dev, libtiff5-dev)
• Fortran compiler (gfortran)

---

Shiny Module Package Requirements

These requirements apply to all mod* and app* packages:

Documentation Requirements

• Complete roxygen on all exported UI/Server functions
• Reactive parameter documentation (r parameter structure)
• Module integration examples in @examples
• Vignettes show full app integration, not isolated module usage
• README includes parent app context (appPlatform)

Module-Specific Patterns

• UI functions return shiny.tag.list
• Server functions use moduleServer()
• Namespace parameter documented with conflict prevention context
• Reactive list structure fully documented
• inst/app/app.R for isolated testing (not production deployment)

Environment Variables

• Document inherited variables with source attribution
• Never invent variable names - verify against dependency READMEs
• List in README before Quick Example

pkgdown Configuration

• Use template: package: templ.pkgdown
• Reference groups by @family tags
• Get Started vignette shows integration with parent app

---

modUpload Complexity

modUpload is the most complex module with:

• 18 exported functions across 8 categories
• ~1667 lines of R code
• Multi-step wizard UI with validation at each step
• Async processing via {future}/{promises}
• Comprehensive validation using {shinyvalidate}

Exported Function Categories

Category	Functions
Upload Core	modUploadUI, modUploadServer
UI Modules	updateProjectUI, updateProjectServer
UI Builders	new_art_modal_ui, buildAboutArtUI
Validation	validator_step_1, validator_step_2, ckfile
Pipeline	new_pipeline_task, run_pipeline
UI Helpers	button_factory, status_badge, status_class
Wizard Helpers	bslab_step_required, bxlab_step_number, bxpbar_step_progress
Utilities	wait_art_html2, image_hash_exists

---

Reactive Data Structure

The r parameter expects:

r <- reactiveValues(
  artist = "746bxxxx-...",          # Artist UUID (set by parent app)
  artwork = "99xxxxxx-...",         # Artwork UUID (managed by module)
  appdata = list(                   # From artutils::get_appdata()
    artist = list(
      info = list(artist_name, ...),
      collections = character(),    # Named vector of collection UUIDs
      artDT = data.table(...)       # All artist artworks with metadata
    )
  )
)

Key columns in artDT: - art_uuid, art_title, art_name - Artwork identification - collection_uuid, collection_name - Collection assignment - is_nft, is_print, is_verified - Status flags - brush_strokes, drawing_hours - Metrics - stop_date - Completion date

---

Environment Variables

Inherited from dependencies (verify against artcore README.md):

Database (via artcore): - ART_PGHOST, ART_PGPORT, ART_PGUSER, ART_PGPASS

CDN (via artcore): - ART_BUCKETS_KEY_ID, ART_BUCKETS_KEY_SECRET

Demo Mode (via artcore): - ART_RUNAS_DEMO - Disables write operations when TRUE

---

Key Patterns

Async Processing

Uses future::plan(future::multisession) in server initialization:

modUploadServer <- function(id, r) {
  future::plan(future::multisession)
  shiny::moduleServer(id, function(input, output, session) {
    pipeline <- new_pipeline_task()
    # ...
  })
}

Validation

Two-step validation (Step 1: required, Step 2: optional):

iv_1 <- validator_step_1()
iv_2 <- validator_step_2()

observeEvent(input$btn_submit, {
  iv_1$enable()
  if (iv_1$is_valid()) {
    # Proceed
  }
})

Demo Mode

All write operations check demo mode first:

if (artcore::is_demo()) {
  showNotification("Demo Mode: Action blocked", type = "warning")
  return(invisible(NULL))
}

---

Testing

# Run tests
devtools::test()

# Run standalone app for testing
shiny::runApp("inst/app")

# Build documentation
devtools::document()
pkgdown::build_site()

---

Modernization Pattern

This package follows the documentation modernization pattern. When updating:

1. Phase 0: Update DESCRIPTION, review exports
2. Phase 1: Enhance all roxygen documentation
3. Phase 2: Create _pkgdown.yml and vignettes
4. Phase 3: Rewrite README.md
5. Phase 4: Create/update NEWS.md
6. Phase 5: Replace AGENTS.md with this template
7. Phase 6: Run devtools::document(), devtools::check()

Study modGallery and modBrowse as exemplars.