Skip to content

CLAUDE.md

Latest commit

 

History

History
215 lines (169 loc) · 7.62 KB

CLAUDE.md

File metadata and controls

215 lines (169 loc) · 7.62 KB

CLAUDE.md

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

CRITICAL: Docker Commands

NEVER use docker-compose or docker exec directly. ALWAYS use task commands.

# Starting containers
task docker:up-core      # Core services only
task docker:up-debug     # Core + debug tools (phpMyAdmin, Mailhog)
task docker:up-discourse # Core + Discourse
task docker:up-all       # All services

# Stopping containers
task docker:down-core
task docker:down-debug
task docker:down-discourse
task docker:down-all

# Running commands in container
task docker:run:bash -- "npm run dev"      # Run bash command
task docker:run:artisan -- migrate         # Run artisan command
task docker:shell                          # Open shell in container

# Testing
task docker:test:phpunit      # Run PHP tests
task docker:test:jest         # Run JS tests
task docker:test:playwright   # Run e2e tests

# Vite dev server (HMR)
task docker:vite:start        # Start Vite in background
task docker:vite:stop         # Stop Vite
task docker:vite              # Start Vite in foreground (interactive)

# Logs and debugging
task docker:logs              # View container logs

Project Overview

Restarters.net is a suite of software for the repair community that brings together community repair enthusiasts and activists. It combines three core modules:

  • The Fixometer - engine for organizing community repair events and recording their impact
  • Restarters Talk - space for local and global discussion of community repair (powered by Discourse)
  • Restarters Wiki - collectively produced knowledge base of advice and support (powered by MediaWiki)

This is a Laravel 9 application with PHP 8+ that integrates with external services including Discourse, MediaWiki, and WordPress.

Development Commands

Local Development Setup

Prerequisites: Install Task - the project uses Taskfile for Docker management.

See docs/local-development.md for full setup instructions.

# Start Docker environment (uses Task - do NOT use docker-compose directly)
task docker:up-core      # Core only (app + database)
task docker:up-debug     # With phpMyAdmin and Mailhog
task docker:up-discourse # With Discourse integration
task docker:up-all       # All services

# Stop Docker environment
task docker:down-core    # Stop core services
task docker:down-debug   # Stop debug services
task docker:down-all     # Stop all services

# Other Docker commands
task docker:logs         # View container logs
task docker:shell        # Open shell in container
task docker:run:artisan -- migrate  # Run artisan commands
task docker:run:bash -- "command"   # Run bash commands

# Run Vite for HMR (hot module replacement)
task docker:run:bash -- "npm run dev"

# The application will be available at:
# - Restarters: http://localhost:8001 (Admin: jane@bloggs.net / passw0rd)
# - phpMyAdmin: http://localhost:8002 (Host: restarters_db, User: root, Pass: s3cr3t)
# - Mailhog: http://localhost:8025
# - Discourse: http://localhost:8003

Common Development Commands

# Install PHP dependencies
composer install

# Install and build frontend assets
npm install
npm run dev          # Development build
npm run watch        # Watch for changes
npm run production   # Production build

# Laravel commands
php artisan migrate            # Run database migrations
php artisan migrate:fresh     # Fresh migration (drops all tables)
php artisan seed              # Run database seeders
php artisan tinker            # Laravel REPL
# JavaScript translation files are now auto-generated by Vite laravel-translator plugin
php artisan translations:check # Check translation completeness

# Generate application key (for new installs)
php artisan key:generate

Testing

# Run PHP unit tests (inside Docker container)
task docker:shell
# Then inside container:
export DB_TEST_HOST=restarters_db
./vendor/bin/phpunit

# Run specific test file
./vendor/bin/phpunit tests/Feature/Events/AddRemoveVolunteerTest.php

# Run specific test method
./vendor/bin/phpunit --filter testMethodName

# Run JavaScript tests
npm run jest

# Run Playwright end-to-end tests
npm test

Code Quality

# PHP CS Fixer (code style)
./tools/php-cs-fixer.phar fix

# Check code style without fixing
./tools/php-cs-fixer.phar fix --dry-run --diff

Architecture Overview

Core Domain Models

  • Device (app/Device.php) - Represents items brought to repair events with repair status, categories, and impact calculations
  • Group (app/Group.php) - Repair groups that organize events, with location, network affiliations, and member management
  • Party (app/Party.php) - Repair events hosted by groups, with attendee management and statistics calculation
  • User (app/User.php) - Platform users with roles (Admin, Host, Restarter, NetworkCoordinator)
  • Network (app/Network.php) - Regional networks that groups can belong to
  • Category (app/Category.php) - Device categories for classification and impact calculations

Key Relationships

  • Groups have many Events (Parties)
  • Events have many Devices
  • Users belong to Groups through UserGroups with roles
  • Groups belong to Networks through group_network pivot table
  • Devices belong to Categories and have repair status tracking

External Integrations

  • Discourse API - User management, group creation, SSO integration
  • MediaWiki API - User account sync and authentication
  • WordPress XML-RPC - Content publishing for events and groups
  • Geocoding - Location services for groups and events
  • Drip - Email marketing integration

Database Design

  • Uses Laravel migrations in database/migrations/
  • Soft deletes enabled for key models (Events, Users)
  • Audit trail via owen-it/laravel-auditing package
  • JSON columns for flexible network_data storage

Frontend Stack

  • Vue 2 components for interactive features
  • Laravel Mix for asset compilation
  • Bootstrap 4 for styling
  • SCSS for styles in resources/sass/
  • Multiple build targets: main app, global styles, wiki styles

Permission System

  • Role-based permissions via custom app/Role.php and app/Permissions.php
  • Middleware for authentication and authorization
  • Network coordinators have regional permissions
  • Group-level host permissions

File Structure Patterns

  • Controllers follow resource naming (e.g., DeviceController, GroupController)
  • Events and Listeners in app/Events/ and app/Listeners/
  • Custom artisan commands in app/Console/Commands/
  • API controllers separate from web controllers
  • Blade templates in resources/views/ with partials organization

Testing Strategy

  • PHPUnit for backend unit and feature tests
  • Jest for JavaScript component testing
  • Playwright for end-to-end testing
  • Database factory patterns for test data

Important Configuration

  • Environment variables critical for external service integration
  • Docker setup provides development databases and services
  • Queue processing for background jobs (Discourse, WordPress sync)
  • Caching used extensively for performance (categories, statistics)
  • Timezone handling important for global event management

Development Notes

  • The codebase uses custom helper functions in app/Helpers/
  • Translation files support multiple locales in lang/ directory
  • Image handling via intervention/image with custom sizing
  • Custom validation rules in app/Rules/
  • Event-driven architecture with model observers
  • Only translate fr and fr-BE

Development Warnings

  • Don't try to test changes when you're running on Windows.

Workflow Guidelines

  • When you create files, add them to git