pascalmartineau/cultureat-bak
4
0
Fork 0
generated from pascalmartineau/wp-skeleton
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: Update CLAUDE / PLANNING / TASKS

Browse Source
This commit is contained in:
Pascal Martineau
2025-09-25 09:30:16 -04:00
parent 4c41ff2dae
commit b12f1fc2a2
3 changed files with 1064 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

433
.claude/CLAUDE.md
View File

@@ -1,58 +1,399 @@
# CLAUDE.md
# CLAUDE.md - CCAT Project Guide
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## 🚨 CRITICAL WORKFLOW REQUIREMENTS
## Overview
### 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
This is a WordPress site for Conseil de la culture de l'Abitibi-Témiscamingue with a hybrid architecture combining WordPress backend with a Nuxt.js frontend application. The site uses GraphQL for data communication between WordPress and Nuxt.js.
### 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
## Development Commands
---
### WordPress/PHP
- **Lint PHP code**: `./vendor/bin/phpcs` (uses WordPress coding standards via phpcs.xml)
- **Install PHP dependencies**: `composer install`
## Project Overview
### Nuxt.js Frontend (in wp-content/themes/ccat/)
- **Development server**: `pnpm dev:nuxt` (runs on host with --host flag)
- **Build**: `pnpm build` (runs typecheck then nuxt build sequentially)
- **Type checking**: `pnpm build:typecheck`
- **Lint**: `pnpm lint` (ESLint with auto-fix)
- **Deploy**: `pnpm deploy` (NuxtHub deployment)
- **Preview**: `pnpm preview` (NuxtHub preview)
**CCAT Website** - Digital platform for Conseil de la culture de l'Abitibi-Témiscamingue
## Architecture
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.
### WordPress Backend
- **Location**: Root directory contains standard WordPress installation
- **Custom Post Types**: membership, contributor, event, location, project, representation, resource, template (wp-content/themes/ccat/includes/cpt/)
- **Custom Taxonomies**: discipline, project-category, resource-category (wp-content/themes/ccat/includes/taxonomies/)
- **GraphQL**: Enabled via WP GraphQL plugin with JWT authentication
- **ACF Integration**: Advanced Custom Fields Pro with Extended Pro for custom fields
### 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
### Nuxt.js Frontend
- **Location**: wp-content/themes/ccat/ (acts as WordPress theme but contains Nuxt app)
- **Framework**: Nuxt 4.x with Vue 3, TypeScript
- **UI**: Nuxt UI 4.0 alpha with TailwindCSS
- **GraphQL**: Connects to WordPress GraphQL endpoint via nuxt-graphql-middleware
- **Deployment**: Cloudflare Workers via NuxtHub
- **Package Manager**: pnpm with specific built dependencies configuration
---
### Key Dependencies
- **WordPress Plugins**: WP GraphQL, ACF Pro, iThemes Security Pro, Clean Image Filenames
- **Nuxt Modules**: @nuxt/ui, @nuxthub/core, nuxt-auth-utils, nuxt-graphql-middleware, @nuxtjs/sitemap
## Architecture Overview
## File Structure
- `/wp-content/themes/ccat/app/` - Nuxt application files
- `/wp-content/themes/ccat/server/` - Server-side GraphQL schema and API routes
- `/wp-content/themes/ccat/includes/` - WordPress theme functions (CPT, taxonomies, ACF)
- `/wp-content/themes/ccat/acf-json/` - ACF field group definitions
- `/wp-content/mu-plugins/` - Must-use plugins (currently only headless-home-url.php)
### 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
## Development Notes
- Site is configured as non-indexable (indexable: false in nuxt.config.ts)
- GraphQL endpoint: https://wp.cultureat.ca/graphql
- Frontend URL: https://cultureat.ca
- Uses Cloudflare Workers for hosting the Nuxt frontend
- WordPress serves as headless CMS with custom post types for cultural content management
- GraphQL operations should be in the same directory where they are used
- WordPress filters and actions hooks should use named functions prefixed with ccat_ defined the line after add_action / add_filter
### 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.