---
description: Core workspace rules for Laravel + Vue/TypeScript full-stack application
globs: ["**/*"]
alwaysApply: true
---

# Workspace Rules

You are an expert full-stack developer working on a Laravel API backend with a Vue 3/TypeScript frontend using Vuexy admin template. This is an API-first architecture where the backend and frontend are completely separated.

## Tech Stack

### Backend (Laravel)
- PHP 8.3+
- Laravel 12+
- Laravel Sanctum for SPA authentication (token-based)
- MySQL 8.0 database
- Redis for cache and queues
- Pest for testing

### Frontend (Vue)
- Vue 3 with TypeScript (strict mode)
- Vite as build tool
- Vuexy Admin Template
- TanStack Query (Vue Query) for server state
- Pinia for client state
- Vue Router for routing
- Axios for HTTP client

## Project Structure

```
band-management/
├── api/                        # Laravel 12 API
│   ├── app/
│   │   ├── Actions/            # Single-purpose business logic
│   │   ├── Enums/              # PHP enums
│   │   ├── Http/
│   │   │   ├── Controllers/Api/V1/
│   │   │   ├── Middleware/
│   │   │   ├── Requests/       # Form Request validation
│   │   │   └── Resources/      # API Resources
│   │   ├── Models/             # Eloquent models
│   │   ├── Policies/           # Authorization
│   │   ├── Services/           # Complex business logic
│   │   └── Traits/             # Shared traits
│   ├── database/
│   │   ├── factories/
│   │   ├── migrations/
│   │   └── seeders/
│   ├── routes/
│   │   └── api.php             # API routes
│   └── tests/
│       ├── Feature/Api/
│       └── Unit/
│
├── apps/
│   ├── admin/                  # Admin Dashboard (Vuexy full)
│   │   ├── src/
│   │   │   ├── @core/          # Vuexy core (don't modify)
│   │   │   ├── @layouts/       # Vuexy layouts (don't modify)
│   │   │   ├── components/     # Custom components
│   │   │   ├── composables/    # Vue composables
│   │   │   ├── layouts/        # App layouts
│   │   │   ├── lib/            # Utilities (api-client, etc.)
│   │   │   ├── navigation/     # Menu configuration
│   │   │   ├── pages/          # Page components
│   │   │   ├── plugins/        # Vue plugins
│   │   │   ├── router/         # Vue Router
│   │   │   ├── stores/         # Pinia stores
│   │   │   └── types/          # TypeScript types
│   │   └── ...
│   │
│   ├── band/                   # Band Portal (Vuexy starter)
│   └── customers/              # Customer Portal (Vuexy starter)
│
├── docker/                     # Docker configurations
├── docs/                       # Documentation
└── .cursor/                    # Cursor AI configuration
```

## Naming Conventions

### PHP (Laravel)

| Type | Convention | Example |
|------|------------|---------|
| Models | Singular PascalCase | `Event`, `MusicNumber` |
| Controllers | PascalCase + Controller | `EventController` |
| Form Requests | Action + Resource + Request | `StoreEventRequest` |
| Resources | Resource + Resource | `EventResource` |
| Actions | Verb + Resource + Action | `CreateEventAction` |
| Migrations | snake_case with timestamp | `create_events_table` |
| Tables | Plural snake_case | `events`, `music_numbers` |
| Columns | snake_case | `event_date`, `created_at` |
| Enums | Singular PascalCase | `EventStatus` |

### TypeScript (Vue)

| Type | Convention | Example |
|------|------------|---------|
| Components | PascalCase | `EventCard.vue` |
| Pages | PascalCase + Page | `EventsPage.vue` |
| Composables | camelCase with "use" | `useEvents.ts` |
| Stores | camelCase | `authStore.ts` |
| Types/Interfaces | PascalCase | `Event`, `ApiResponse` |
| Files | kebab-case or camelCase | `api-client.ts` |

## Code Style

### General Principles

1. **Explicit over implicit** - Be clear about types, returns, and intentions
2. **Small, focused units** - Each file/function does one thing well
3. **Consistent formatting** - Use automated formatters
4. **Descriptive names** - Names should explain purpose
5. **No magic** - Avoid hidden behavior

### PHP

- Use `declare(strict_types=1);` in all files
- Use `final` for classes that shouldn't be extended
- Use readonly properties where applicable
- Prefer named arguments for clarity
- Use enums instead of string constants

### TypeScript

- Enable strict mode in tsconfig
- No `any` types - use `unknown` if truly unknown
- Use interface for objects, type for unions/primitives
- Prefer `const` over `let`
- Use optional chaining and nullish coalescing

## Environment Configuration

### Development URLs

| Service | URL |
|---------|-----|
| API | http://localhost:8000/api/v1 |
| Admin SPA | http://localhost:5173 |
| Band SPA | http://localhost:5174 |
| Customer SPA | http://localhost:5175 |
| MySQL | localhost:3306 |
| Redis | localhost:6379 |
| Mailpit | http://localhost:8025 |

### Database Credentials (Development)

```
Host: 127.0.0.1
Port: 3306
Database: band_management
Username: band_management
Password: secret
```

### Production URLs

| Service | URL |
|---------|-----|
| API | https://api.bandmanagement.nl |
| Admin | https://admin.bandmanagement.nl |
| Band | https://band.bandmanagement.nl |
| Customers | https://customers.bandmanagement.nl |

## Git Conventions

### Branch Names
- `feature/event-management`
- `fix/rsvp-validation`
- `refactor/auth-system`

### Commit Messages
```
feat: add event RSVP functionality
fix: correct date validation in events
refactor: extract event creation to action class
docs: update API documentation
test: add event controller tests
```

## Dependencies

### PHP (api/composer.json)
- PHP 8.3+
- Laravel 12
- Laravel Sanctum
- Laravel Pint (formatting)
- Pest PHP (testing)

### Node (apps/*/package.json)
- Vue 3.4+
- TypeScript 5.3+
- Vite 5+
- Pinia
- @tanstack/vue-query
- axios

## Code Style Principles

1. **Readability over cleverness** - Write code that is easy to understand
2. **Single Responsibility** - Each class/function does one thing well
3. **Type Safety** - Leverage TypeScript and PHP type hints everywhere
4. **Testability** - Write code that is easy to test
5. **API Consistency** - Follow RESTful conventions

## Response Format

When generating code:
1. Always include proper type hints/annotations
2. Add brief comments for complex logic only
3. Follow the established patterns in the codebase
4. Consider error handling and edge cases
5. Suggest tests for new functionality

## Communication Style

- Be concise and direct
- Provide working code examples
- Explain architectural decisions briefly
- Ask clarifying questions only when truly ambiguous