timebank-cc-public/references/EXTERNAL_SERVICES_REQUIREMENTS.md

# Timebank.cc - External Services Requirements

This document outlines all external services, dependencies, and infrastructure requirements needed to run the Timebank.cc application.

## Core Runtime Requirements

### PHP
- **Version**: PHP 8.0+ (required by Laravel 10.x)
- **Recommended**: PHP 8.3 for best performance and latest features
- **Required Extensions**:
  - `curl`, `dom`, `gd`, `json`, `mbstring`, `openssl`, `pcre`, `pdo`, `tokenizer`, `xml`, `zip`
  - `redis` - For cache and queue operations
  - `mysql`/`mysqli` - For database connectivity
  - `bcmath` - For precise financial calculations
  - `intl` - For multi-language support

### Web Server
- **Apache 2.4+** or **Nginx 1.18+**
- **SSL/TLS** support required for production
- **Rewrite rules** enabled for clean URLs

## Database Services

### MySQL/MariaDB (Primary Database)
- **MySQL**: 8.0+ (required for window functions in transaction balance calculations)
- **MariaDB**: 10.2+ (required for window function support)
- **Configuration Requirements**:
  - UTF8MB4 character set support
  - Large packet size for media uploads (`max_allowed_packet >= 64MB`)
  - InnoDB storage engine
- **Special Database User Permissions**:
  - Transaction table has restricted DELETE/UPDATE permissions at MySQL user level
  - Single application user with table-level restrictions to enforce transaction immutability

### Database Connection
```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=timebank_cc
DB_USERNAME=timebank_user
DB_PASSWORD=secure_password
```

## Cache & Session Storage

### Redis (Required)
- **Version**: Redis 6.0+ recommended
- **Usage**:
  - Session storage (`SESSION_DRIVER=redis`)
  - Application cache (`CACHE_DRIVER=redis`)
  - Queue backend (`QUEUE_CONNECTION=redis`)
  - Real-time presence tracking (online status)

### Redis Configuration
```env
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=
REDIS_PORT=6379
REDIS_CACHE_DB=1
```

## Search Service

### Elasticsearch (Required)
- **Version**: Elasticsearch 7.x or 8.x
- **Usage**: Full-text search with Scout integration
- **Features**:
  - Multi-language search (en, nl, de, es, fr)
  - Configurable field boosting
  - Geographic search capabilities
- **Memory Requirements**: Minimum 2GB RAM allocated to Elasticsearch
- **Configuration**:
```env
ELASTICSEARCH_HOST=localhost:9200
SCOUT_DRIVER=matchish-elasticsearch
```

### Search Indices
The application uses multiple Elasticsearch indices:
- `posts_index` - Blog posts and events
- `users_index` - User profiles
- `organizations_index` - Organization profiles  
- `banks_index` - Bank profiles

## Real-time Communication

### Laravel Reverb WebSocket Server (Required)
- **Laravel Reverb**: WebSocket server (Laravel package)
- **Port**: 8080 (configurable)
- **Usage**:
  - Real-time messaging via WireChat package
  - Live notifications
  - Presence system (online status tracking)
  - Livewire real-time updates

### WebSocket Configuration
```env
BROADCAST_DRIVER=reverb
PUSHER_APP_ID=local-app-id
PUSHER_APP_KEY=local-app-key
PUSHER_APP_SECRET=local-app-secret
PUSHER_HOST=localhost
PUSHER_PORT=8080
PUSHER_SCHEME=http
```

### Starting WebSocket Server
```bash
php artisan reverb:start
```

## Queue Processing

### Queue Worker (Required)
- **Backend**: Redis-based queues
- **Usage**:
  - Email processing
  - Background job processing
  - File uploads and processing
  - Search index updates

### Queue Configuration
```env
QUEUE_CONNECTION=redis
QUEUE_DRIVER=redis
```

### Starting Queue Worker
```bash
php artisan queue:work
```

## Email Services

### SMTP Server (Required for Production)
- **Development**: Mailtrap, MailHog, or similar testing service
- **Production**: Any SMTP provider (SendGrid, Mailgun, AWS SES, etc.)

### Email Configuration
```env
MAIL_MAILER=smtp
MAIL_HOST=smtp.provider.com
MAIL_PORT=587
MAIL_USERNAME=username
MAIL_PASSWORD=password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@timebank.cc
```

## File Storage & Media

