cultureat-bak/.claude/PLANNING.md

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

# 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)

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