cultureat-bak/.claude/CLAUDE.md

CLAUDE.md - CCAT Project Guide

🚨 CRITICAL WORKFLOW REQUIREMENTS

Before Starting ANY Work Session:

1. ALWAYS read PLANNING.md - Contains current project status, decisions, and context
2. Check TASKS.md - Review all pending tasks and their priorities
3. Mark completed tasks immediately - Update task status as you complete work
4. Add newly discovered tasks - Document any new tasks you identify during work

Task Management Protocol:

• Update TASKS.md with progress and completion status
• Add context and notes for future sessions
• Prioritize tasks based on current project phase
• Document dependencies and blockers

---

Project Overview

CCAT Website - Digital platform for Conseil de la culture de l'Abitibi-Témiscamingue

A comprehensive cultural community platform using WordPress as both backend CMS and theme container, with Nuxt 4 integrated as a custom theme providing the frontend experience.

Key Objectives

• Centralize cultural information and events for the Abitibi-Témiscamingue region
• Provide platform for artists and cultural organizations
• Enable event management and subscription capabilities
• Foster community engagement through membership features
• Streamline administrative tasks for CCAT staff

---

Architecture Overview

WordPress Theme Integration

• Nuxt-in-WordPress: Nuxt 4 runs within WordPress theme context
• Hybrid Rendering: PHP handles WordPress logic, Nuxt handles frontend
• Composer Dependencies: Plugin management via WPackagist / private repository
• ACF Integration: Deep integration with ACF + ACF Extended Pro
• Content Preview: SSR-based preview system via iframe

Tech Stack

WordPress Theme Structure

• WordPress: CMS + Custom theme containing Nuxt 4
• Plugins: Managed via Composer + WPackagist
• Theme Structure: Combines PHP logic with Nuxt 4 frontend
• Directory Layout: app/ server/ shared/ (Nuxt) + acf-json/ includes/ (WordPress)

Frontend (Nuxt 4 in WordPress Theme)

• Framework: Nuxt 4 (embedded in WordPress theme)
• UI: Nuxt UI components + custom UI components
• GraphQL: Nuxt GraphQL middleware (client)
• Auth: JWT authentication for WPGraphQL
• Deployment: Gitea Actions (push-to-deploy)
• Images: @nuxt/image optimization
• Maps: Leaflet for interactive maps

Backend & Integrations

• CMS: WordPress with WPGraphQL + JWT Authentication
• Custom Fields: Advanced Custom Fields (ACF) + ACF Extended Pro
• Content: ACF Flexible Fields for dynamic layouts
• Email: Mailchimp (likely PHP integration)
• Payments: Stripe (likely PHP integration)
• Import: AirTable (non-destructive)
• Preview: ACF Extended Pro content preview via iframe/SSR

---

Content Structure

Custom Post Types (CPT)

Contributor    - Artist / organization profiles
Event          - Base event descriptions  
Listing        - Job offers/proposals (with deadlines)
Location       - Venue information
Profile        - User cultural profiles
Project        - CCAT projects
Representation - Event instances (when/where)
Resource       - Document/link repository
Template       - Reusable ACF content blocks

Taxonomies

Discipline         - Artistic/cultural categories
Listing Category   - Job/proposal types
Project Category   - CCAT project types
Resource Category  - Resource organization
Post Category      - Standard WordPress

User System

• Authentication: JWT tokens via WPGraphQL
• Free Membership: Basic profile + content management
• Premium Membership: Enhanced features (likely PHP Stripe integration)
• Admin Roles: Full content + user management + impersonation
• Member Zones: Protected areas for account and profiles management

Event System

• Event CPT: Base event info (no dates)
• Representation CPT: Specific event instances (date/location)
• Location CPT: Venue information (hierarchical as Venue / Room)
• Contributor CPT: People involved with the event (performers, organizers, etc)
• Subscriptions: Free/paid registration with bulk options
• Calendar: Interactive display with filtering

---

Code Organization

WordPress Theme Directory Structure