### File Storage
- **Local Storage**: Default for development
- **Cloud Storage**: AWS S3, DigitalOcean Spaces, or compatible for production
- **Media Library**: Spatie Media Library for file management
- **Requirements**:
  - Image processing: GD or Imagick PHP extension
  - Max file size: 12MB (configurable)
  - Supported formats: jpg, jpeg, png, gif, webp, pdf, documents

### Storage Configuration
```env
FILESYSTEM_DRIVER=local  # or s3 for production
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=
AWS_BUCKET=
```

## Frontend Build Tools

### Node.js & npm (Development)
- **Node.js**: 16.x+ LTS
- **npm**: 8.x+
- **Usage**:
  - Asset compilation (Vite)
  - TailwindCSS processing
  - JavaScript bundling

### Frontend Dependencies
- **Alpine.js**: Client-side reactivity
- **TailwindCSS**: Utility-first CSS framework
- **Vite**: Modern asset bundling and development server

### Build Commands
```bash
npm run dev        # Development server with hot module replacement
npm run build      # Production build
npm run prod       # Production build (alias)
npm run production # Production build (alias)
```

## Optional Services

### Location Services
- **IP Geolocation**: For user location detection
- **APIs**: Various location lookup services (configurable)
```env
LOCATION_TESTING=true
```

### Development Tools
- **Laravel Debugbar**: Development debugging
- **Laravel Telescope**: Application monitoring (optional)
- **Laradumps**: Enhanced debugging

### Monitoring & Analytics
- **Activity Logger**: Built-in user activity tracking (no external services, only for security / debugging)
- **Search Analytics**: Search pattern tracking (optional)

## Environment-Specific Requirements

### Development Environment
- **PHP**: 8.0+ with Xdebug
- **Database**: Local MySQL/MariaDB
- **Redis**: Local Redis instance
- **Elasticsearch**: Local Elasticsearch instance
- **WebSocket**: Laravel Reverb on localhost
- **Mail**: Mailtrap or MailHog

### Production Environment  
- **PHP**: 8.1+ with OPcache enabled
- **Database**: MySQL 8.0+ with replication (recommended)
- **Redis**: Redis cluster for high availability
- **Elasticsearch**: Multi-node cluster with proper memory allocation
- **WebSocket**: Laravel Reverb with process management (Supervisor)
- **Queue**: Multiple queue workers with Supervisor
- **Load Balancer**: For multiple app instances
- **SSL Certificate**: Required for WebSocket and general security

## Deployment Considerations

### Process Management (Production)
- **Supervisor**: For queue workers and WebSocket server
- **Process monitoring**: Ensure critical services restart on failure

### Example Supervisor Configuration
```ini
[program:timebank-queue]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/timebank/artisan queue:work redis --sleep=3 --tries=3
directory=/var/www/timebank
user=www-data
numprocs=8

[program:timebank-reverb]
process_name=%(program_name)s
command=php /var/www/timebank/artisan reverb:start
directory=/var/www/timebank
user=www-data
```

### Security Requirements
- **Firewall**: Ports 80, 443, 8080 (WebSocket)
- **SSL/TLS**: Required for production
- **Database Security**: Restricted user permissions
- **File Permissions**: Proper Laravel directory permissions

### Performance Optimization
- **OPcache**: PHP bytecode caching
- **Redis**: Memory-based caching
- **CDN**: For static assets (optional)
- **Database Indexing**: Proper indexes for large datasets

## Container Deployment (Optional)

### Docker Services
If using containerization, the following services are needed:

- **App Container**: PHP-FPM with required extensions
- **Web Server**: Nginx or Apache
- **Database**: MySQL 8.0+ container
- **Redis**: Redis container
- **Elasticsearch**: Elasticsearch container
- **Queue Worker**: Dedicated container for queue processing
- **WebSocket**: Container for Reverb WebSocket server

### Docker Compose Example Structure
```yaml
services:
  app:
    # PHP application
  nginx:
    # Web server
  mysql:
    # Database
  redis:
    # Cache & sessions
  elasticsearch:
    # Search service
  queue:
    # Queue worker
  websocket:
    # Reverb server
```

## Minimum System Resources

### Development
- **CPU**: 2 cores
- **RAM**: 4GB (2GB for app, 2GB for services)
- **Storage**: 10GB

### Production (Small)
- **CPU**: 4 cores
- **RAM**: 8GB (4GB for app, 2GB for Redis, 2GB for Elasticsearch)
- **Storage**: 50GB+ with SSD

### Production (Medium)
- **CPU**: 8 cores
- **RAM**: 16GB
- **Storage**: 100GB+ SSD
- **Network**: Load balancer, CDN integration