generated from pascalmartineau/wp-skeleton
399 lines
14 KiB
Markdown
399 lines
14 KiB
Markdown
# 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
|
|
```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. |