# CLAUDE.md

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

## Project Overview

This is a multi-domain Laravel application called "pr-copilot" that supports different domains with distinct themes and styling. The application uses Laravel with Livewire, Volt, and Fortify for authentication, along with Flux UI components.

### Supported Domains

- **Main Portal**: pr-copilot.test - Main admin portal page
- **Presseecho**: presseecho.test - Landing page with presseecho theme
- **Business Portal**: businessportal24.test - Landing page with business portal theme

## Development Commands

### Installation & Setup

```bash
composer install
npm install
php artisan key:generate
php artisan migrate
php artisan migrate --seed  # Run seeders for roles and permissions
```

### Asset Compilation

```bash
npm run dev:portal       # Start Portal dev server (Port 5177)
npm run dev:web          # Start Web dev server (Port 5178)
npm run dev:all          # Start both dev servers concurrently (recommended)
npm run build            # Production build (all)
npm run build:portal     # Portal-specific assets
npm run build:web        # Web-specific assets
```

### Development Server

```bash
php artisan serve        # Start Laravel development server
composer run dev         # Start full development stack (server, queue, logs, vite)
```

### Testing

```bash
composer run test        # Run Pest tests (clears config first)
php artisan test         # Direct Laravel test command
php artisan test --filter TestName  # Run specific test
```

### Domain Management

```bash
php artisan domains:generate-favicons  # Generate placeholder favicons for all domains
```

## Architecture

### Domain-Based Theme System

The application uses a sophisticated domain-based theme system that determines styling and assets at runtime:

**How it works:**
1. `ThemeServiceProvider` detects the incoming domain from the HTTP request
2. Looks up domain config in `/config/domains.php` by matching `domain_name`
3. Sets theme variables globally via `View::share()` and `config()`
4. Vite automatically loads the correct build directory based on `assets_dir`

**Key configuration** (`/config/domains.php`):
- Each domain has: `domain_name`, `url`, `theme`, `view_prefix`, `assets_dir`, `color_scheme`, `font`
- Portal domain uses `build/portal` assets
- Web domains (presseecho, businessportal24) share `build/web` assets but load different CSS theme files

**Development features:**
- Simulate any domain locally: Set `DEV_SIMULATE_DOMAIN=true` and `DEV_SIMULATED_DOMAIN=presseecho.test` in `.env`
- Theme override via URL: Add `?theme=presseecho` to test different themes

### Key Components

- **Livewire Components**: Located in `app/Livewire/` with the following structure:
  - `app/Livewire/Actions/` - Reusable actions (e.g., Logout)
  - Auth components in `resources/views/livewire/auth/` (login, register, password reset, etc.)
  - Settings components in `resources/views/livewire/settings/` (profile, password, appearance)
  - Admin components in `resources/views/livewire/admin/` (users management)
  - Web components in `resources/views/livewire/web/` (frontend features)
- **Volt Components**: Single-file Livewire components using functional API for rapid development
- **Flux UI**: Premium UI component library for consistent design (Portal only)
- **Multi-Build System**: Separate Vite configurations for different asset bundles

### Authentication & Authorization

- **Laravel Fortify**: Handles authentication features
- **Laravel Sanctum**: API token authentication
- **Spatie Permissions**: Role and permission management system

### Asset Management

The project uses a **dual-port Vite setup** with separate configurations:

- **Portal (Backend)**: `vite.portal.config.js` - Port 5177, includes FluxUI
- **Web (Frontend)**: `vite.web.config.js` - Port 5178, no FluxUI
- **Tailwind Configs**: `tailwind.portal.config.js` and `tailwind.web.config.js`

**Why two ports?** Vite can only run one configuration at a time. The portal uses FluxUI components while web domains don't, requiring separate builds. Web domains (presseecho & businessportal24) share the same Vite server and differ only in CSS variables loaded at runtime via `ThemeServiceProvider`.

**Build directories**:
- Portal assets → `public/build/portal/`
- Web assets → `public/build/web/`

### Database

- **SQLite** for development (`database/database.sqlite`)
- **Migrations**: Users (with 2FA columns), cache, jobs, personal access tokens
- **Seeders**: `RolesAndPermissionsSeeder` - Run with `php artisan migrate --seed`

### Testing Framework

- **Pest PHP** (v3.8+) - Modern testing framework built on PHPUnit
- Configuration: `phpunit.xml` and `tests/Pest.php`
- Test database: Uses `DB_DATABASE=testing` environment (configured in phpunit.xml)
- Test directories: `tests/Feature/` (authentication, dashboard, settings) and `tests/Unit/`

## Important Files & Configuration

- **Domain System**:
  - `/config/domains.php` - Domain and theme configuration
  - `/app/Providers/ThemeServiceProvider.php` - Core theme switching logic at runtime
  - `/routes/domains.php` - Domain-specific routing

- **Routes**:
  - `/routes/web.php` - Public web routes
  - `/routes/auth.php` - Authentication routes
  - `/routes/admin.php` - Admin portal routes
  - `/routes/api.php` - API endpoints with Sanctum protection

- **Views Structure**:
  - `resources/views/web/` - Frontend domain views (presseecho, businessportal24)
  - `resources/views/admin/` - Backend portal views
  - `resources/views/components/` - Shared components across all domains
  - `resources/views/components/layouts/` - Layout components (app, auth)
  - `resources/views/livewire/` - Livewire components (auth, settings, admin, web)

- **Vite & Assets**:
  - `vite.portal.config.js` - Backend/Portal build configuration (Port 5177)
  - `vite.web.config.js` - Frontend/Web build configuration (Port 5178)
  - `tailwind.portal.config.js` and `tailwind.web.config.js` - Separate Tailwind configs
  - `resources/css/portal.css` - Portal styles with FluxUI
  - `resources/css/web/theme-*.css` - Theme-specific CSS for web domains

- **Documentation**:
  - `DOMAINS-CONFIG.md` - Detailed domain setup instructions
  - `FORTIFY-SANCTUM-SETUP.md` - Authentication setup guide
  - `VITE-SETUP.md` - Dual-port Vite architecture explanation