wp-content/themes/ccat/
├── acf-json/              # ACF field group definitions
├── app/                    # Nuxt 4 app directory
│   ├── assets/
│   │   ├── css/           # Styles
│   │   └── svg/           # Custom icons and vector images
│   ├── components/
│   │   ├── auth/          # Authentication components
│   │   ├── nodes/         # Main page components per CPT
│   │   ├── sections/      # Flexible content layouts
│   │   ├── site/          # Header, footer, navigation
│   │   └── ui/            # Custom UI components
│   ├── composables/
│   │   ├── useAuth.js         # JWT authentication & tokens
│   │   ├── useMemberArea.js   # Member zone functionality
│   │   ├── useMemberSignup.js # Registration flows
│   │   ├── useNodeByUri.js    # Content fetching by URI
│   │   ├── useResponsive.js   # Responsive utilities
│   │   └── useSiteOptions.js  # ACF options page data
│   ├── graphql/           # GraphQL operations (*.gql)
│   ├── layouts/           # Nuxt layouts
│   ├── middleware/        # Nuxt middlewares
│   ├── pages/             # Nuxt pages
│   └── plugins/
├── includes/        # PHP functions and classes
│   ├── core/        # Core theme features
│   ├── cpt/         # Custom post types
│   ├── graphql/     # Custom WPGraphQL types, queries and mutations
│   ├── taxonomies/  # Custom taxonomies
│   └── vendors/     # 3rd party integrations
├── languages/             # WordPress theme translations
├── layouts/               # ACF Extended PRO templates (for content preview)
├── public/                # Nuxt 4 public directory
├── server/        # Nuxt 4 server directory
│   ├── api/       # API endpoints
│   ├── graphql/   # Server side GraphQL operations
│   └── utils/     # Auto-imported server utils
├── shared/        # Shared utilities/types
│   ├── types/     # Shared types
│   └── utils/     # Auto-imported shared utils
├── functions.php          # WordPress theme functions
└── style.css              # WordPress theme header

Component Architecture

• Nodes: Main page components mapped to CPT types
• Sections: Flexible content layout components for ACF fields
• Auth: Authentication flows and protected content
• Site: Global site components (header, footer, nav)
• UI: Reusable custom UI components

---

Development Guidelines

WordPress Theme Development

• Theme Structure: Follow Nuxt 4 directory conventions within WordPress theme
• PHP Integration: Handle WordPress-specific logic, authentication, integrations
• Composer: Manage plugins via composer.json and WPackagist
• ACF Configuration: Store field groups in acf-json/ for version control
• Custom Functions: Organize PHP logic in includes/ directory

Nuxt 4 (Within WordPress Theme)

• Use Nuxt UI components + custom UI components
• Implement SSR for SEO optimization and content preview
• Use Nuxt GraphQL middleware for all API calls
• JWT token management and refresh handling
• Mobile-first responsive design
• Leverage @nuxt/image for all media
• Follow accessibility standards (WCAG 2.1 AA)

---

Key Features Implementation

Member Management

• JWT-based registration/login with email verification
• Token refresh and session management
• Profile creation/editing (linked to Profile CPT)
• Premium membership upgrades (likely via PHP/Stripe)
• Content creation permissions based on membership
• Admin impersonation for user support

Event Management

• Calendar view with Leaflet map integration
• Event subscription forms (free/paid via Stripe)
• Bulk attendee registration for admins
• Email confirmations via Mailchimp
• Admin tools for subscription management

Content Management & Preview

• ACF Flexible Fields for dynamic content sections
• Template CPT for reusable content blocks
• ACF Extended Pro preview system (iframe + SSR)
• Image uploads with point-of-interest cropping
• Automated URL redirects on slug changes
• Virtual pages (redirect to first child)
• Real-time content preview during editing

Admin Tools

• User management and moderation
• User impersonation for support purposes
• Event approval workflows
• Subscription monitoring
• Content import from AirTable
• Event webscraping configuration

Integrations (Likely PHP-based)

• Mailchimp: User sync, newsletters, transactional emails (PHP API)
• Stripe: Payment processing, subscription billing (PHP SDK)
• AirTable: Import existing content non-destructively
• Webscraping: Automated event discovery from external sources

---

Development Patterns & Solutions

WordPress Theme Integration

• Use WordPress hooks and filters for theme integration
• Leverage ACF Extended Pro for enhanced field management
• Implement content preview via SSR iframe system
• Handle both PHP logic and Nuxt rendering in single theme

GraphQL & Authentication

• Use Nuxt GraphQL middleware for all API calls
• Implement JWT token storage and refresh logic
• Handle authentication state across SSR/client
• Implement proper error handling for expired tokens
• Admin impersonation with separate token management

Content Preview System

• ACF Extended Pro iframe preview integration
• SSR rendering for preview content via Nuxt server
• Real-time preview updates during content editing
• Flexible content section rendering in isolation

