Keywords

creativity metrics, art analytics, artalytics

AI Agent Instructions for Artalytics Website

This is the single authoritative source for all AI agent instructions when working with this repository. All other AI-specific instruction files redirect here.

Repository Overview

The Artalytics Main Website serves as the primary marketing and product showcase platform for Artalytics, the digital art analytics and authentication platform. Built with Quarto, it features responsive design, comprehensive SEO optimization, and integration with R for dynamic content generation and data visualization.

Website: https://artalytics.app

Repository Policies

CRITICAL REQUIREMENTS: - Do not commit binaries or archives over 100 MB. GitHub will reject pushes that include such files (GH001). - Do not store tool installers (e.g., Quarto tarballs) in the repository. Install them in CI using official actions or download-on-demand. - Prefer reproducible setup via GitHub Actions steps instead of vendoring installers.

Repository Structure

site-main/
├── _quarto.yml                    # Main Quarto configuration
├── _website.yml                   # Website-specific settings
├── index.qmd                      # Homepage
├── how-it-works.qmd              # Product explanation
├── metrics-overview.qmd          # Metrics documentation overview
├── _faq.qmd                      # FAQ section (included component)
├── articles/                     # Article content and resources
├── demo/                         # Product demonstration materials
├── www/                          # Static web assets
│   ├── css/                      # Stylesheets
│   │   ├── styles.css           # Main styles
│   │   ├── modals.css           # Modal styling
│   │   └── colors.css           # Color definitions
│   └── images/                  # Image assets
├── _R/                          # R scripts for content generation
├── .github/
│   └── workflows/
│       └── deploy-site.yml      # GitHub Actions deployment
├── README.md                    # Repository documentation
└── artalytics-pages.Rproj      # RStudio project file

Technology Stack

Quarto 1.6.0+: Static site generator for R/Python scientific publishing
R: Statistical computing language with packages:
- ggplot2: Data visualization
- plotly: Interactive plots
- reshape2: Data reshaping
- magick: Image processing (if needed)
Platform: Quarto Website
Theme: Cosmo (Bootstrap-based)
Deployment: GitHub Actions → Direct server deployment via SSH
Server: Apache2 on artalytics.app
GitHub Actions: CI/CD for automated building and deployment

Local Development Setup

Ubuntu/Debian Setup

# Install system R (or use r-lib/actions in CI)
sudo apt-get update -y
sudo apt-get install -y r-base r-base-dev libcurl4-openssl-dev libssl-dev libxml2-dev

# Install Quarto locally (download on demand; do NOT commit the archive)
curl -fsSL -o /tmp/quarto.tar.gz https://github.com/quarto-dev/quarto-cli/releases/download/v1.6.39/quarto-1.6.39-linux-amd64.tar.gz
sudo tar -xzf /tmp/quarto.tar.gz -C /opt
sudo ln -sf /opt/quarto-1.6.39/bin/quarto /usr/local/bin/quarto

# Install required R packages (Ubuntu method - most reliable)
sudo apt-get install -y r-cran-ggplot2 r-cran-plotly r-cran-reshape2

# Build the site
quarto render

General Setup

# Clone repository
git clone [repository-url]
cd site-main

# Install R dependencies (if using R)
Rscript -e "install.packages(c('ggplot2', 'plotly', 'reshape2'))"

# Preview site locally
quarto preview

# Open in RStudio (optional)
open artalytics-pages.Rproj

Build Process & Commands

Build Timing

⚠️ IMPORTANT: Build takes 9-12 seconds consistently. NEVER CANCEL builds before 60+ seconds as edge cases may take longer.

Development Commands

# Full build from scratch
time quarto render  # ~10 seconds

# Preview with live reload (for development)
quarto preview --port 4200 --host 0.0.0.0

# Check site configuration
quarto check

# Render specific page
quarto render index.qmd

# Render with debug output
quarto render --debug

Build outputs go to _site/ directory.

Expected Warnings

The build will produce warning messages about unresolved link targets - these are expected and do not affect functionality: - docs/index.qmd and related metrics documentation files - blog/posts/protecting-artwork.qmd (legacy reference)

Configuration Architecture

Quarto Configuration (_quarto.yml)

project:
  type: website

metadata-files:
  - _website.yml

format:
  html:
    theme: cosmo
    lightbox: true
    smooth-scroll: true
    link-external-newwindow: true
    css:
      - ./www/css/styles.css
      - ./www/css/modals.css
      - ./www/css/colors.css
    title-prefix: "Artalytics"
    description-meta: "Artalytics transforms creativity into actionable data..."

Website Configuration (_website.yml)

Extended metadata and navigation settings
Email configuration for contact forms
SEO optimization settings

