chore: Update CLAUDE / PLANNING / TASKS

2025-09-25 09:30:16 -04:00
parent 4c41ff2dae
commit b12f1fc2a2
3 changed files with 1064 additions and 46 deletions
--- a/.claude/PLANNING.md
+++ 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.*