timebank-cc-public/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

### Laravel Application
```bash
# Start development server
php artisan serve

# Start queue worker for emails and background jobs
php artisan queue:work

# Start websocket server for real-time messaging
php artisan reverb:start

# Clear and rebuild Laravel cache
php artisan optimize
```

### Frontend Assets
```bash
# Development server with hot module replacement
npm run dev

# Production build
npm run build
# Or use aliases:
npm run prod
npm run production
```

### Database & Search
```bash
# Run migrations and seeders
php artisan migrate
php artisan db:seed

# Run db:seed with root privileges (required for DROP operations)
# Use this when the app's MySQL user has limited permissions
./seed.sh

# Apply database updates (for schema changes and data migrations)
php artisan database:update

# Rebuild Elasticsearch indices (requires significant memory/CPU)
php artisan scout:import

# Re-index specific models
php artisan scout:import "App\Models\User"
php artisan scout:import "App\Models\Post"
```

### Testing
```bash
# Run all tests
php artisan test

# Run specific test file
php artisan test tests/Feature/AuthenticationTest.php

# Run security tests
php artisan test --filter SearchXssProtectionTest
php artisan test --filter PostContentXssProtectionTest
```

### Deployment
```bash
# Full deployment (local environment)
./deploy.sh

# Full deployment (server environment - uses .env configuration)
./deploy.sh -e server

# Skip migrations
./deploy.sh -m

# Skip npm build
./deploy.sh -n

# HTMLPurifier cache setup (automatic during deploy, or run manually)
./deployment-htmlpurifier-fix.sh
```

### Configuration Management
```bash
# Merge new configuration keys from .example files into active configs
php artisan config:merge --all

# Preview changes without applying (recommended first)
php artisan config:merge --all --dry-run

# Merge specific config file
php artisan config:merge timebank_cc

# Restore config from backup
php artisan config:merge --restore
```

**Quick Reference:**
- Safely merges new keys from `.example` files without overwriting custom values
- Automatically prompted during `deploy.sh` deployment
- Creates backups in `storage/config-backups/` before changes
- See `references/CONFIG_MANAGEMENT.md` for complete documentation

## Core Architecture

### Multi-Profile System
The application uses a polymorphic profile system where users can switch between different profile types:
- **User**: Individual profiles with personal time accounts
- **Organization**:Community profiles with higher transaction limits
- **Bank**: Financial institution profiles with currency creation/removal permissions
- **Admin**: Administrative profiles without payment accounts

Profile switching is session-based using Laravel's multi-guard authentication with `SwitchGuardTrait`.

### Account & Transaction Model
- **Accounts**: Polymorphic relationship to Users/Organizations/Banks
- **Transactions**: Immutable records using MySQL window functions for balance calculations
- **Database Protection**: Transaction table has DELETE/UPDATE restrictions at MySQL user level
- **Transaction Types**: Configurable (worked time, gifts, donations, currency creation/removal, migrations)

### Key Configuration
The application uses a white-label configuration system that allows platform-specific customization:
- **Configuration Files**: Located in `config/` directory (e.g., `config/timebank-default.php`, `config/timebank-cc.php`)
- **Environment Variable**: Set `TIMEBANK_CONFIG` in `.env` to specify which config file to use (without .php extension)
- **Helper Function**: Use `timebank_config('key.path')` to access platform-specific configuration values
- **Default Config**: `timebank-default` (can be customized by copying and modifying for new platforms)

Configuration includes:
- Account balance limits per profile type
- Transaction type permissions
- Profile visibility settings (public/private balances)
- Validation rules and name restrictions
- Search boost factors and Elasticsearch settings
- Platform-specific translations (names, currency, terminology)
- Footer navigation (sections, links, ordering, visibility)

**Creating a New White-Label Instance:**
1. Copy `config/timebank-default.php` to `config/your-platform.php`
2. Customize settings and translations in the new file
3. Set `TIMEBANK_CONFIG=your-platform` in `.env`
4. Use the existing `timebank_config()` helper throughout the codebase

### Frontend Stack
- **Livewire 3**: Server-side reactive components
- **TailwindCSS + WireUI**: Utility-first CSS with pre-built components
- **Alpine.js**: Minimal client-side JavaScript
- **Vite**: Modern asset bundling and development server

### Real-time Features
- **Laravel Reverb**: WebSocket server for messaging and presence
- **WireChat Package**: Chat/messaging functionality
- **Presence System**: Online user tracking with `HasPresence` trait

### Search System
- **Elasticsearch**: Full-text search with Scout integration
- **Configurable Boosting**: Different boost factors for fields and models in `config/timebank-cc.php`
- **Multi-language**: Search across 5 languages (en, nl, de, es, fr)