CI/CD Setup (GitHub Actions)

Use official setup actions; do not vendor installers in the repo.

name: Build site
on:
  push:
    branches: [ main ]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Set up R
      - uses: r-lib/actions/setup-r@v2

      # Set up Quarto
      - uses: quarto-dev/quarto-actions/setup@v2
        with:
          version: 1.6.39

      # Install R packages (Ubuntu method recommended)
      - name: Install R packages from Ubuntu repos
        run: sudo apt-get install -y r-cran-ggplot2 r-cran-plotly r-cran-reshape2

      # Build
      - name: Render site
        run: quarto render

Deployment Pipeline

# .github/workflows/deploy-site.yml
name: Deploy-Site
on:
  push:
    branches: [main]

jobs:
  deploy:
    steps:
      - Install system dependencies
      - Setup Quarto and R
      - Install R packages
      - Render website
      - Deploy to artalytics.app
      - Reload Apache server

Content Management

Site Structure

Homepage (index.qmd): Product overview and value proposition
How It Works (how-it-works.qmd): Product functionality explanation
Metrics Overview (metrics-overview.qmd): Technical capabilities
Articles: Thought leadership and case studies
Demo: Interactive product demonstrations
FAQ: Common questions and answers

Page Structure

All pages use Quarto Markdown format:

---
title: "Page Title"
description: "Page description for SEO"
---

# Page Content

Content with R integration capabilities

Dynamic Content

R Visualizations: Generated charts and analytics
Data Integration: Real-time or processed data displays
Interactive Elements: Plotly charts and interactive components

R Integration and Data Visualization

R Script Organization

**_R/ Directory**: Centralized R scripts for content generation (NOT used during standard site builds)
Dynamic Generation: Real-time chart creation
Data Processing: Analytics and metric calculations

R Integration in Content

# Example R code block in .qmd files
#| echo: false
#| warning: false
#| fig-width: 10
#| fig-height: 6

library(ggplot2)
library(plotly)

# Create interactive visualization
p <- ggplot(data, aes(x = variable, y = value)) +
  geom_line() +
  theme_minimal()

ggplotly(p)

Visualization Capabilities

ggplot2: Static chart generation
plotly: Interactive visualizations
reshape2: Data transformation and manipulation

Styling Architecture

CSS Organization

styles.css: Main site styling and layout
modals.css: Modal dialog styling
colors.css: Color variable definitions

Design System

Primary Colors: Defined in colors.css
Typography: Responsive font sizing and hierarchy
Components: Reusable UI components and layouts
Responsive Design: Mobile-first approach
Brand Integration: Consistent with Artalytics brand guidelines

SEO and Metadata Optimization

Meta Configuration

# In _quarto.yml
title-meta: "Digital Art Analytics and Authentication Platform"
author-meta: "Bobby Fatemi, Founder at Artalytics"
description-meta: "Artalytics transforms creativity into actionable data..."
keywords: ["creativity metrics", "art analytics", "artalytics"]
image: ./www/images/png/social-card.png
image-alt: "Digital Artwork Analytics"

SEO Best Practices

Descriptive page titles with brand prefix
Meta descriptions for all pages
Open Graph and Twitter Card integration
Semantic HTML structure
Alt text for all images
Internal linking strategy

Interactive Features

Smooth Scrolling

Enhanced user experience
Smooth navigation between sections
Improved accessibility

External Link Handling

Open external links in new windows
Consistent link styling and behavior
Security considerations for external links

Testing and Validation

Manual Validation Scenarios

After any build, validate these key URLs return HTTP 200:

Homepage: http://localhost:4200/ or /_site/index.html
How it Works: http://localhost:4200/how-it-works.html
Article pages: Check content renders properly:
- Article index: http://localhost:4200/articles/
- Individual article pages under /articles/items/
- Look for proper navigation and formatting

Quick Validation Commands

# Test key pages via curl
curl -I http://localhost:4200/
curl -I http://localhost:4200/how-it-works.html  
curl -I http://localhost:4200/articles/

# Verify static files
ls -la _site/index.html
file _site/index.html  # Should show "HTML document"

# Test R packages are working
Rscript -e 'library(ggplot2); library(plotly); library(reshape2); cat("All packages loaded successfully\n")'

# Comprehensive site check
quarto check

# Test server response
ping artalytics.app

# Check deployed site
curl -I https://artalytics.app

Performance Optimization

Image Optimization

Responsive image sizing
Optimized file formats (WebP where supported)
Lightbox integration for large images
Alt text for accessibility

Code Optimization

Efficient R code execution
Quarto freeze for cached computations
Minified CSS and JavaScript
Optimized asset loading

Server Performance

Apache configuration optimization
Gzip compression
Browser caching strategies
CDN considerations

