timebank-cc-public/README.md

Timebank.cc

A community time banking platform where members exchange services using time as currency. Built with Laravel, Livewire 3, and real-time WebSocket support.

Development Status: Active development — not production-ready.

Features

• Multi-Profile System: Switch between Individual, Organization, Bank, and Admin profiles
• Time-Based Transactions: Immutable transaction history with MySQL-level write protection
• Real-Time Messaging: Live chat with presence indicators via Laravel Reverb
• Advanced Search: Elasticsearch-powered with location and skill matching
• Multilingual: English, Dutch, German, Spanish, French
• White-Label: Theme and configuration system for custom deployments

Prerequisites

• PHP 8.3+
• MySQL 8.0+ or MariaDB 10.2+ (window function support required)
• Redis
• Elasticsearch 8.x
• Node.js & NPM
• Composer

See references/SETUP_GUIDE.md for full server setup instructions.

Quick Start

# 1. Install dependencies
composer install
npm install

# 2. Configure environment
cp .env.example .env
php artisan key:generate
# Edit .env with your database, Redis, Elasticsearch, and mail settings

# 3. Database
php artisan migrate
php artisan db:seed
php artisan storage:link

# 4. Search index
php artisan scout:import

# 5. Start services (separate terminals)
php artisan serve
php artisan queue:work --queue=high,messages,default,emails,mailing,low
php artisan reverb:start
npm run dev

Architecture

Multi-Guard Authentication

Four profile types using Laravel multi-guard auth (web, admin, bank, organization). Active guard stored in session; profile switching handled by SwitchGuardTrait.

Transaction Immutability

Transactions are protected at the MySQL user level — the app DB user cannot UPDATE or DELETE from the transactions table:

REVOKE UPDATE, DELETE ON `timebank_cc`.transactions FROM 'timebank_user'@'localhost';

White-Label Configuration

Copy config/timebank-default.php, customize it, and set TIMEBANK_CONFIG=your-platform in .env. Use timebank_config('key') throughout the codebase.

Theme System

Themes are configured in config/themes.php and activated via TIMEBANK_THEME. Available themes: timebank_cc, uuro, vegetable, yellow. See references/THEME_IMPLEMENTATION.md.

Technology Stack

Layer	Technology
Backend	Laravel 10, Livewire 3, Laravel Jetstream
Frontend	Tailwind CSS, Alpine.js, WireUI, Vite
Database	MySQL 8+ / MariaDB 10.2+
Search	Elasticsearch 8.x via Laravel Scout
Real-time	Laravel Reverb (WebSocket)
Cache/Queue	Redis

Scripts

Root-level

Script	Description
./deploy.sh	Universal deployment script (local and server)
./deploy.sh -e server	Deploy using server .env configuration
./deploy.sh -m	Skip migrations
./deploy.sh -n	Skip npm build
./seed.sh	Run db:seed with elevated MySQL privileges (needed for DROP operations)
./deployment-htmlpurifier-fix.sh	Set up HTMLPurifier cache (run after deploy or manually)

scripts/ directory

Script	Description
scripts/backup-all.sh	Master backup: database + storage
scripts/backup-database.sh	Database backup only
scripts/backup-storage.sh	Storage backup only
scripts/restore-all.sh	Full restore: database + storage
scripts/restore-database.sh	Database restore only
scripts/restore-storage.sh	Storage restore only
scripts/cleanup-backups.sh	Remove old backup files
scripts/setup-backups.sh	Initialize backup directory structure
scripts/re-index-search.sh	Rebuild Elasticsearch search indices
scripts/mail-switch.sh	Toggle between Mailpit (local) and real SMTP
scripts/send-all-test-emails.sh	Send all transactional test emails in all 5 languages
scripts/test-transactional-emails.sh	Interactive transactional email test
scripts/test-inactive-warning-emails.sh	Test inactive profile warning emails
scripts/test-all-warnings.sh	Test all profile warning flows
scripts/test-transaction-immutability.sh	Verify transaction immutability on active DB
scripts/check-elasticsearch-security.sh	Check Elasticsearch security configuration
scripts/create-restricted-db-user-safe.sh	Create restricted app DB user with write protections
scripts/migrate-to-example-configs.sh	Migrate to .example config pattern
scripts/debug-db-connection.sh	Debug database connection from .env
scripts/log.sh	Development log viewer (do not include in production)

Artisan Commands

