# 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.*