# CLAUDE.md - Development Guide

## Commands

### Development
- Start all services: `composer dev` (runs server, queue, logs, and vite concurrently)
- Run Vite separately: `npm run dev`
- Build assets: `npm run build`
- Start server only: `php artisan serve`
- Run queue worker: `php artisan queue:listen --tries=1`
- Run database migrations: `php artisan migrate`
- Seed database with sample data: `php artisan db:seed`
- Clear cache: `php artisan cache:clear`
- Import camera data: `php artisan app:fetch-cameras`

### Testing
- Run all tests: `php artisan test`
- Run single test: `php artisan test --filter=TestName`
- Run feature tests: `php artisan test --testsuite=Feature`
- Run unit tests: `php artisan test --testsuite=Unit`
- Run with coverage: `php artisan test --coverage`

### Code Quality
- Format code: `./vendor/bin/pint`
- Format specific file: `./vendor/bin/pint path/to/file.php`
- List routes: `php artisan route:list`
- Generate IDE helper files: `php artisan ide-helper:generate`

### Git Commands
- Initialize a repository: `git init`
- Clone repository: `git clone <repository-url>`
- Check status: `git status`

#### Branching
- List all branches: `git branch`
- Create new branch: `git branch <branch-name>`
- Create and switch to new branch: `git checkout -b <branch-name>`
- Switch to branch: `git checkout <branch-name>`
- Delete branch: `git branch -d <branch-name>`
- Delete remote branch: `git push origin --delete <branch-name>`
- Rename current branch: `git branch -m <new-branch-name>`

#### Basic Workflow
- Stage all changes: `git add .`
- Stage specific file: `git add <file-path>`
- Commit staged changes: `git commit -m "Descriptive message"`
- Push to remote: `git push origin <branch-name>`
- Pull from remote: `git pull origin <branch-name>`
- Fetch all branches from remote: `git fetch --all`

#### Undoing Changes
- Discard changes in working directory: `git checkout -- <file-path>`
- Unstage file: `git reset HEAD <file-path>`
- Undo last commit (keeping changes): `git reset --soft HEAD~1`
- Undo last commit (discarding changes): `git reset --hard HEAD~1`
- Revert specific commit: `git revert <commit-hash>`

#### Stashing
- Stash changes: `git stash`
- List stashes: `git stash list`
- Apply most recent stash: `git stash apply`
- Apply specific stash: `git stash apply stash@{n}`
- Delete most recent stash: `git stash drop`
- Apply and delete most recent stash: `git stash pop`

#### History and Logs
- View commit history: `git log`
- View compact history: `git log --oneline`
- View history with graph: `git log --graph --oneline --all`
- Show changes in commit: `git show <commit-hash>`
- Show file at specific commit: `git show <commit-hash>:<file-path>`
- Show changes between commits: `git diff <commit1>..<commit2>`
- Show who modified a line: `git blame <file-path>`

#### Remote Operations
- List remotes: `git remote -v`
- Add remote: `git remote add <name> <url>`
- Change remote URL: `git remote set-url <name> <new-url>`
- Remove remote: `git remote remove <name>`
- Prune deleted remote branches: `git remote prune origin`

#### Merging and Rebasing
- Merge branch into current: `git merge <branch-name>`
- Merge without fast-forward: `git merge --no-ff <branch-name>`
- Abort merge: `git merge --abort`
- Rebase current branch: `git rebase <branch-name>`
- Interactive rebase: `git rebase -i <commit-hash>` or `git rebase -i HEAD~n`
- Continue after resolving conflicts: `git rebase --continue`
- Abort rebase: `git rebase --abort`

#### Advanced
- Create a tag: `git tag <tag-name>` or `git tag -a <tag-name> -m "message"`
- Push tags: `git push --tags`
- Cherry-pick commits: `git cherry-pick <commit-hash>`
- Clean untracked files: `git clean -fd`
- Create patch: `git format-patch <commit-hash>`
- Apply patch: `git apply <patch-file>` or `git am <patch-file>`
- Squash last n commits: `git rebase -i HEAD~n`
- Search commit messages: `git log --grep="search term"`

#### GitHub CLI Commands
- Log in to GitHub: `gh auth login`
- View current authenticated user: `gh auth status`
- List pull requests: `gh pr list`
- Create pull request: `gh pr create --title "Title" --body "Description"`
- Check out pull request: `gh pr checkout <number>`
- View pull request details: `gh pr view <number>`
- Merge pull request: `gh pr merge <number>`
- Close pull request: `gh pr close <number>`
- Create issue: `gh issue create --title "Title" --body "Description"`
- List issues: `gh issue list`
- View issue: `gh issue view <number>`
- Close issue: `gh issue close <number>`
- List workflows: `gh workflow list`
- Run workflow: `gh workflow run <workflow-name>`
- View workflow runs: `gh run list`
- Open repository in browser: `gh repo view --web`

### Git Workflows & Best Practices

#### Project Workflow
1. **Feature Branch Workflow**
   - Always create a dedicated branch for each feature/bugfix
   - Branch naming: `feature/feature-name` or `bugfix/issue-description`
   - Keep branches focused on a single task
   - Rebase your branch regularly against the main branch

2. **Commit Guidelines**
   - Write clear, concise commit messages in the imperative mood
   - Format: `<type>: <subject>` (e.g., `feat: add user authentication`)
   - Common types: feat, fix, docs, style, refactor, test, chore
   - Keep commits atomic and focused on a single change
   - Separate subject from body with a blank line for longer explanations

3. **Pull Request Process**
   - Create descriptive PR titles and detailed descriptions
   - Reference related issues using keywords (Fixes #123)
   - Include screenshots/videos for UI changes
   - Make sure tests pass before requesting review
   - Request review from appropriate team members
   - Address review comments promptly

4. **Code Review Guidelines**
   - Be respectful and constructive in comments
   - Focus on code, not the developer
   - Explain reasoning behind suggestions
   - Use questions rather than demands when possible
   - Approve once all concerns are addressed

5. **Handling Merge Conflicts**
   - Rebase your branch against the latest main branch
   - Resolve conflicts locally before pushing
   - Consult with code owners when resolving complex conflicts
   - Test thoroughly after resolving conflicts

## Code Style Guidelines
- PSR-4 autoloading standard for namespaces and classes
- 4-space indentation (2 spaces for YAML files)
- Strong typing: Always use PHP 8.2+ type hints and return types
- Livewire components for interactive UI (use #[Computed] attributes for reactive properties)
- Blade templates with Tailwind CSS for styling
- Laravel naming conventions:
  - Controllers: PascalCase, singular nouns (UserController)
  - Models: PascalCase, singular nouns (User)
  - Database: snake_case, plural nouns (users)
  - Variables: camelCase
- Dependency injection over facades when possible (especially in tests)
- Comprehensive PHPDoc blocks for classes, methods, and properties
- Use environment variables for configuration (never hardcode credentials)
- Explicit error handling with try/catch blocks and custom exceptions where appropriate