generated from pascalmartineau/wp-skeleton
Pascal Martineau
8fbac701f6
All checks were successful
Deploy WordPress and Nuxt / deploy (push) Successful in 1m2s
407 lines
17 KiB
Markdown
407 lines
17 KiB
Markdown
# 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 (Current Implementation)
|
|
|
|
### Core Platform - ✅ IMPLEMENTED
|
|
| Component | Technology | Version | Purpose | Status |
|
|
|-----------|------------|---------|---------|---------|
|
|
| **CMS** | WordPress | Latest | Content management system | ✅ Configured |
|
|
| **Frontend** | Nuxt | 4.1.2 | Modern Vue.js framework | ✅ Integrated |
|
|
| **UI Framework** | Nuxt UI | 4.0.0 | Component library | ✅ Configured |
|
|
| **Database** | MySQL | 8.0+ | Data storage | ✅ Operational |
|
|
| **Language** | PHP | 8.1+ | WordPress backend | ✅ Compatible |
|
|
| **Language** | TypeScript | 5.9.2 | Frontend development | ✅ Configured |
|
|
|
|
### 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 - 🚧 PARTIALLY CONFIGURED
|
|
|
|
#### Version Control - ✅ OPERATIONAL
|
|
- **Git**: Version control system (configured)
|
|
- **Gitea**: Self-hosted Git service with Actions (.gitea/workflows configured)
|
|
- **Git Flow**: Branching strategy for organized development (main branch active)
|
|
|
|
#### Project Management - ✅ CONFIGURED
|
|
- **TASKS.md**: Task tracking using markdown checkboxes (comprehensive)
|
|
- **PLANNING.md**: This document for project planning (updated)
|
|
- **CLAUDE.md**: Development guide for AI assistance (detailed)
|
|
|
|
#### Testing Tools - ⏳ NOT IMPLEMENTED
|
|
- **Vitest**: Unit testing for frontend (not configured)
|
|
- **PHPUnit**: Unit testing for WordPress/PHP (not configured)
|
|
- **Playwright**: End-to-end testing (not configured)
|
|
- **GraphQL testing tools**: For API validation (not configured)
|
|
|
|
---
|
|
|
|
## ⚙️ Configuration & Deployment
|
|
|
|
### Environment Variables
|
|
```bash
|
|
# WordPress/Nuxt Integration - ✅ CONFIGURED
|
|
NUXT_GRAPHQL_ENDPOINT="https://wp.cultureat.ca/graphql" # WordPress GraphQL endpoint
|
|
NUXT_SESSION_PASSWORD= # JWT authentication secret (configured)
|
|
NUXT_HUB_PROJECT_KEY= # NuxtHub project reference (configured)
|
|
|
|
# Third-party Services - ⏳ PENDING IMPLEMENTATION
|
|
MAILCHIMP_API_KEY= # Mailchimp integration (not implemented)
|
|
STRIPE_SECRET_KEY= # Stripe payments (not implemented)
|
|
STRIPE_PUBLISHABLE_KEY= # Stripe public key (not implemented)
|
|
AIRTABLE_API_KEY= # AirTable import key (not implemented)
|
|
```
|
|
|
|
### Useful Commands (Current Implementation)
|
|
```bash
|
|
# Development - ✅ WORKING
|
|
pnpm dev:nuxt # Start Nuxt dev server --host (configured)
|
|
pnpm build:typecheck # Check for TypeScript errors (working)
|
|
pnpm build:nuxt # Build Nuxt for production (working)
|
|
pnpm lint # ESLint with --fix (working)
|
|
composer install # Install WordPress plugins (working)
|
|
git push origin main # Deploy via Gitea Actions (configured)
|
|
|
|
# WordPress - ✅ WORKING
|
|
composer update # Update plugin dependencies (working)
|
|
wp-cli commands # WordPress CLI available
|
|
|
|
# Additional Available Commands
|
|
pnpm deploy # NuxtHub deployment
|
|
pnpm preview # NuxtHub preview
|
|
pnpm postinstall:nuxt # Nuxt preparation
|
|
```
|
|
|
|
### Deployment Configuration - ✅ CONFIGURED
|
|
- **CI/CD**: Gitea Actions configured for push-to-deploy
|
|
- **Hosting**: NuxtHub integration with Cloudflare Workers
|
|
- **Domain**: cultureat.ca configured in nuxt.config.ts
|
|
- **SSL**: Required and configured for secure authentication
|
|
- **Build System**: Optimized for production with Nitro preset
|
|
|
|
### Implementation Specifics
|
|
|
|
#### File Structure Analysis - ✅ IMPLEMENTED
|
|
```
|
|
wp-content/themes/ccat/
|
|
├── acf-json/ # 25+ ACF field groups (212KB total)
|
|
├── app/ # Nuxt 4 application
|
|
│ ├── components/ # 7 directories, organized by function
|
|
│ ├── composables/ # 7 composables (3 stubs need completion)
|
|
│ ├── graphql/ # 5 GraphQL operations
|
|
│ └── pages/ # 4 pages (member-focused + dynamic routing)
|
|
├── includes/ # WordPress PHP logic
|
|
│ ├── cpt/ # 9 Custom Post Types (all implemented)
|
|
│ ├── taxonomies/ # 4 Custom Taxonomies (all implemented)
|
|
│ └── graphql/ # Custom GraphQL extensions
|
|
├── server/ # Nuxt server directory
|
|
│ └── schema.graphql # 866KB generated schema
|
|
└── package.json # 18 dependencies, 4 dev dependencies
|
|
```
|
|
|
|
#### Critical Technical Debt Identified
|
|
1. **Member Composables**: `useMemberSignup.ts` and `useMemberArea.ts` are 49-byte stubs
|
|
2. **Footer Implementation**: TheSiteFooter.vue shows "TODO" - needs top section content
|
|
3. **Site Navigation**: Header/navigation fully implemented with responsive design
|
|
4. **Integration Gaps**: No third-party service integrations (Mailchimp, Stripe, AirTable)
|
|
5. **Testing Coverage**: Zero test files found in entire project
|
|
|
|
---
|
|
|
|
## 📋 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
|
|
|
|
---
|
|
|
|
## 📊 Current Implementation Status
|
|
|
|
### Overall Project Progress: **~65% Complete**
|
|
|
|
### ✅ Completed Infrastructure
|
|
- **WordPress Theme Structure**: Complete Nuxt 4 integration within WordPress theme
|
|
- **Content Management**: 9 Custom Post Types, 4 Taxonomies, 25+ ACF field groups
|
|
- **GraphQL API**: Comprehensive 866KB schema with all content types exposed
|
|
- **Authentication**: JWT-based system with role management and impersonation
|
|
- **Core Components**: Node components for major content types, basic sections system
|
|
- **Development Environment**: Full toolchain with TypeScript, ESLint, build scripts
|
|
|
|
### 🚧 In Progress Components
|
|
- **Member Management**: Pages exist, but composables are stubs requiring completion
|
|
- **Site Structure**: Header/navigation complete, footer needs top section implementation
|
|
- **Event System**: CPTs ready, but calendar and mapping integration needed
|
|
- **Content Sections**: Basic system works, needs expansion of section types
|
|
|
|
### ⏳ Pending Integrations
|
|
- **Third-party Services**: Mailchimp, Stripe, AirTable integrations not implemented
|
|
- **Advanced Features**: Event subscriptions, premium memberships, admin tools
|
|
- **Performance**: Optimization, caching, and production readiness
|
|
- **Testing**: Comprehensive testing suite and quality assurance
|
|
|
|
### 🔥 Critical Next Steps
|
|
1. **Complete Member Area** - Finish useMemberSignup and useMemberArea composables (currently 49-byte stubs)
|
|
2. **Event Calendar Integration** - Implement Leaflet maps and calendar components
|
|
3. **Event-Representation Integration** - Display event instances via Event pages (backend relation)
|
|
4. **Footer Top Section** - Complete TheSiteFooter.vue implementation (currently shows "TODO")
|
|
|
|
---
|
|
|
|
## 📈 Future Roadmap
|
|
|
|
### Post-Launch Enhancements (Year 1)
|
|
- **Advanced Search**: Enhanced filtering and search capabilities
|
|
- **API Expansion**: Public API for third-party integrations
|
|
- **Analytics Dashboard**: Advanced reporting for admins
|
|
|
|
### Long-Term Vision (Years 2-3)
|
|
- **AI Features**: Content recommendations and smart matching
|
|
|
|
---
|
|
|
|
**Document Status**: Living document, updated regularly
|
|
**Last Updated**: September 25, 2025 - Comprehensive status analysis completed
|
|
**Current Phase**: Phase 2 (Core Features) - 70% complete
|
|
**Next Review**: Completion of site components and member management systems
|
|
**Critical Blocker**: Site components (header/footer/nav) must be completed before user testing
|
|
|
|
---
|
|
|
|
*This planning document serves as the north star for the CCAT project. All development decisions should align with the vision and principles outlined here.* |