### Server-Side - **Laravel Exceptions**: Automatic handling - **Validation**: Form request validation - **Logging**: Laravel log channels - **Debug Mode**: Spatie Ignition for development ### Client-Side - **AJAX Errors**: Axios interceptors - **Validation Feedback**: Bootstrap form validation - **User Notifications**: Alert messages

### Current Scale - **Target**: Single user - **Concurrent Users**: 1 - **Data Volume**: Thousands of tasks/projects - **Performance**: Adequate for personal use ### Growth Paths **If needed for multiple users**: 1. Add user_id to all tables 2. Implement row-level security 3. Add authorization policies 4. Consider caching layer 5. Optimize queries with pagination **If data grows significantly**: 1. Implement pagination everywhere 2. Add search indexes (Elasticsearch) 3. Archive old completed...

### Query Optimization **Eager Loading**: ```php Task::with(['projects', 'contexts', 'zones'])->get(); ``` Prevents N+1 query problems **Global Scopes**: Automatic filtering reduces result sets **Indexes**: Foreign keys and commonly queried columns indexed ### Caching Strategy - **Current**: Minimal caching (database-driven) - **Future**: Could add query caching for lookups - **Session**: Stores user session data ### Asset Optimization - **Vite**: Bundles and minifies JavaScript/CSS - **P...

### Schema Design Principles 1. **Normalization**: Third normal form (3NF) 2. **Referential Integrity**: Foreign key constraints 3. **Soft Deletes**: `deleted_at` for reversible deletions 4. **Timestamps**: `created_at`, `updated_at` on all tables 5. **Pivot Tables**: For many-to-many relationships ### Migration Strategy - **Evolutionary**: 94 migrations showing incremental development - **Version Control**: All schema changes tracked - **Rollback**: Down methods for reversibility - **Indexin...

### Authentication - **Method**: Laravel Sanctum (session-based) - **Storage**: Sessions in database or file - **Middleware**: `auth` middleware protects routes ### Authorization - **Level**: Controller-based (implicit) - **Pattern**: Single-user assumption (no explicit permission checks) - **Future**: Could add Policies/Gates for multi-user

### Template Structure ``` resources/views/ ├── layouts/ │ └── app.blade.php # Master layout ├── tasks/ │ ├── index.blade.php # Task list │ ├── create.blade.php # Task creation │ └── edit.blade.php # Task editing ├── projects/ │ ├── index.blade.php │ ├── create.blade.php │ └── ... └── [other entity views...] ``` ### JavaScript Organization ``` resources/js/ ├── app.js # Main entry point, Axios setup ├── bootstrap.js # Bootstrap f...

### 1. Many-to-Many with Pivot Data **Example**: Tasks ↔ Projects ```php // Pivot table: project_task // Pivot data: sort_order, is_parallel $task->projects()->attach($projectId, [ 'sort_order' => 1, 'is_parallel' => true ]); ``` **Usage**: Task can belong to multiple projects, projects can have multiple tasks ### 2. Hierarchical (Self-Referential) **Example**: Projects containing Projects ```php // project_project pivot table $project->childProjects() // Child projects $project->...

### 1. Standard CRUD Flow ``` User Request → Route → Controller → Model → Database ↓ Response ← View ← Controller ← Model ``` ### 2. Service-Mediated Flow ``` User Request → Route → Controller → Service → Multiple Models → Database ↓ Response ← View ← Controller ← Service (aggregated data) ``` ### 3. AJAX Enhancement Flow ``` User Action (JS) → Axios Request → Controller → Model → Database ...

### Controllers (42 total - Post-Refactoring) **Responsibility**: Handle HTTP requests, delegate to services, return responses **Pattern**: Specialized controllers following Single Responsibility Principle **Location**: `app/Http/Controllers/` **Controller Organization by Domain**: | Domain | Count | Controllers | |--------|-------|-------------| | **Task** | 9 | TaskController, TaskFilterController, TaskConversionController, TaskDependencyController, TaskDocumentController, TaskChunkContro...

