From b12f1fc2a259781bbd17a16555831eac1caf7c54 Mon Sep 17 00:00:00 2001 From: Pascal Martineau Date: Thu, 25 Sep 2025 09:30:16 -0400 Subject: [PATCH] chore: Update CLAUDE / PLANNING / TASKS --- .claude/CLAUDE.md | 433 +++++++++++++++++++++++++++++++++++++++----- .claude/PLANNING.md | 307 +++++++++++++++++++++++++++++++ .claude/TASKS.md | 370 +++++++++++++++++++++++++++++++++++++ 3 files changed, 1064 insertions(+), 46 deletions(-) create mode 100644 .claude/PLANNING.md create mode 100644 .claude/TASKS.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 529c002..43b3c8d 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -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 \ No newline at end of file +### 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. \ No newline at end of file diff --git a/.claude/PLANNING.md b/.claude/PLANNING.md new file mode 100644 index 0000000..987003c --- /dev/null +++ b/.claude/PLANNING.md @@ -0,0 +1,307 @@ +# PLANNING.md - CCAT Project Planning Document + +## 🎯 Project Vision + +### Mission Statement +Create a comprehensive digital platform that serves as the central hub for the cultural community of Abitibi-TΓ©miscamingue, connecting artists, organizations, and cultural enthusiasts while promoting regional cultural activities and fostering community engagement. + +### Core Values +- **Community First**: Every feature should strengthen connections within the cultural community +- **Accessibility**: Platform must be accessible to all users regardless of technical expertise +- **Cultural Promotion**: Showcase and celebrate the rich cultural diversity of the region +- **User Empowerment**: Enable artists and organizations to manage their own content +- **Transparency**: Open and clear communication about events, opportunities, and resources + +### Success Metrics +- **Community Growth**: Increase in registered cultural profiles and active members +- **Event Engagement**: Higher attendance and participation in cultural events +- **Content Creation**: Volume and quality of user-generated cultural content +- **Regional Impact**: Measurable increase in cultural activity awareness and participation +- **User Satisfaction**: Positive feedback and continued platform usage + +--- + +## πŸ—οΈ Architecture Overview + +### System Architecture Philosophy +**Hybrid WordPress-Nuxt Integration**: A WordPress theme that embeds Nuxt 4, combining the content management power of WordPress with the modern frontend capabilities of Nuxt. + +### Architecture Principles +- **Content-First Design**: WordPress CMS handles all content management +- **Modern Frontend Experience**: Nuxt 4 provides fast, interactive user interface +- **API-Driven**: GraphQL API layer separates content from presentation +- **Progressive Enhancement**: Core functionality works without JavaScript +- **Mobile-First**: Responsive design prioritizing mobile experience +- **Performance Optimized**: Fast loading times and efficient resource usage + +### Data Flow Architecture +``` +User Request β†’ WordPress (PHP) β†’ WPGraphQL β†’ Nuxt Frontend β†’ User Interface + ↓ ↑ +WordPress Admin ← ACF Fields ← Content Management ← User Actions + ↓ +Third-party Integrations (Mailchimp, Stripe, AirTable) +``` + +### Content Architecture +- **Hierarchical Structure**: Organized content types with clear relationships +- **Flexible Content**: ACF flexible fields for dynamic page layouts +- **Reusable Components**: Template CPT for consistent content blocks +- **User-Generated Content**: Community members can create and manage profiles +- **Administrative Control**: Staff can moderate and approve content + +--- + +## πŸ’» Technology Stack + +### Core Platform +| Component | Technology | Version | Purpose | +|-----------|------------|---------|---------| +| **CMS** | WordPress | Latest | Content management system | +| **Frontend** | Nuxt | 4.x | Modern Vue.js framework | +| **UI Framework** | Nuxt UI | Latest | Component library | +| **Database** | MySQL | 8.0+ | Data storage | +| **Language** | PHP | 8.1+ | WordPress backend | +| **Language** | JavaScript/TypeScript | ES2022+ | Frontend development | + +### WordPress Plugins & Extensions +| Plugin | Purpose | License | +|--------|---------|---------| +| **WPGraphQL** | GraphQL API layer | Free | +| **WPGraphQL JWT Authentication** | API authentication | Free | +| **Advanced Custom Fields Pro** | Custom field management | Commercial | +| **ACF Extended Pro** | Enhanced ACF features + preview | Commercial | + +### Frontend Technologies +| Technology | Purpose | Integration | +|------------|---------|-------------| +| **Vue 3** | Component framework | Via Nuxt 4 | +| **Nuxt UI** | UI component library | Primary UI framework | +| **@nuxt/image** | Image optimization | Asset handling | +| **Nuxt GraphQL Middleware** | GraphQL client | API communication | +| **Leaflet** | Interactive maps | Event locations | + +### Third-Party Integrations +| Service | Purpose | Implementation | +|---------|---------|----------------| +| **Mailchimp** | Email marketing & transactional emails | PHP SDK | +| **Stripe** | Payment processing | PHP SDK | +| **AirTable** | Data import system | API integration | + +### Development Tools +| Tool | Purpose | Usage | +|------|---------|-------| +| **Composer** | PHP dependency management | Plugin management via WPackagist | +| **npm/pnpm** | Node.js package management | Frontend dependencies | +| **Gitea Actions** | CI/CD pipeline | Automated deployment | +| **TypeScript** | Type safety | Frontend development | + +--- + +## πŸ› οΈ Required Tools & Environment + +### Development Environment Requirements + +#### Local Development Setup +- **PHP**: Version 8.1 or higher +- **Node.js**: Version 18 or higher +- **MySQL**: Version 8.0 or higher +- **Composer**: Latest version for PHP dependencies +- **npm/pnpm**: For JavaScript package management + +#### WordPress Development Tools +- **WordPress**: Latest version +- **WP-CLI**: WordPress command line interface +- **Local development environment**: (LocalWP, XAMPP, Docker, or similar) + +#### Frontend Development Tools +- **Code Editor**: VS Code recommended with extensions: + - Vue Language Features (Volar) + - TypeScript Vue Plugin (Volar) + - GraphQL extension + - PHP extension +- **Browser Developer Tools**: Chrome/Firefox DevTools +- **GraphQL Playground**: For API testing + +### Production Environment Requirements + +#### Hosting Requirements +- **PHP**: 8.1+ with required extensions +- **MySQL/MariaDB**: 8.0+ or 10.6+ +- **Web Server**: Apache 2.4+ or Nginx 1.20+ +- **SSL Certificate**: Required for secure authentication +- **Memory**: Minimum 512MB PHP memory limit +- **Storage**: SSD recommended for performance + +#### Performance Requirements +- **CDN**: Not required initially (@nuxt/image handles optimization) +- **Caching**: WordPress object caching recommended +- **Backup System**: Automated daily backups +- **Monitoring**: Server and application monitoring + +### Development Workflow Tools + +#### Version Control +- **Git**: Version control system +- **Gitea**: Self-hosted Git service with Actions +- **Git Flow**: Branching strategy for organized development + +#### Project Management +- **TASKS.md**: Task tracking using markdown checkboxes +- **PLANNING.md**: This document for project planning +- **CLAUDE.md**: Development guide for AI assistance + +#### Testing Tools +- **Vitest**: Unit testing for frontend +- **PHPUnit**: Unit testing for WordPress/PHP +- **Playwright**: End-to-end testing +- **GraphQL testing tools**: For API validation + +--- + +## πŸ“‹ Development Phases & Milestones + +### Phase 1: Foundation (Months 1-3) +**Goal**: Establish core architecture and basic functionality +- WordPress theme with Nuxt 4 integration +- Authentication system with JWT +- Content structure (CPTs, taxonomies, ACF fields) +- Basic GraphQL API functionality + +### Phase 2: Core Features (Months 4-6) +**Goal**: Implement primary user-facing features +- Member registration and profile management +- Event system with calendar integration +- Content management with flexible layouts +- Site navigation and global components + +### Phase 3: Advanced Features (Months 7-9) +**Goal**: Add premium features and integrations +- Payment processing (Stripe integration) +- Email marketing (Mailchimp integration) +- Event subscription system +- Admin tools and user impersonation + +### Phase 4: Enhancement & Launch (Months 10-12) +**Goal**: Polish, optimize, and prepare for production +- Performance optimization +- Security audit and testing +- Content import from existing systems +- User training and documentation + +--- + +## 🎨 User Experience Strategy + +### Target User Groups +1. **Cultural Artists**: Individual artists showcasing work and finding opportunities +2. **Cultural Organizations**: Groups promoting events and managing memberships +3. **Community Members**: Residents interested in cultural activities +4. **CCAT Staff**: Administrators managing the platform and content +5. **Event Organizers**: People creating and promoting cultural events + +### User Journey Design +- **Discovery**: Easy browsing of events and cultural profiles +- **Engagement**: Simple registration and profile creation +- **Participation**: Event subscription and community interaction +- **Contribution**: Content creation and profile management +- **Administration**: Streamlined content moderation and user management + +### Accessibility Commitments +- **WCAG 2.1 AA Compliance**: Meet accessibility standards +- **Mobile-First Design**: Optimal experience on all devices +- **Performance**: Fast loading times even on slow connections +- **Multilingual Support**: Prepared for French/English localization +- **Inclusive Design**: Consider diverse user needs and abilities + +--- + +## πŸ” Security & Privacy Considerations + +### Data Protection +- **GDPR Compliance**: Handle personal data responsibly +- **User Consent**: Clear opt-ins for email and data collection +- **Data Minimization**: Collect only necessary information +- **Right to Deletion**: Allow users to delete their accounts + +### Security Measures +- **Authentication**: JWT tokens with proper expiration +- **Authorization**: Role-based access control +- **Input Validation**: Sanitize all user inputs +- **API Security**: Rate limiting and proper error handling +- **Regular Updates**: Keep all plugins and core systems updated + +### Privacy Features +- **Profile Visibility**: User control over profile information +- **Email Preferences**: Granular email subscription controls +- **Content Ownership**: Clear guidelines for user-generated content +- **Admin Transparency**: Clear communication about moderation policies + +--- + +## πŸ“Š Analytics & Success Measurement + +### Key Performance Indicators (KPIs) +- **User Engagement**: Active users, session duration, page views +- **Content Creation**: Number of profiles, events, and user posts +- **Event Participation**: Event views, subscriptions, and attendance +- **Community Growth**: New registrations and profile completions +- **Technical Performance**: Page load times, uptime, error rates + +### Analytics Implementation +- **Privacy-Focused**: Use privacy-respecting analytics tools +- **User Behavior**: Track user flows and feature usage +- **Performance Monitoring**: Real-time application performance +- **Content Analytics**: Most popular content and search terms + +--- + +## πŸš€ Launch Strategy + +### Pre-Launch Preparation +- **Content Migration**: Import existing cultural data +- **User Training**: Staff and power user training sessions +- **Beta Testing**: Limited release to core community members +- **Documentation**: Complete user and admin guides +- **Marketing Materials**: Prepare launch communications + +### Launch Phases +1. **Soft Launch**: Limited user base, gather feedback +2. **Community Launch**: Open to cultural organizations +3. **Public Launch**: Full public availability +4. **Post-Launch**: Monitor, support, and iterate + +### Success Criteria for Launch +- **Technical Stability**: No critical bugs or performance issues +- **User Adoption**: Target number of registered profiles +- **Content Quality**: Sufficient content for engaging experience +- **User Satisfaction**: Positive feedback from beta users +- **Admin Readiness**: Staff comfortable with platform management + +--- + +## πŸ“ˆ Future Roadmap + +### Post-Launch Enhancements (Year 1) +- **Mobile App**: Native iOS/Android applications +- **Advanced Search**: Enhanced filtering and search capabilities +- **Social Features**: User-to-user messaging and networking +- **API Expansion**: Public API for third-party integrations +- **Analytics Dashboard**: Advanced reporting for admins + +### Long-Term Vision (Years 2-3) +- **Regional Integration**: Connect with other cultural councils +- **E-commerce**: Ticket sales and merchandise integration +- **Virtual Events**: Live streaming and virtual event hosting +- **AI Features**: Content recommendations and smart matching +- **Multilingual**: Full French/English bilingual support + +--- + +**Document Status**: Living document, updated regularly +**Last Updated**: Project initiation +**Next Review**: End of Phase 1 + +--- + +*This planning document serves as the north star for the CCAT project. All development decisions should align with the vision and principles outlined here.* \ No newline at end of file diff --git a/.claude/TASKS.md b/.claude/TASKS.md new file mode 100644 index 0000000..e76daad --- /dev/null +++ b/.claude/TASKS.md @@ -0,0 +1,370 @@ +# TASKS.md - CCAT Project Task Management + +## Task Status Instructions +Use GitHub-style checkboxes to mark task completion: +- `- [ ]` for uncompleted tasks +- `- [x]` for completed tasks +- Add notes or comments after tasks using `` + +--- + +## Milestone 1: Foundation & Setup + +### WordPress Theme Structure +- [ ] Create basic WordPress theme structure with `functions.php` and `style.css` +- [ ] Set up `composer.json` with WPackagist dependencies +- [ ] Create directory structure (`acf-json/`, `includes/`, `app/`, `server/`, `shared/`) +- [ ] Configure Nuxt 4 within WordPress theme context +- [ ] Set up basic theme activation and WordPress integration + +### Development Environment +- [ ] Configure Gitea Actions for CI/CD pipeline +- [ ] Set up local development environment +- [ ] Configure environment variables for development/production +- [ ] Set up hot reloading for Nuxt within WordPress theme +- [ ] Create basic build scripts and deployment configuration + +### Core Plugins & Dependencies +- [ ] Install and configure WPGraphQL plugin +- [ ] Install and configure WPGraphQL JWT Authentication +- [ ] Install and configure Advanced Custom Fields (ACF) Pro +- [ ] Install and configure ACF Extended Pro +- [ ] Configure GraphQL schema and test basic queries + +--- + +## Milestone 2: Content Structure & Data Models + +### Custom Post Types (CPT) +- [ ] Create Contributor CPT (artist/organization profiles) +- [ ] Create Event CPT (base event descriptions) +- [ ] Create Listing CPT (job offers/proposals with deadlines) +- [ ] Create Location CPT (venue information, hierarchical) +- [ ] Create Profile CPT (user cultural profiles) +- [ ] Create Project CPT (CCAT projects) +- [ ] Create Representation CPT (event instances) +- [ ] Create Resource CPT (document/link repository) +- [ ] Create Template CPT (reusable content blocks) + +### Custom Taxonomies +- [ ] Create Discipline taxonomy (artistic/cultural categories) +- [ ] Create Listing Category taxonomy +- [ ] Create Project Category taxonomy +- [ ] Create Resource Category taxonomy +- [ ] Configure taxonomy relationships with CPTs + +### ACF Field Groups +- [ ] Design and create ACF fields for Contributor CPT +- [ ] Design and create ACF fields for Event CPT +- [ ] Design and create ACF fields for Listing CPT +- [ ] Design and create ACF fields for Location CPT (venue/room hierarchy) +- [ ] Design and create ACF fields for Profile CPT +- [ ] Design and create ACF fields for Project CPT +- [ ] Design and create ACF fields for Representation CPT +- [ ] Design and create ACF fields for Resource CPT +- [ ] Create flexible content field groups for dynamic layouts +- [ ] Set up ACF options page for site-wide settings + +### WPGraphQL Integration +- [ ] Configure GraphQL schema for all CPTs +- [ ] Configure GraphQL schema for all taxonomies +- [ ] Configure GraphQL schema for ACF fields +- [ ] Test GraphQL queries for all content types +- [ ] Set up GraphQL authentication and permissions + +--- + +## Milestone 3: Authentication & User Management + +### JWT Authentication System +- [ ] Configure JWT authentication for WPGraphQL +- [ ] Create `useAuth` composable for token management +- [ ] Implement user registration flow +- [ ] Implement user login flow +- [ ] Implement JWT token refresh mechanism +- [ ] Handle authentication errors and edge cases + +### User Roles & Permissions +- [ ] Define custom user roles (member, premium, admin) +- [ ] Configure user capabilities and permissions +- [ ] Implement user registration with email verification +- [ ] Create user profile management system +- [ ] Link user accounts to Profile CPT + +### Member Signup & Management +- [ ] Create `useMemberSignup` composable +- [ ] Create `useMemberArea` composable +- [ ] Build member registration forms +- [ ] Build member profile editing interface +- [ ] Implement membership tier upgrades +- [ ] Create admin user impersonation functionality + +--- + +## Milestone 4: Core Nuxt Components + +### Base Component Architecture +- [ ] Set up Nuxt UI integration +- [ ] Create base layout structure +- [ ] Design component organization system + +### Node Components (Main Page Components) +- [ ] Create node component for Contributor pages +- [ ] Create node component for Event pages +- [ ] Create node component for Listing pages +- [ ] Create node component for Location pages +- [ ] Create node component for Profile pages +- [ ] Create node component for Project pages +- [ ] Create node component for Representation pages +- [ ] Create node component for Resource pages +- [ ] Create `useNodeByUri` composable for content fetching + +### Site Components (Global) +- [ ] Create header component with navigation +- [ ] Create footer component +- [ ] Create main navigation system +- [ ] Create breadcrumb navigation (excluding virtual pages) +- [ ] Create search functionality +- [ ] Implement responsive navigation for mobile + +### Authentication Components +- [ ] Create login form component +- [ ] Create registration form component +- [ ] Create password reset component +- [ ] Create protected route middleware +- [ ] Create user profile components +- [ ] Create member zone dashboard + +--- + +## Milestone 5: Content Management & Flexible Layouts + +### Flexible Content Sections +- [ ] Create section components for ACF flexible fields +- [ ] Design reusable content block system +- [ ] Implement Template CPT integration +- [ ] Create dynamic section rendering system +- [ ] Build content editor interface + +### ACF Extended Pro Preview System +- [ ] Configure ACF Extended Pro preview templates +- [ ] Set up iframe preview system +- [ ] Implement SSR rendering for preview content +- [ ] Create preview layouts in `/layouts` directory +- [ ] Test real-time preview functionality + +### Content Features +- [ ] Implement image uploads with point-of-interest cropping +- [ ] Create automated URL redirect system +- [ ] Implement virtual pages (redirect to first child) +- [ ] Build content search and filtering +- [ ] Create content categorization system + +--- + +## Milestone 6: Event System & Calendar + +### Event Management +- [ ] Design event-representation relationship system +- [ ] Create event creation and editing interface +- [ ] Build event listing and detail pages +- [ ] Implement event approval workflow for admins + +### Interactive Calendar +- [ ] Integrate Leaflet maps for location display +- [ ] Build calendar component with multiple views (month/week/day/list) +- [ ] Implement event filtering and search +- [ ] Create event detail modal/popup +- [ ] Add calendar navigation and date selection + +### Event Subscriptions +- [ ] Design event subscription system +- [ ] Create subscription forms (free events) +- [ ] Implement waitlist management +- [ ] Build bulk attendee registration for admins +- [ ] Create subscription confirmation system +- [ ] Add subscription cancellation functionality + +--- + +## Milestone 7: Utilities & Composables + +### Core Composables +- [ ] Create `useResponsive` composable for responsive utilities +- [ ] Create `useSiteOptions` composable for ACF options page +- [ ] Build error handling utilities +- [ ] Create loading state management +- [ ] Implement cache management utilities + +### GraphQL Operations +- [ ] Create GraphQL operation files (`.gql`) in `/app/graphql/` +- [ ] Set up GraphQL codegen for TypeScript types +- [ ] Create reusable GraphQL fragments +- [ ] Implement GraphQL error handling +- [ ] Add GraphQL query optimization + +--- + +## Milestone 8: Third-Party Integrations (PHP) + +### Mailchimp Integration +- [ ] Set up Mailchimp PHP SDK +- [ ] Create user synchronization system +- [ ] Implement newsletter subscription management +- [ ] Build transactional email system +- [ ] Create email template system +- [ ] Add merge field synchronization + +### Stripe Integration +- [ ] Set up Stripe PHP SDK +- [ ] Implement payment processing for premium memberships +- [ ] Create subscription billing system +- [ ] Build payment webhook handling +- [ ] Implement refund processing +- [ ] Add payment analytics and reporting + +### AirTable Import System +- [ ] Design non-destructive import system +- [ ] Create AirTable API integration +- [ ] Build field mapping interface +- [ ] Implement incremental updates +- [ ] Add import validation and error handling +- [ ] Create import history and rollback functionality + +--- + +## Milestone 9: Advanced Features + +### Admin Tools +- [ ] Create admin dashboard +- [ ] Build user management interface +- [ ] Implement content moderation tools +- [ ] Create event subscription management +- [ ] Add analytics and reporting features +- [ ] Build system configuration interface + +### Event Webscraping Tool +- [ ] Design webscraping architecture +- [ ] Create external event source configuration +- [ ] Build automated event discovery system +- [ ] Implement data validation and normalization +- [ ] Add duplicate detection and management +- [ ] Create admin review and approval workflow + +### Premium Membership Features +- [ ] Design premium feature system +- [ ] Enhanced profile visibility +- [ ] Priority event listings +- [ ] Advanced analytics for members +- [ ] Additional content creation tools +- [ ] Premium support features + +--- + +## Milestone 10: UI/UX & Polish + +### Custom UI Components +- [ ] Design and build custom UI component library +- [ ] Create consistent styling system +- [ ] Implement responsive design patterns +- [ ] Add animations and transitions +- [ ] Build accessibility features +- [ ] Create component documentation + +### Mobile Optimization +- [ ] Optimize all components for mobile +- [ ] Implement touch-friendly interactions +- [ ] Create mobile-specific navigation +- [ ] Optimize performance for mobile devices +- [ ] Test across different screen sizes + +--- + +## Milestone 11: Testing & Quality Assurance + +### Unit Testing +- [ ] Set up testing framework +- [ ] Write tests for composables +- [ ] Test utility functions +- [ ] Create mock data for testing +- [ ] Add continuous integration testing + +### Integration Testing +- [ ] Test GraphQL operations +- [ ] Test WordPress/PHP integration +- [ ] Validate third-party integrations +- [ ] Test user authentication flows +- [ ] Verify payment processing + +### End-to-End Testing +- [ ] Test complete user registration flow +- [ ] Test event creation and subscription +- [ ] Test member area functionality +- [ ] Test admin workflows +- [ ] Test content preview system + +--- + +## Milestone 12: Performance & Optimization + +### Performance Optimization +- [ ] Optimize GraphQL queries (prevent N+1) +- [ ] Implement caching strategies +- [ ] Optimize images with @nuxt/image +- [ ] Minimize bundle sizes +- [ ] Implement lazy loading +- [ ] Monitor Core Web Vitals + +### Security Audit +- [ ] Review authentication security +- [ ] Validate input sanitization +- [ ] Test API security +- [ ] Review payment security +- [ ] Implement security headers +- [ ] Run security vulnerability scans + +--- + +## Milestone 13: Launch Preparation + +### Content Migration +- [ ] Migrate existing content from current systems +- [ ] Set up initial user accounts +- [ ] Import event data +- [ ] Configure site-wide settings +- [ ] Test content import process + +### Documentation & Training +- [ ] Create user documentation +- [ ] Write admin training materials +- [ ] Document API endpoints +- [ ] Create troubleshooting guides +- [ ] Record training videos + +### Final Testing & Deployment +- [ ] Complete end-to-end testing +- [ ] Performance testing under load +- [ ] Cross-browser compatibility testing +- [ ] Mobile device testing +- [ ] Production deployment +- [ ] Post-launch monitoring setup + +--- + +## Post-Launch Tasks + +### Ongoing Maintenance +- [ ] Set up monitoring and alerting +- [ ] Create backup procedures +- [ ] Plan regular security updates +- [ ] Monitor performance metrics +- [ ] Gather user feedback +- [ ] Plan feature iterations + +--- + +**Notes:** +- Mark completed tasks with `[x]` +- Add comments or blockers using `` after tasks +- Update this file regularly during development +- Use this file to track progress and plan work sessions \ No newline at end of file