Initial commit
This commit is contained in:
Ronald Huynen
249
README.md
Normal file
249
README.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user