Skip to contents

Get Started with artcore

Source: vignettes/artcore.Rmd
artcore.Rmd

The artcore package provides the foundation tools for the Artalytics platform, including database connectivity, CDN asset management, UUID generation, and environment validation.

Installation

Install artcore from GitHub:

# install.packages("pak")
pak::pak("artalytics/artcore")

Environment Setup

Before using artcore functions, configure the required environment variables. The package validates these at runtime and provides clear error messages when they’re missing.

Database Connection 

Sys.setenv(
 ART_PGHOST = "your-postgres-host",
 ART_PGPORT = "5432",
 ART_PGUSER = "your-username",
 ART_PGPASS = "your-password",
 ART_PGDATA = "your-database"
)

CDN Access (DigitalOcean Spaces) 

Sys.setenv(
  ART_BUCKETS_KEY_ID = "your-spaces-key-id",
  ART_BUCKETS_KEY_SECRET = "your-spaces-secret"
)

Application Mode 

# Enable demo mode (writes are ignored)
Sys.setenv(ART_RUNAS_DEMO = "TRUE")

Core Functions

Database Operations

Connect to and disconnect from the PostgreSQL database:

library(artcore)

# Open a database connection
con <- ..dbc()

# Run your queries
# result <- DBI::dbGetQuery(con, "SELECT * FROM artists LIMIT 10")

# Always close the connection when done
..dbd(con)

CDN Asset Management

Check if assets exist and construct URLs:

# Check if an object exists in a bucket
has_object("art-public", "artist-id/artwork-id/thumbnail.jpg")

# Get a public URL for an asset
cdn_asset_url("art-public", "artist-id/artwork-id/thumbnail.jpg")

# Get a signed (presigned) URL for private assets
cdn_asset_url("art-vault", "artist-id/artwork-id/original.png", signed = TRUE)

# List all keys under a prefix
keys <- cdn_list_keys("art-data", "artist-id/artwork-id/")

UUID Generation

Generate platform-specific UUIDs with recognizable prefixes:

# Generate a new artist ID (prefix: 88)
artist_id <- genArtistID()
# Example: "88xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Generate a new artwork ID (prefix: 99)
artwork_id <- genArtworkID()
# Example: "99xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Generate a new collection ID (prefix: 77)
collection_id <- genCollectionID()
# Example: "77xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Generate test IDs (for development)
test_artist <- genArtistID(test = TRUE)
# Returns UUID starting with: "80000000-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Environment Validation

Validate that required environment variables are set:

# Check database variables
check_env_dba()

# Check CDN variables
check_env_cdn()

# Check API keys
check_env_api()

# Check application mode
check_env_app()

Each function throws an informative error if required variables are missing.

Utility Functions 

# Check if running in demo mode
if (is_demo()) {
  message("Running in demo mode - writes will be ignored")
}

# Format large numbers for display
format_brushes(1500)
# Returns: "1.5K+"

# Calculate percentile ranking
scores <- c(10, 20, 30, 40, 50)
calc_percentile(35, scores)
# Returns the percentile of 35 within the scores vector

Next Steps

  • See the Reference for complete function documentation
  • Review environment variable requirements in the package README
  • Check out the AGENTS.md file for development guidelines