ronald/timebank-cc-public
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
main
timebank-cc-public/CLAUDE.md
Ronald Huynen 2547717edb Initial commit
2026-03-23 21:37:59 +01:00

10 KiB
Raw Permalink Blame History

CLAUDE.md

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

Development Commands

Laravel Application

# 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

# 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

# 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

# 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

# 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

# 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:

'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:

// 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:

// Hide "Research" link
['route' => 'static-research', 'title' => 'Research', 'order' => 5, 'visible' => false],

Adding custom links:

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

Authentication-required links:

// 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 View Git Blame Copy Permalink