summercms-initial-research/.planning/codebase/INTEGRATIONS.md

# External Integrations

**Analysis Date:** 2026-02-04

## APIs & External Services

**Payment Processing:**
- Stripe - Payment provider for transactions
  - SDK/Client: `stripe/stripe-php` (integrated via PgStripe plugin)
  - Env vars: `STRIPE_API_KEY`, `STRIPE_SECRET_KEY` (configured in `plugins/golem15/pgstripe/`)
  - Purpose: Card processing, payment authorization, subscription management via PaymentGateway system

**AI Services:**
- OpenAI - LLM and chat completions
  - SDK/Client: `openai-php/client` (integrated via AI plugin)
  - Env vars: `OPENAI_API_KEY`
  - Purpose: AI chat interfaces, prompt management, text generation
  - Location: `plugins/golem15/ai/`

- Perplexity - Alternative LLM provider
  - SDK/Client: Native HTTP client integration
  - Env vars: `PERPLEXITY_API_KEY`
  - Purpose: Alternative AI engine for AI plugin
  - Location: `plugins/golem15/ai/`

**GitHub Integration:**
- GitHub API v3 - Repository and content management
  - SDK/Client: GitHub REST API via HTTP client
  - Env vars: `GITHUB_TOKEN` (optional, for private repos)
  - Purpose: Git integration features (repo mirroring, CI/CD hooks)
  - Location: `plugins/golem15/github/`

**OAuth/Social Authentication:**
- Laravel Socialite - OAuth provider framework
  - SDK/Client: `laravel/socialite`
  - Configured via: `config/services.php`
  - Purpose: Social login integration (Google, GitHub, etc.) for User plugin
  - Location: `plugins/golem15/user/`

## Data Storage

**Databases:**
- MySQL 5.7+ (default in `.env.example`, `DB_CONNECTION=mysql`)
  - Connection: `DB_HOST=127.0.0.1`, `DB_PORT=3306`, `DB_DATABASE=database`, `DB_USERNAME=root`, `DB_PASSWORD=`
  - Client: Laravel Eloquent ORM (built into Laravel Framework)
  - Config file: `config/database.php`

- PostgreSQL 9.5+ (supported alternative)
  - Connection: `DB_CONNECTION=pgsql`
  - Client: Laravel Eloquent ORM
  - Config file: `config/database.php`

- SQLite (supported alternative, file-based)
  - Connection: `DB_CONNECTION=sqlite`
  - Default file: `storage/database.sqlite`
  - Client: Laravel Eloquent ORM
  - Config file: `config/database.php`

- SQL Server (supported alternative)
  - Connection: `DB_CONNECTION=sqlsrv`
  - Client: Laravel Eloquent ORM
  - Config file: `config/database.php`

