# CLAUDE.md - CCAT Project Guide

## 🚨 CRITICAL WORKFLOW REQUIREMENTS

### Before Starting ANY Work Session:
1. **ALWAYS read `.claude/PLANNING.md`** - Contains current project status, decisions, and context
2. **Check `.claude/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 `.claude/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
```bash
# 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](https://nuxt.com/)
- [Nuxt GraphQL Middleware](https://nuxt.com/modules/graphql-middleware)
- [WordPress Theme Development](https://developer.wordpress.org/themes/)
- [WPGraphQL Docs](https://www.wpgraphql.com/)
- [WPGraphQL JWT Authentication](https://github.com/wp-graphql/wp-graphql-jwt-authentication)

### Content & Fields
- [ACF Documentation](https://www.advancedcustomfields.com/)
- [ACF Extended Pro](https://www.acf-extended.com/)
- [Composer + WPackagist](https://wpackagist.org/)

### Integrations
- [Stripe PHP SDK](https://github.com/stripe/stripe-php)
- [Mailchimp API PHP](https://mailchimp.com/developer/marketing/docs/fundamentals/)
- [Leaflet Documentation](https://leafletjs.com/)

### Deployment
- [Gitea Actions](https://docs.gitea.io/en-us/usage/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.