250 lines
9.6 KiB
Markdown
250 lines
9.6 KiB
Markdown
# Timebank.cc
|
|
|
|
[](https://laravel.com)
|
|
[](https://php.net)
|
|
[](CHANGELOG.md)
|
|
[](LICENSE)
|
|
|
|
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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```sql
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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
|
|
```bash
|
|
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/`):
|
|
```bash
|
|
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`)
|
|
|
|
```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](LICENSE).
|