IDEA Extended

.planning/codebase/STACK.md

@@ -0,0 +1,126 @@
+# Technology Stack
+
+**Analysis Date:** 2026-02-04
+
+## Languages
+
+**Primary:**
+- PHP 8.1+ - Core application language for WinterCMS framework, all plugins, and controllers
+
+**Secondary:**
+- Twig - Template engine for frontend themes and email templates
+- JavaScript - Frontend interactions and AJAX handlers
+
+## Runtime
+
+**Environment:**
+- PHP 8.1 or higher (required)
+- Laravel 9.x runtime via Winter Storm abstraction layer
+
+**Package Manager:**
+- Composer 2.x - PHP dependency management
+- Lockfile: Present (composer.lock managed by Composer merge plugin)
+
+## Frameworks
+
+**Core:**
+- Winter CMS 1.2.x - Complete CMS/CMF platform based on Laravel 9
+- Laravel Framework 9.1+ - HTTP framework and application foundation
+- Winter Storm (~1.2.0) - Winter's buffer layer between Laravel and Winter plugins
+
+**Key Modules (Winter Core):**
+- `winter/wn-system-module` - Core system functionality, models, migrations
+- `winter/wn-backend-module` - Admin interface, backend forms, list views
+- `winter/wn-cms-module` - Frontend CMS page management and publishing
+
+**Testing:**
+- PHPUnit 9.5.8+ - Unit and functional testing
+- Mockery 1.4.4+ - Mock object framework
+- FakerPHP 1.9.2+ - Test data generation
+
+**Build/Dev:**
+- Laravel Artisan - CLI framework for commands and migrations
+- Wikimedia Composer Merge Plugin 2.1.0 - Automatic plugin composer.json merging
+
+## Key Dependencies
+
+**Critical:**
+- `winter/storm` - Storm library providing DI container, filesystem abstraction, validation framework
+- `laravel/framework` - HTTP kernel, routing, middleware, database ORM (Eloquent), queue system
+- `php-open-source-saver/jwt-auth` - JWT token generation and validation for API authentication
+- `keios/moneyright` - Financial calculations with precise decimal arithmetic (no floats)
+- `keios/apparatus` - Scenario-based workflow engine, DI container enhancements, backend utilities
+- `keios/laravel-apparatus` - Laravel integration for Apparatus framework
+
+**Infrastructure:**
+- `wikimedia/composer-merge-plugin` - Enables modular plugin architecture with separate composer.json per plugin
+
+**Code Quality:**
+- `squizlabs/php_codesniffer` - PSR-1/PSR-2/PSR-4 code standard checking
+- `php-parallel-lint/php-parallel-lint` - Syntax checking
+- `dms/phpunit-arraysubset-asserts` - Extended assertions for arrays in tests
+
+## Configuration
+
+**Environment:**
+- `.env.example` template in project root
+- Environment variables control all external service integration and deployment settings
+- Runtime configuration values:
+  - `APP_NAME`, `APP_KEY`, `APP_DEBUG`, `APP_URL` - Application settings
+  - `DB_CONNECTION`, `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD` - Database
+  - `CACHE_DRIVER`, `SESSION_DRIVER`, `QUEUE_CONNECTION` - Cache/session/queue backends
+  - `REDIS_HOST`, `REDIS_PASSWORD`, `REDIS_PORT` - Redis connection (optional)
+  - `MAIL_MAILER`, `MAIL_HOST`, `MAIL_PORT`, `MAIL_USERNAME`, `MAIL_PASSWORD` - Mail configuration
+  - `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`, `AWS_BUCKET` - AWS S3 (optional)
+
+**Build:**
+- `composer.json` - Project dependencies and scripts
+- `phpunit.xml` - PHPUnit testing configuration
+- `phpcs.xml` - PHP CodeSniffer configuration
+- `.editorconfig` - Editor formatting standards (PSR-compliant)
+- `artisan` - Artisan CLI entry point script
+- `index.php` - HTTP request entry point
+
+**Laravel Config Files (in `config/`):**
+- `app.php` - Application name, debug mode, timezone
+- `database.php` - Database connections (MySQL, PostgreSQL, SQLite, SQL Server, Redis)
+- `cache.php` - Cache stores (file, Redis, Memcached, DynamoDB)
+- `queue.php` - Queue backends (sync, database, beanstalkd, SQS, Redis)
+- `mail.php` - Mail drivers (SMTP, Mailgun, Postmark, SES, Sendmail, Log)
+- `auth.php` - Authentication throttling configuration
+- `session.php` - Session configuration
+- `filesystems.php` - Storage disk configuration
+- `services.php` - Third-party service credentials (Mailgun, Postmark, AWS SES)
+- `database.php` - Multiple database connection types
+
+**Plugin-Specific Config:**
+- JWT configuration publishes to `config/jwt.php` and `config/auth.php` (User plugin)
+- Each plugin manages its own configuration in `plugins/golem15/*/config/`
+
+## Platform Requirements
+
+**Development:**
+- PHP 8.1+ installed and available in PATH (use `php-legacy` command per project CLAUDE.md)
+- Composer 2.x
+- MySQL 5.7+ OR PostgreSQL 9.5+ OR SQLite OR SQL Server (at least one required)
+- Optional: Redis 5+ (for caching, sessions, queues)
+- Optional: Memcached (for caching)
+
+**Production:**
+- PHP 8.1+ with common extensions (PDO, OpenSSL, Fileinfo, Tokenizer, MBSTRING)
+- MySQL 5.7+ OR PostgreSQL 9.5+ OR SQL Server database
+- Redis (recommended for performance)
+- Web server: Apache with mod_rewrite OR Nginx
+- Cron job setup for Laravel scheduler (see CLAUDE.md)
+
+**Optional Services:**
+- AWS S3 (for file storage, requires AWS SDK)
+- Stripe (payment processing, requires stripe-php SDK)
+- OpenAI API (AI integration, requires OpenAI PHP SDK)
+- Perplexity API (AI integration alternative)
+- Mailgun/Postmark/AWS SES (transactional email)
+- GitHub API (Git integration via GitHub plugin)
+
+---
+
+*Stack analysis: 2026-02-04*