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