Development & Deployment

php artisan serve              # Dev server
php artisan queue:work --queue=high,messages,default,emails,mailing,low  # Queue worker
php artisan reverb:start       # WebSocket server
npm run dev                    # Asset dev server (HMR)
npm run build                  # Production assets
php artisan optimize           # Rebuild config/route/view cache
php artisan scout:import       # Rebuild search indices (high memory)
php artisan test               # Run test suite
php artisan database:update    # Apply schema changes and data migrations
php artisan config:merge --all # Merge new keys from .example config files

Profiles

php artisan profiles:mark-inactive          # Mark profiles inactive based on login threshold
php artisan profiles:process-inactive       # Send warnings and delete over-threshold profiles
php artisan profiles:permanently-delete-expired  # Anonymize profiles past grace period
php artisan profiles:restore <id>           # Restore a soft-deleted profile

Mailings

php artisan mailings:process-scheduled      # Send scheduled mailings that are ready
php artisan mailings:process-bounces        # Process bounce emails from bounce mailbox
php artisan mailings:manage-bounces         # Apply threshold-based actions on bounced addresses
php artisan mailings:retry-failed           # Retry failed mailings outside their retry window
php artisan email:send-test                 # Send test transactional emails

Calls / Posts

php artisan calls:process-expiry            # Send expiry warnings and expired notifications
php artisan posts:backup                    # Backup posts + media to ZIP archive
php artisan posts:restore                   # Restore posts from backup file

Tags & Skills

# Export existing tags/categories to JSON (for AI-assisted translation/generation)
php artisan tags:import-export export-categories
php artisan tags:import-export export-tags
php artisan tags:import-export export-tags --category-id=5 --locale=en

# Import translated/generated tags from JSON files in imports/tags/
php artisan tags:import-export import
php artisan tags:import-export import path/to/file.json
php artisan tags:import-export import --dry-run   # Preview without changes

# Remove a tag group
php artisan tags:import-export remove-group

# Validate tag translations across all locales
php artisan tags:validate-translations
php artisan tags:validate-translations --locale=nl
php artisan tags:validate-translations --show-missing
php artisan tags:validate-translations --show-duplicates
php artisan tags:validate-translations --show-contexts

Tags can also be seeded directly from the database seeders:

php artisan db:seed --class=TaggableTagsTableSeeder
php artisan db:seed --class=TaggableContextsTableSeeder
php artisan db:seed --class=TaggableLocalesTableSeeder
php artisan db:seed --class=TaggableLocaleContextTableSeeder

Translations

php artisan ai-translator:translate         # Translate PHP language files via AI
php artisan ai-translator:translate-json    # Translate JSON language files via AI
php artisan ai-translator:find-unused       # Find unused translation keys
php artisan ai-translator:clean             # Remove translated strings to prepare for re-translation

Translation helper scripts (in references/translations/):

references/translations/translate-all-sequential.sh  # Translate all locales sequentially
references/translations/translate-new-keys.sh         # Translate only new/missing keys
references/translations/retranslate-informal.sh       # Re-translate informal language variants

Key Configuration (.env)

TIMEBANK_CONFIG=timebank_cc
TIMEBANK_THEME=timebank_cc

DB_CONNECTION=mysql
DB_DATABASE=timebank_cc
DB_USERNAME=timebank_cc_app
DB_PASSWORD=your_password

ELASTICSEARCH_HOST=localhost:9200
SCOUT_DRIVER=matchish-elasticsearch

BROADCAST_DRIVER=reverb
REVERB_APP_ID=app-id
REVERB_APP_KEY=app-key
REVERB_APP_SECRET=app-secret

CACHE_DRIVER=redis
SESSION_DRIVER=database
QUEUE_CONNECTION=redis

References

Document	Description
references/SETUP_GUIDE.md	Full Debian server setup
references/EXTERNAL_SERVICES_REQUIREMENTS.md	Redis, Elasticsearch, mail setup
references/WEBSOCKET_SETUP.md	Reverb / WebSocket configuration
references/THEME_IMPLEMENTATION.md	Theme system details
references/STYLE_GUIDE.md	UI component patterns
references/CONFIG_MANAGEMENT.md	White-label config management
references/SECURITY_OVERVIEW.md	Security architecture
references/QUEUE_WORKERS_SETUP.md	Production queue / systemd setup

License

AGPL v3 — see LICENSE.