``` ┌──────────────────────────────────────────────────────┐ │ Presentation Layer │ │ - Blade Templates (resources/views/) │ │ - JavaScript (resources/js/) + Axios │ │ - CSS (resources/css/) + Bootstrap 5 │ └─────────────────┬────────────────────────────────────┘ │ ┌─────────────────▼────────────────────────────────────┐ │ Application Layer │ │ - Routes (route...

### 1. Monolithic Architecture **Decision**: Single Laravel application containing all functionality **Rationale**: - Single-user application doesn't require microservices complexity - Simpler deployment and maintenance - Efficient database transactions across features - Faster development iteration **Trade-offs**: - Limited horizontal scaling (not a concern for single-user) - All features coupled in one codebase - Benefits: Simplicity, maintainability, performance ### 2. Server-Side Renderi...

This application follows a **traditional Laravel MVC architecture** with **service layer abstraction** for complex business logic. It is a **monolithic, server-rendered web application** optimized for single-user personal productivity management.

1. Resolve the project root (the current working directory) and run: ```bash .claude/playwright-disable.sh ``` If `.claude/playwright-disable.sh` does not exist, use `.claude/switch-mcp.sh none` as fallback. 2. Inform the user that Playwright will be disabled on next restart. 3. Ask the user if they want to restart now with `/restart` or `/exit`.

Launches the codebase-janitor agent to scan for and clean up: - Root-level .md/.txt/.sh/.php/.html files dumped by agents - Tool output junk (phpstan results, modal outputs) - Config variant clutter (phpstan-*.neon duplicates) - Orphan directories (filedump/, .work-plans/, patches/) - Coordination files at wrong locations **Safety:** Dry-run by default, git-based revert for all actions, protected file allowlist.

1. Resolve the project root (the current working directory) and run: ```bash .claude/switch-mcp.sh playwright ``` If `.claude/switch-mcp.sh` does not exist in the current project, check `/var/www/reportmaker/.claude/switch-mcp.sh` as fallback. 2. Inform the user that Playwright will be enabled on next restart. 3. Ask the user if they want to restart now with `/restart` or `/exit`.

1. Resolve the project root (the current working directory) and run: ```bash .claude/mysql-disable.sh ``` If `.claude/mysql-disable.sh` does not exist, use `.claude/switch-mcp.sh none` as fallback. 2. Inform the user that MySQL MCP will be disabled on next restart. 3. Ask the user if they want to restart now with `/restart` or `/exit`.

Only if ALL true: 1. Changes are PURELY backend (no views, routes, controllers) 2. No migrations affecting displayed data 3. No asset changes (JS/CSS) 4. No navigation/menu changes If in doubt → ask for frontend validation.

[What you actually verified — syntax, tests, build] FRONTEND VALIDATION REQUIRED I can ONLY verify backend/build. Frontend consequences are INVISIBLE to me. YOU MUST TEST: - [Affected Page](https://reportmaker.magitek.no/path) — Test [specific thing] CHECKLIST: - [ ] Pages load without errors - [ ] No JavaScript console errors - [ ] Data displays correctly - [ ] Visual appearance correct Current Status: Waiting for your validation ```

```

Never say: "Fixed!", "BUG CRUSHED", "Everything is working", "Ready to merge", "All done!" These are lies — you cannot verify frontend.

- Frontend display (you cannot see how pages render) - JavaScript runtime behavior - CSS/Layout visual regressions - User experience issues

1. Resolve the project root (the current working directory) and run: ```bash .claude/switch-mcp.sh serena ``` If `.claude/switch-mcp.sh` does not exist in the current project, check `/var/www/reportmaker/.claude/switch-mcp.sh` as fallback. 2. Inform the user that Serena will be enabled on next restart. 3. Ask the user if they want to restart now with `/restart` or `/exit`.

```bash chmod 644 path/to/file.php ```

PHP, Blade, JavaScript, TypeScript, CSS, JSON, YAML, Markdown — everything in app/, resources/, config/, routes/, coordination/, .claude/.

| Situation | Action | |-----------|--------| | After Write tool creates file | fix-permissions.sh | | Before git commit | fix-permissions.sh --check | | "Permission denied" in logs | fix-permissions.sh | | "Kunne ikke laste detaljer" | fix-permissions.sh |

```bash ./coordination/scripts/fix-permissions.sh ```

600 (rw-------) → must be 644 (rw-r--r--) `www-data` is in group/others and MUST read PHP, Blade, JS, JSON files.

Claude Code Write tool creates files with **600 permissions** (owner-only). `www-data` cannot read 600 files → "Permission denied", "Kunne ikke laste detaljer", Blade rendering errors.

1. Resolve the project root (the current working directory) and run: ```bash .claude/switch-mcp.sh lighthouse ``` If `.claude/switch-mcp.sh` does not exist in the current project, check `/var/www/reportmaker/.claude/switch-mcp.sh` as fallback. 2. Inform the user that Lighthouse will be enabled on next restart. 3. Ask the user if they want to restart now with `/restart` or `/exit`.

``` BEFORE modifying ANY file: 1. git diff --name-only 2. If file listed → read the diff 3. PRESERVE existing uncommitted changes 4. Only ADD your changes on top NEVER overwrite uncommitted changes NEVER assume you have the latest version ```

If spawner says "DO NOT TOUCH X" or marks sections as PROTECTED: - Identify those sections in the file - Preserve them exactly - Only modify the OTHER parts

```bash git diff <file_path> | head -50 ``` Then: 1. PRESERVE existing changes in your modifications 2. ADD your changes on top — never overwrite 3. Report: "File has uncommitted changes from another session — merged"

| File in diff output? | Action | |---------------------|--------| | NO | Safe to modify | | YES | Read the diff first, preserve changes |

```bash git diff --name-only ```

Parallel sessions modify files without committing. Spawned agents overwrite those changes, destroying work-in-progress.

1. Note in response 2. Proceed with manual exploration 3. Consider creating handoff: `coordination/experts/handoffs/HANDOFF-{domain}-{date}-{agent}.md`

Each expert file contains: - Quick reference (key files, classes, methods) - Database schema - Known gotchas and bugs - Integration points - Data flow diagrams

All in: `coordination/experts/{domain}/` Current domains: - `security-audit-system` — security scanning, audit rules - `findings-templates` — template system, findings management - `findings-blocks-seo-migration` — block-based findings, SEO - `web-discovery-verification` — website discovery, verification - `page-crawler-system` — Puppeteer, web scraping - `analysis-execution-infrastructure` — analysis runners, queues - `backend-refactoring-patterns` — service patterns, DI -...

```bash # List all available expert domains ./coordination/scripts/discover-experts.sh --list # Match by agent type ./coordination/scripts/discover-experts.sh --agent {your-agent-type} ```