**File Storage:**
- AWS S3 (optional)
  - Env vars: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`, `AWS_BUCKET`
  - Client: AWS SDK for PHP
  - Config: `config/filesystems.php`, can use S3 disk for file uploads
  - Purpose: Cloud file storage and CDN delivery

- Local filesystem (default)
  - Storage paths: `storage/app/`, `storage/app/public/`
  - Public access via symlink: `public/storage/`
  - Generated via: `php artisan winter:mirror public --relative`

**Caching:**
- File-based cache (default, `CACHE_DRIVER=file`)
  - Location: `storage/framework/cache/`

- Redis cache (optional, `CACHE_DRIVER=redis`)
  - Connection: `REDIS_HOST=127.0.0.1`, `REDIS_PORT=6379`, `REDIS_PASSWORD=null`
  - Config: `config/cache.php` and `config/database.php` (redis section)
  - Purpose: Fast in-memory caching, session storage, queue backend

- Memcached (optional, `CACHE_DRIVER=memcached`)
  - Connection: `MEMCACHED_HOST=127.0.0.1`, `MEMCACHED_PORT=11211`
  - Config: `config/cache.php`

## Authentication & Identity

**Auth Provider:**
- Custom JWT-based API authentication
  - Implementation: PHP Open Source Saver JWT Auth (`php-open-source-saver/jwt-auth`)
  - Config files: `config/jwt.php`, `config/auth.php`
  - Purpose: Stateless API authentication for frontend-backend communication
  - Location: `plugins/golem15/user/`
  - Middleware: `jwt.auth` for protected routes, `jwt.refresh` for token refresh

- Backend Admin Auth
  - Implementation: Laravel session-based authentication
  - Throttling: Enabled by default (5 attempts, 15-minute suspension)
  - Config: `config/auth.php` (throttle settings)

- OAuth Social Login (optional)
  - Providers: Configurable via Laravel Socialite
  - Integration: User plugin

## Monitoring & Observability

**Error Tracking:**
- Not detected in default stack
- Framework: Laravel uses default error logging to files/channels

**Logs:**
- File-based logging (default)
  - Location: `storage/logs/`
  - Driver: `log` (Laravel default single/daily file rotation)
  - Config: `config/logging.php`

- Optional: Syslog, Papertrail, or other channels via `config/logging.php`

**Debug Mode:**
- Enabled via `APP_DEBUG=true` in `.env`
- Winter CMS debugbar available via `debugbar` plugin (`plugins/winter/debugbar/`)
- WARNING: Always disable `APP_DEBUG=false` in production

## CI/CD & Deployment

**Hosting:**
- Not locked to specific platform
- Requirements: PHP 8.1+ environment with Composer
- Supports: Traditional VPS, managed hosting, containerized deployment

**CI Pipeline:**
- Not detected in default stack
- Test execution: `composer test` or `php artisan winter:test`
- Linting: `composer lint` (parallel-lint for syntax)
- Code sniffing: `composer sniff` (PHPCS for PSR standards)

**Scheduled Tasks:**
- Laravel Scheduler via cron job (requires cron setup)
- Cron entry: `* * * * * cd /path/to/project && php artisan schedule:run >> /dev/null 2>&1`
- Scheduled commands (PaymentGateway plugin):
  - `pg:cancel-sent-payments` - Daily
  - `pg:cancel-created-payments` - Daily
  - `pg:cancel-placed-orders` - Daily
  - `pg:finish-orders` - Daily
  - `pg:update-currencies` - Every 10 minutes
- User plugin scheduled tasks:
  - `user:process-scheduled-deletions` - GDPR scheduled user deletion processing

## Environment Configuration

**Required env vars:**
- `APP_NAME` - Application display name
- `APP_KEY` - Laravel encryption key (generate via `php artisan winter:env`)
- `APP_DEBUG` - Debug mode (true for dev, false for production)
- `APP_URL` - Application URL for URL generation
- `DB_CONNECTION`, `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD` - Database connection
- `CACHE_DRIVER` - Cache backend (file, redis, memcached)
- `SESSION_DRIVER` - Session storage (file, redis, database)
- `QUEUE_CONNECTION` - Queue backend (sync, redis, database, beanstalkd)
- `MAIL_MAILER` - Mail driver (log, smtp, mailgun, postmark, ses, sendmail)

**Secrets location:**
- `.env` file in project root (generated from `.env.example`)
- Not committed to git (listed in `.gitignore`)
- AWS credentials: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
- Mail credentials: `MAIL_USERNAME`, `MAIL_PASSWORD`
- Third-party API keys: `STRIPE_API_KEY`, `OPENAI_API_KEY`, `PERPLEXITY_API_KEY`, `GITHUB_TOKEN`
- Redis password: `REDIS_PASSWORD`

## Webhooks & Callbacks

**Incoming:**
- Payment webhooks from Stripe (handled by PgStripe plugin)
  - Endpoint: Stripe event signature verification via Stripe SDK
  - Events: payment.success, payment.failed, charge.refunded, subscription events
  - Handler: `plugins/golem15/pgstripe/` webhook listeners

- GitHub webhooks (optional, via GitHub plugin)
  - Configurable push/pull request/issue event handlers
  - Handler: `plugins/golem15/github/`

**Outgoing:**
- Email notifications via configured mailer
  - User registration confirmation
  - Payment/order state change notifications (PaymentGateway plugin)
  - Newsletter/notification system via Mail plugin
  - Env vars: `MAIL_FROM_ADDRESS`, `MAIL_FROM_NAME`

- Queue workers for async email
  - Driver: `QUEUE_CONNECTION` (default: sync for dev, database/redis for production)
  - Jobs table: `jobs` migration creates queue job storage

## Message Queue System

**Queue Backend:**
- Sync driver (default, development) - Processes jobs immediately in request lifecycle
  - `QUEUE_CONNECTION=sync`

- Database driver (production-ready) - Stores jobs in `jobs` table
  - `QUEUE_CONNECTION=database`
  - Table: `jobs`
  - Requires: `php artisan queue:work` background worker

- Redis driver (optimal for high throughput)
  - `QUEUE_CONNECTION=redis`
  - Connection: Uses REDIS config from `config/database.php`

- Beanstalkd driver (alternative)
  - `QUEUE_CONNECTION=beanstalkd`
  - Host: `localhost`, configurable via queue.php

## Session Management

**Driver:**
- File-based (default, `SESSION_DRIVER=file`)
  - Location: `storage/framework/sessions/`

- Redis (optional, `SESSION_DRIVER=redis`)
  - Connection: Uses REDIS config

- Database (optional, `SESSION_DRIVER=database`)
  - Table: `sessions`

- Cookie (alternative, `SESSION_DRIVER=cookie`)

## Real-Time Communication

**WebSockets (via WebSockets plugin):**
- Framework: Pusher-compatible WebSocket support
- Plugin: `plugins/golem15/websockets/`
- Purpose: Real-time chat, notifications, live updates
- Config: Managed by WebSockets plugin
- Test command: `php artisan websockets:test-push`

---

*Integration audit: 2026-02-04*