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

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

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:

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

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

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

QUEUE_CONNECTION=redis
QUEUE_DRIVER=redis

Starting Queue Worker

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

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

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

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)

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

[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

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