Troubleshooting Guide

Common Issues

Build fails with R package errors:

# Reinstall packages with proper dependencies (Ubuntu method - recommended)
sudo apt-get install -y libcurl4-openssl-dev libssl-dev libxml2-dev
sudo apt-get install -y r-cran-ggplot2 r-cran-plotly r-cran-reshape2

Alternative CI Setup with CRAN packages: If you need to use CRAN instead of Ubuntu repositories in GitHub Actions:

      - name: Install R packages from CRAN
        run: >
          Rscript -e 'install.packages(c("ggplot2","plotly","reshape2"),
          repos="https://cloud.r-project.org")'

Note: CRAN installation may fail due to network connectivity issues, so Ubuntu repos are recommended.

CRAN package installation fails with network errors:

# Use Ubuntu repositories instead (more reliable)
sudo apt-get install -y r-cran-ggplot2 r-cran-plotly r-cran-reshape2

# Check available R packages in Ubuntu repos
apt search r-cran-packagename

Plotly visualizations not rendering: - Check JavaScript is enabled - Verify plotly R package is properly installed - Look for console errors in browser dev tools

Port conflicts during preview:

# Use different port
quarto preview --port 4201
# Or kill existing process
pkill -f "quarto preview"

Permission errors:

# Fix permissions on project directory
sudo chown -R $USER:$USER .
chmod -R 755 .

Large file push failures (GH001):

# Remove large file and recommit
git rm --cached path/to/large/file
git commit -m "Remove large file"
# If already pushed, use git filter-repo or BFG

Deployment Failures

# Check GitHub Actions logs
# Verify SSH connectivity
ssh root@artalytics.app

# Check server permissions
ls -la /var/www/html/

# Verify Apache status
systemctl status apache2

R Integration Issues

# Check R installation
R --version

# Verify R packages
Rscript -e "library(ggplot2); library(plotly); library(reshape2)"

# Test R code execution
quarto render --execute-debug

Styling Issues

Check CSS file paths in _quarto.yml
Verify responsive design across devices
Test browser compatibility
Validate CSS syntax

Security Considerations

Deployment Security

SSH key-based deployment
Secure server configuration
HTTPS enforcement
Regular security updates

Content Security

Sanitized user inputs (if any)
Secure external link handling
Privacy protection in analytics
GDPR compliance considerations

Integration with Artalytics Ecosystem

Cross-Platform Linking

Blog: Link to blog.artalytics.info for content marketing
Metrics Guide: Reference metrics.artalytics.info for technical details (private link)
Certificates: Link to certificates.art for authentication features
Investment: Connect to investor materials at investors.artalytics.info (private link)

Brand Consistency

Unified visual identity across platforms
Consistent messaging and positioning
Coordinated content strategy
Shared asset management

Analytics and Monitoring

Performance Monitoring

Website analytics integration
Performance metric tracking
User behavior analysis
Conversion tracking

Error Monitoring

Server error tracking
JavaScript error monitoring
Uptime monitoring
Performance alerting

Maintenance and Updates

Regular Maintenance Tasks

Content Updates: Product features, pricing, testimonials
Technical Updates: Quarto, R, and dependency updates
Security Updates: Server and application security patches
Performance Reviews: Site speed and optimization audits

Content Review Cycle

Monthly content accuracy reviews
Quarterly strategic content updates
Annual comprehensive site audit
Ongoing SEO optimization

Best Practices

Content Development

Write clear, engaging copy focused on user benefits
Use consistent tone and voice across all pages
Include relevant keywords naturally
Structure content with proper headings
Test all interactive elements

Technical Development

Follow Quarto best practices for configuration
Use semantic HTML structure
Implement proper error handling
Test thoroughly before deployment
Monitor performance continuously

Collaboration

Use clear commit messages
Document significant changes
Coordinate with other Artalytics properties
Maintain consistent brand messaging
Regular stakeholder reviews

Important Notes

Large binaries policy: Files over 100 MB will cause pushes to fail. If you accidentally add such a file, remove it (git rm –cached path && git commit) and rewrite history if it reached remote (use git filter-repo or BFG).
Use .gitignore entries to prevent committing installers and large archives.
Build times are consistent at ~10 seconds - allow adequate timeout in CI/CD (recommend 60+ seconds)
Expected warning messages during build about missing docs/ and blog/ references are normal and do not affect functionality
Ubuntu R package repositories are more reliable than CRAN for this environment
The _R/ directory contains utility scripts that are NOT used during standard site builds

System Requirements

Quarto: Version 1.6.0+
R: Latest version
R Packages: ggplot2, plotly, reshape2
System Dependencies: libcurl4-openssl-dev, libssl-dev, libxml2-dev