State Management

• Use Nuxt's built-in state management
• Implement JWT token persistence and refresh
• Handle impersonation state for admins
• Site options management via useSiteOptions

Form Handling & Payments (PHP Integration)

• Use Nuxt UI form components on frontend
• Handle form submissions via WordPress/PHP backend
• Mailchimp API integration in PHP for email management
• Stripe SDK integration in PHP for payment processing
• Webhook handling for payment events in PHP

---

Implementation Timeline

Phase 1: Foundation

1. WordPress theme setup with Nuxt 4 integration
2. Composer configuration for plugin management
3. WPGraphQL + JWT Authentication setup
4. Core CPT structure with ACF field groups
5. Basic Nuxt components (auth, nodes, sections)
6. ACF Extended Pro preview system

Phase 2: Core Features

1. Member registration/profile management (useAuth, useMemberArea)
2. Event calendar with Leaflet maps
3. Flexible content sections with preview
4. Node-based page components per CPT
5. Site-wide components (header, footer, navigation)
6. Mailchimp integration (PHP)

Phase 3: Advanced Features

1. Stripe payment integration (PHP)
2. Event subscription system
3. Premium membership features
4. Admin impersonation functionality
5. Advanced admin tools
6. AirTable import system

Phase 4: Enhancement & Launch

1. Webscraping tool implementation
2. Performance optimization
3. Advanced search/filtering
4. Analytics integration
5. Final testing and launch preparation

---

Technical Requirements

Performance Considerations

• Optimize GraphQL queries (avoid N+1)
• Implement proper caching strategies
• Use @nuxt/image for all media optimization
• WordPress theme performance optimization
• ACF Extended Pro preview performance
• PHP integration efficiency (Mailchimp, Stripe)
• Monitor Core Web Vitals

Security Requirements

• Sanitize all GraphQL inputs
• WordPress security best practices
• Implement proper CORS policies
• Use JWT tokens for authentication
• Secure PHP integrations (Mailchimp, Stripe APIs)
• Validate payment webhooks in PHP
• ACF Extended Pro security considerations
• Regular security updates for WordPress and plugins

Testing Strategy

• Unit tests for utilities and composables
• Integration tests for GraphQL operations
• WordPress/PHP integration testing
• E2E tests for critical user flows
• Payment testing with Stripe test mode (PHP)
• Email testing with Mailchimp sandbox (PHP)
• Content preview functionality testing

---

Deployment & Environment

Deployment Notes

• WordPress theme with integrated Nuxt 4 frontend
• Plugin management via Composer + WPackagist
• CI/CD: Push-to-deploy via Gitea Actions
• Database: Optimized for GraphQL queries
• Assets: @nuxt/image handles optimization
• ACF field groups versioned in acf-json/
• SSL/TLS required for all environments
• JWT tokens for secure API communication

Environment Variables

# WordPress/Nuxt Integration
NUXT_GRAPHQL_ENDPOINT=     # WordPress GraphQL endpoint
NUXT_SESSION_PASSWORD=     # JWT authentication secret
NUXT_HUB_PROJECT_KEY=      # NuxtHub project reference

# Third-party Services (likely PHP env vars)
MAILCHIMP_API_KEY=       # Mailchimp integration
STRIPE_SECRET_KEY=       # Stripe payments
STRIPE_PUBLISHABLE_KEY=  # Stripe public key
AIRTABLE_API_KEY=        # AirTable import key

Useful Commands

# Development
npm run dev             # Start Nuxt dev server (within WordPress theme)
npm run build:typecheck # Check for TypeScript errors
npm run build           # Build for production
composer install        # Install WordPress plugins
git push origin main    # Deploy via Gitea Actions

# WordPress
composer update      # Update plugin dependencies

---

Resources & Documentation

Core Technologies

• Nuxt 4 Documentation
• Nuxt GraphQL Middleware
• WordPress Theme Development
• WPGraphQL Docs
• WPGraphQL JWT Authentication

Content & Fields

• ACF Documentation
• ACF Extended Pro
• Composer + WPackagist

Integrations

• Stripe PHP SDK
• Mailchimp API PHP
• Leaflet Documentation

Deployment

• Gitea Actions

---

Remember: This is a WordPress theme containing Nuxt 4, not a separate frontend. The integration between WordPress/PHP and Nuxt is key to the architecture. Prioritize user experience, accessibility, and community engagement in all development decisions.