### Important Database Requirements
- MySQL 8.0+ or MariaDB 10.2+ required for window function support in transaction balance calculations
- Redis required for caching and real-time features
- Elasticsearch required for search functionality

### Security Considerations
- Profile names have extensive validation to prevent URL path conflicts
- Multi-guard authentication system prevents unauthorized profile access
- Transaction immutability enforced at database user permission level

## UI Styling and Theme System

### Theme System Overview
The application uses a multi-theme system allowing different installations to have unique visual identities. Themes are configured in `config/themes.php` and activated via the `TIMEBANK_THEME` environment variable.

**Available Themes:** timebank_cc (default), uuro, vegetable, yellow

### UI Component Patterns
**IMPORTANT:** All new views and UI components must follow the patterns documented in `references/STYLE_GUIDE.md`. This style guide is the authoritative reference for:

- Page layout structure and spacing
- Data tables with sorting, pagination, and actions
- Search and filter interfaces
- Modal dialogs (standard, confirmation, preview)
- Form elements and validation
- Button styles and loading states
- Status badges and indicators
- Theme-aware color usage

**Reference Implementation:** `resources/views/livewire/mailings/manage.blade.php` demonstrates all core UI patterns in production use.

### Theme-Aware Styling Rules
When creating or modifying views:

1. **Use theme color classes:** `bg-theme-brand`, `text-theme-primary`, `border-theme-border`
2. **Use theme helper functions in PHP:** `theme_color('primary.500')`, `theme_font('font_family_body')`
3. **Follow component patterns from STYLE_GUIDE.md** for tables, modals, forms, buttons
4. **Test across all themes** by switching `TIMEBANK_THEME` environment variable
5. **Use Jetstream button components:** `<x-jetstream.button>`, `<x-jetstream.secondary-button>`, `<x-jetstream.danger-button>`, `<x-jetstream.light-button>`

### Building New Views Checklist
- [ ] Review STYLE_GUIDE.md for applicable patterns
- [ ] Reference mailings/manage.blade.php for similar UI elements
- [ ] Use theme-aware color classes throughout
- [ ] Follow standard spacing scale (mt-12, mb-6, space-x-3, etc.)
- [ ] Include loading states for Livewire actions
- [ ] Add proper focus states and accessibility attributes
- [ ] Test with all 4 themes (timebank_cc, uuro, vegetable, yellow)

## White-Label Customization

### Footer Navigation
The footer navigation is fully configurable per platform via the `footer` configuration key in your platform config file (e.g., `config/timebank-default.php`).

**Configuration Structure:**
```php
'footer' => [
    'sections' => [
        [
            'title' => 'Section Title',  // Translation key
            'order' => 1,                 // Display order
            'visible' => true,            // Show/hide section
            'links' => [
                [
                    'route' => 'route-name',        // Laravel route name
                    'title' => 'Link Title',        // Translation key
                    'order' => 1,                   // Display order
                    'visible' => true,              // Show/hide link
                    'auth_required' => false,       // Optional: only show to authenticated users
                ],
                [
                    'url' => 'https://example.com', // Optional: custom URL instead of route
                    'title' => 'External Link',
                    'order' => 2,
                    'visible' => true,
                ],
            ],
        ],
    ],
    'tagline' => 'Your time is currency',  // Footer tagline translation key
],
```

**Customization Examples:**

*Reordering sections:*
```php
// Move "Help" section to first position
['title' => 'Help', 'order' => 1, 'visible' => true, 'links' => [...]],
['title' => 'Who we are', 'order' => 2, 'visible' => true, 'links' => [...]],
```

*Hiding specific links:*
```php
// Hide "Research" link
['route' => 'static-research', 'title' => 'Research', 'order' => 5, 'visible' => false],
```

*Adding custom links:*
```php
// Add external link
['url' => 'mailto:contact@yourplatform.com', 'title' => 'Email Us', 'order' => 3, 'visible' => true],
```

*Authentication-required links:*
```php
// Only show to logged-in users
['route' => 'static-messenger', 'title' => 'Chat messenger', 'order' => 2, 'visible' => true, 'auth_required' => true],
```

## Workflow Guidelines
Follow the standard workflow defined in `CLAUDE_WORKFLOW.md`:
1. Plan tasks using TodoWrite tool for active management
2. Document planning and reviews in `todo.md` file
3. Get user verification before beginning work
4. Keep changes simple with minimal impact
5. Do not use emoji's in front-end applications unless requested
6. Provide high-level progress updates
7. Never edit files in vendor folders, always use vendor update safe overrides