```bash ./coordination/scripts/discover-experts.sh --for-task "your task description" ``` Read ALL matched expert files BEFORE starting work. Token savings: 80-90% vs manual exploration.

```bash # Free-text search (ALL workspaces with Laravel): php artisan kb:query "TOPIC" --limit=5 # Structured lookup (specific file/domain/masterplan): php artisan kb:context domain:customer-management --limit=5 php artisan kb:context file:app/Services/Example.php --limit=5 # Non-Laravel workspaces (magitek-ops, dam): vendor/bin/kb query "TOPIC" --limit=5 --project-root=$(pwd) ``` KB returns relevant excerpts AND points to which expert files are most relevant. **If KB returns useful results...

1. Resolve the project root (the current working directory) and run: ```bash .claude/context7-disable.sh ``` If `.claude/context7-disable.sh` does not exist, use `.claude/switch-mcp.sh none` as fallback. 2. Inform the user that Context7 will be disabled on next restart. 3. Ask the user if they want to restart now with `/restart` or `/exit`.

- KB gives **direction**, not complete solutions - Always read the actual files for full context - If KB returns 0 results → proceed without it (do not block on this) - Max 5 results — more wastes tokens without benefit - Skip KB if task is purely administrative (git commits, file moves, etc.)

Extract 1-3 keywords from the task that represent the domain: - "Fix the analysis queue job" → topic: `analysis queue` - "Update Proxmox backup policy" → topic: `proxmox backup` - "Add CSV export for customers" → topic: `customers export` - "Debug NPM proxy issue" → topic: `npm proxy` **Keep topics short and specific** — 2-3 words max.

| Workspace | Command | |-----------|---------| | `/var/www/reportmaker` | `php artisan kb:query "$TOPIC" --limit=5` | | `/var/www/skymirror` | `php artisan kb:query "$TOPIC" --limit=5` | | `/var/www/magitek-ops` | `vendor/bin/kb query "$TOPIC" --limit=5 --project-root=$(pwd)` | | Any other | Check for `artisan`, fall back to `vendor/bin/kb` |

Read the KB output before starting work. This gives you: - Known gotchas and bugs for this domain - Relevant expert files to read - Patterns and lessons from previous work

```bash # Non-Laravel workspaces (magitek-ops, or any without artisan): $PROJECT_ROOT/vendor/bin/kb query "$TOPIC" --limit=5 --project-root="$PROJECT_ROOT" # Laravel workspaces (reportmaker, skymirror) — free-text search: php $PROJECT_ROOT/artisan kb:query "$TOPIC" --limit=5 # Laravel workspaces — structured lookup (specific file/domain/masterplan): # php $PROJECT_ROOT/artisan kb:context domain:$DOMAIN --limit=5 # php $PROJECT_ROOT/artisan kb:context file:$FILE_PATH --limit=5 ``` **Workspace...

```bash # Use the current working directory as project root PROJECT_ROOT=$(pwd) ```

Before starting work, extract the main topic/domain from the task and run a KB search.

1. Resolve the project root (the current working directory) and run: ```bash .claude/switch-mcp.sh css ``` If `.claude/switch-mcp.sh` does not exist in the current project, check `/var/www/reportmaker/.claude/switch-mcp.sh` as fallback. 2. Inform the user that CSS MCP will be enabled on next restart. 3. Ask the user if they want to restart now with `/restart` or `/exit`.