pascalmartineau/cultureat-bak
4
0
Fork 0
generated from pascalmartineau/wp-skeleton
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b12f1fc2a259781bbd17a16555831eac1caf7c54
cultureat-bak/.claude/PLANNING.md

12 KiB
Raw Blame History

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.

Reference in New Issue View Git Blame Copy Permalink