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