### Example 1: Simple Alert **Before:** ```javascript alert('Task created successfully!'); ``` **After:** ```javascript showSuccess('Task created successfully!'); ``` --- ### Example 2: Error Alert **Before:** ```javascript alert('Failed to delete task'); ``` **After:** ```javascript showError('Failed to delete task'); ``` --- ### Example 3: Alert with Try-Catch **Before:** ```javascript try { await deleteTask(taskId); alert('Task deleted!'); } catch (error) { alert('Failed ...

### Include Service in HTML Add this script tag in your layout (after the API service): ```html <!-- Notification service --> <script src="/js/services/notification.js"></script> ``` That's it! The styles are automatically injected by the service.

- ✅ **Better UX**: Non-blocking toast notifications instead of modal alerts - ✅ **Consistent styling**: All notifications look the same - ✅ **Auto-dismiss**: Notifications disappear automatically - ✅ **Multiple notifications**: Can show several at once - ✅ **Accessible**: ARIA labels for screen readers - ✅ **No dependencies**: Pure vanilla JavaScript, zero dependencies - ✅ **Small footprint**: < 15KB total (including CSS)

This guide explains how to migrate from `alert()` calls to the new modern notification system.

After API Service migration is complete, move to: 1. **Notification System** - Replace all alert() calls with modern toasts 2. **XSS Security Fixes** - Audit and fix innerHTML usage 3. **jQuery Removal** - Replace with modern alternatives See `docs/llm/modernisering-plan.md` for full roadmap.

- **Code reduction**: 8000+ lines eliminated - **Development speed**: 50% faster for new API features - **Bug reduction**: Estimated 70% fewer API-related bugs - **Maintenance**: Much easier to update API endpoints ---

1. **High Priority** (Most used, biggest impact): - `public/js/tasks.js` (~30 fetch calls) - `public/js/projects.js` (~25 fetch calls) - `public/js/references.js` (~20 fetch calls) 2. **Medium Priority**: - `public/js/batch_update.js` - `public/js/agenda.js` - `public/js/common.js` 3. **Lower Priority**: - All other files with fetch calls

- [ ] Include API service scripts in layout - [ ] Replace alert() calls with notification system (see next phase) - [ ] Migrate one file at a time, starting with most critical - [ ] Test thoroughly after each migration - [ ] Remove old fetch() code once migrated - [ ] Update any documentation

### Task API ```javascript // CRUD operations await taskAPI.getAll(filters) await taskAPI.getById(id) await taskAPI.create(data) await taskAPI.update(id, data) await taskAPI.patch(id, updates) await taskAPI.delete(id) // Toggle operations await taskAPI.toggleComplete(id) await taskAPI.toggleFavorite(id) // Batch operations await taskAPI.batchUpdate(ids, updates) await taskAPI.batchDelete(ids) await taskAPI.batchComplete(ids) // Relationships await taskAPI.attachProjects(taskId, projectIds) a...

Let's migrate a real file: `public/js/tasks.js` (partial) ### Before (tasks.js - excerpt): ```javascript // Load all tasks async function loadAllTasks() { try { const response = await fetch('/tasks', { method: 'GET', headers: { 'Content-Type': 'application/json', 'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content } }); if (!response.ok) { throw new Error(`HTTP err...

### Example 1: Simple GET Request **Before:** ```javascript async function loadTasks() { try { const response = await fetch('/tasks', { method: 'GET', headers: { 'Content-Type': 'application/json', 'Accept': 'application/json', 'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content } }); if (!response.ok) { throw new Error(`HTTP error! status: ${respons...

### Include Services in HTML Add these script tags in your layout (before your application code): ```html <!-- Base API service --> <script src="/js/services/api.js"></script> <!-- Specialized services --> <script src="/js/services/task-api.js"></script> <script src="/js/services/project-api.js"></script> <script src="/js/services/reference-api.js"></script> <!-- Optional: Index file for convenient access --> <script src="/js/services/index.js"></script> ```

- ✅ **Less code**: Eliminates 8000+ lines of duplicate fetch boilerplate - ✅ **Consistent error handling**: All errors handled uniformly - ✅ **Automatic CSRF tokens**: No need to manually add tokens to every request - ✅ **Better UX**: Consistent loading states and error messages - ✅ **Type safety**: Clear API contracts for all endpoints - ✅ **Easier testing**: Mock API calls in one place

This guide explains how to migrate from manual `fetch()` calls to the new centralized API service layer.

This database schema is designed for: - **Flexibility**: Multi-dimensional organization - **Scalability**: Normalized design - **Integrity**: Comprehensive constraints - **Extensibility**: Clear patterns for adding features - **Performance**: Strategic indexing The schema supports complex GTD-based productivity management with hierarchies, dependencies, time management, and resource allocation.

### 1. Always Eager Load Relationships ```php Task::with(['projects', 'contexts', 'areas'])->get(); ``` Prevents N+1 query problems ### 2. Use Transactions for Multi-Table Operations ```php DB::transaction(function () { $task = Task::create([...]); $task->projects()->attach($projectId, ['sort_order' => 1]); $task->contexts()->attach($contextIds); }); ``` ### 3. Respect Unique Constraints Check before insert to avoid duplicate key errors ### 4. Handle Cascade Deletes Carefully Unde...

The 94 migrations show evolutionary development: ### Phase 1: Core Setup (Jan 2025) - Users, tasks, projects, areas, contexts - Basic pivot tables ### Phase 2: Feature Enhancement (Late Jan 2025) - Task/project attributes (energy, time, tags) - Action states, task types - Dependencies ### Phase 3: Organization Dimensions (Feb 2025) - Zones and zone pivots - Quadrants - Area hierarchies and aliases ### Phase 4: Time Management (Feb-Mar 2025) - Time capacities - Time slots - Area time preferen...

### Common Queries #### Get all tasks with relationships ```sql SELECT tasks.*, GROUP_CONCAT(projects.project_name) as projects, GROUP_CONCAT(contexts.name) as contexts FROM tasks LEFT JOIN project_task ON tasks.id = project_task.task_id LEFT JOIN projects ON project_task.project_id = projects.id LEFT JOIN context_task ON tasks.id = context_task.task_id LEFT JOIN contexts ON context_task.context_id = contexts.id GROUP BY tasks.id; ``` #### Get project hierarchy ```sql WITH RECURS...

### Foreign Key Cascade Rules **ON DELETE CASCADE** (Most relationships): - Deleting a task → deletes all pivot records, documents, time slots - Deleting a project → deletes all pivot records, documents - Deleting an area → deletes all pivot records, relationships **ON DELETE SET NULL**: - Deleting a section → sets `settings.seksjon_id` to NULL ### Unique Constraints ``` projects.project_name -- UNIQUE areas.name -- UNIQUE contexts.name -- UNIQUE...

### Explicit Indexes ``` time_capacities.target_date task_time_slots.task_id task_time_slots.slot_type area_time_preferences.area_id quadrant_task.task_id, quadrant_task.quadrant_id quadrant_project.project_id, quadrant_project.quadrant_id quadrant_reference.reference_id, quadrant_reference.quadrant_id dependencies.predecessor_type, dependencies.predecessor_id dependencies.successor_type, dependencies.successor_id ``` ### Implicit Indexes - All primary keys (`id` columns) - All unique constra...

### Entity Relationship Overview ``` ┌─────────┐ │ Users │ └─────────┘ │ ┌─────────────────────┼─────────────────────┐ │ │ │ ┌───▼───┐ ┌────▼────┐ ┌────▼────┐ │ Tasks │◄──────────►│ Projects│◄────────►│ Areas │ └───┬───┘ └────┬────┘ └────┬────┘ │ │ ...

### 1. lists **Purpose**: Generic list storage **Location**: `database/migrations/2025_03_03_144353_create_lists_table.php` ``` id BIGINT AUTO_INCREMENT PRIMARY KEY title VARCHAR(255) NOT NULL content TEXT NULL created_at TIMESTAMP updated_at TIMESTAMP ``` ### 2. users **Purpose**: User authentication **Location**: `database/migrations/2014_10_12_000000_create_users_table.php` ``` id BIGINT AUTO_INCREMENT PRIMARY KEY name VARCHAR(255) N...

### 1. settings **Purpose**: Application-wide configuration storage **Location**: `database/migrations/2025_02_04_131016_create_settings_table.php` ``` id BIGINT AUTO_INCREMENT PRIMARY KEY seksjon_id BIGINT FOREIGN KEY → seksjoner.id SET NULL key VARCHAR(255) UNIQUE NOT NULL value TEXT NULL -- Can store JSON, boolean, string, number created_at TIMESTAMP updated_at TIMESTAMP UNIQUE(key) ``` **Sample Settings**: - `time_enabled_for_settings` ...

### 1. area_relationships (Hierarchical) **Purpose**: Parent-child area structure **Location**: `database/migrations/2025_01_30_150539_create_area_relationships_table.php` ``` parent_area_id BIGINT FOREIGN KEY → areas.id CASCADE child_area_id BIGINT FOREIGN KEY → areas.id CASCADE portion_of_parent DECIMAL(5,2) DEFAULT 0.0 created_at TIMESTAMP updated_at TIMESTAMP PRIMARY KEY(parent_area_id, child_area_id) ``` **Composite Primary Key**: (parent_area_id, child_a...

### 1. time_capacities **Purpose**: Define available time by date/period **Location**: `database/migrations/2025_02_04_070915_create_time_capacities_table.php` ``` id BIGINT AUTO_INCREMENT PRIMARY KEY target_date DATE NOT NULL (INDEXED) daily_capacity UNSIGNED INT NULL -- Minutes available per day weekly_capacity UNSIGNED INT NULL -- Minutes available per week monthly_capacity UNSIGNED INT NULL -- Minutes available per month...

### 1. task_dependencies **Purpose**: Task-to-task dependencies (critical path) **Location**: `database/migrations/2025_01_29_160823_create_task_dependencies_table.php` ``` id BIGINT AUTO_INCREMENT PRIMARY KEY predecessor_task_id BIGINT FOREIGN KEY → tasks.id CASCADE successor_task_id BIGINT FOREIGN KEY → tasks.id CASCADE relation_type ENUM('FS','FF','SS','SF') NOT NULL created_at TIMESTAMP updated_at TIMESTAMP ``` **Relation...

### Task Type Extensions Four tables extend task functionality for different task types: #### 1. tasks_repetitive **Purpose**: Configuration for repetitive/recurring tasks **Location**: `database/migrations/2025_02_21_100024_create_tasks_repetitive_table.php` ``` id BIGINT AUTO_INCREMENT PRIMARY KEY task_id BIGINT FOREIGN KEY → tasks.id CASCADE (UNIQUE) interval VARCHAR(255) NULL -- 'daily', 'weekly', 'monthly', 'yearly' repeat_count INTEGER NULL ...

### Overview of Pivot Table Pattern All pivot tables follow consistent patterns: 1. Auto-increment `id` primary key 2. Two foreign keys (with cascade delete) 3. Timestamps 4. Optional relationship data (sort_order, attributes, etc.) ### Key Pivot Tables #### 1. project_task **Purpose**: Tasks belonging to projects **Location**: `database/migrations/2025_01_21_171727_create_project_task_table.php` ``` id BIGINT AUTO_INCREMENT PRIMARY KEY task_id BIGINT FOREIGN KEY → tas...

### 1. Tasks Table **Purpose**: Primary table for all actionable items **Location**: `database/migrations/2025_01_21_055011_create_tasks_table.php` **Columns**: ``` id BIGINT AUTO_INCREMENT PRIMARY KEY title VARCHAR(255) NOT NULL is_completed BOOLEAN DEFAULT false tag VARCHAR(255) NULL energy VARCHAR(255) NULL -- 'low', 'med', 'high' time UNSIGNED INT NULL -- Minutes notes TEXT NULL du...

### Core Entity Tables (7) - `users` - User authentication - `tasks` - Individual actionable items - `projects` - Multi-task initiatives - `areas` - Life/work domains - `contexts` - Work contexts (@home, @computer, etc.) - `zones` - Resource allocation buckets - `quadrants` - Eisenhower matrix quadrants ### Relationship Tables (13 pivot tables) Many-to-many relationship mappings with additional attributes ### Extension Tables (12) - Task types: `tasks_repetitive`, `tasks_routine`, `tasks_auto`...

This application uses a **highly normalized relational database** with extensive many-to-many relationships and hierarchical structures. The schema supports complex personal productivity management with GTD methodology. ### Statistics - **Total Tables**: 38 (25 core + 13 pivot tables) - **Total Migrations**: 94 (showing evolutionary development) - **Foreign Keys**: 40+ - **Relationships**: 30+ many-to-many, 15+ one-to-many - **Supported DBMS**: MySQL, PostgreSQL, SQLite ### Design Principles ...

When making changes: 1. **Plan** the change (model, migration, controller, view) 2. **Create** migration first 3. **Update** model (fillable, relationships, casts) 4. **Modify** controller (validation, eager loading, sync) 5. **Update** views (forms, lists) 6. **Test** with tinker and browser 7. **Commit** with clear message Follow existing patterns in the codebase for consistency!

### Making Changes ```bash # 1. Create branch git checkout -b feature/add-priority-field # 2. Make changes, test # 3. Add changed files git add app/Models/Task.php git add database/migrations/... # 4. Commit git commit -m "Add priority field to tasks" # 5. Push git push -u origin claude/analyze-codebase-docs-01QcfoPZKzpD2wK2W6ZK6TFd ``` ---

### 1. Always Eager Load Relationships ```php // BAD - N+1 queries $tasks = Task::all(); foreach ($tasks as $task) { echo $task->projects->count(); // Query per task } // GOOD - 2 queries total $tasks = Task::with('projects')->get(); foreach ($tasks as $task) { echo $task->projects->count(); // No query } ``` ### 2. Use Pagination ```php // Instead of ->get() $tasks = Task::paginate(20); // In views {{ $tasks->links() }} ``` ### 3. Select Only Needed Columns ```php // Instead of $...

### 1. Keep Controllers Thin **Bad**: ```php public function store(Request $request) { // 200 lines of business logic } ``` **Good**: ```php public function store(Request $request) { $validated = $request->validate([...]); $task = $this->taskService->createTask($validated); return response()->json(['success' => true, 'task' => $task]); } ``` ### 2. Use Service Classes for Complex Logic Move complex business logic to services: - `app/Services/TaskService.php` - `app/Services...

### 1. Relationship Not Loading **Problem**: `$task->projects` returns null or empty **Solutions**: ```php // Check eager loading in controller $task = Task::with('projects')->find($id); // Check pivot table has records DB::table('project_task')->where('task_id', $id)->get(); // Check model relationship definition // Ensure withPivot() includes all needed columns ``` ### 2. Validation Failing **Problem**: Form submission returns 422 error **Solutions**: ```php // Check validation rules ma...

### Manual Testing Checklist 1. **Database**: Run migration, check schema 2. **Model**: Test relationships in `php artisan tinker` 3. **Controller**: Test routes with Postman or browser 4. **Views**: Check UI rendering and form submission 5. **Validation**: Try invalid data to test validation 6. **AJAX**: Test JSON responses with browser dev tools ### Tinker Testing Examples ```bash php artisan tinker ``` ```php // Test relationship $task = Task::find(1); $task->projects; // Should return pr...

### Modifying Validation Rules **Location**: Controller methods (store, update) ```php // Before $validated = $request->validate([ 'title' => 'required|string|max:255', ]); // After - add more rules $validated = $request->validate([ 'title' => 'required|string|max:255|unique:tasks,title', 'description' => 'nullable|string|max:1000', 'tags' => 'array', 'tags.*' => 'exists:tags,id', ]); ``` ### Changing Pivot Table Data **Add new pivot column**: ```bash # 1. Create migrat...

### 1. Adding a New Field to an Existing Model **Example**: Add "priority" field to Tasks **Steps**: ```bash # 1. Create migration php artisan make:migration add_priority_to_tasks_table ``` ```php // database/migrations/YYYY_MM_DD_HHMMSS_add_priority_to_tasks_table.php public function up() { Schema::table('tasks', function (Blueprint $table) { $table->string('priority')->nullable()->after('tag'); }); } public function down() { Schema::table('tasks', function (Blueprint $...

The refactored backend provides: - **Type Safety**: Enums and DTOs prevent runtime errors - **Separation of Concerns**: Controllers, services, validation separated - **Single Responsibility**: 41 focused controllers - **Testability**: Small, focused components easy to test - **Maintainability**: Clear structure, self-documenting code - **Modern PHP**: PHP 8.1+ features throughout

### JSON Responses (AJAX) **Success**: ```php return response()->json([ 'success' => true, 'task' => $task->load('projects'), 'message' => 'Task created successfully!' ], 201); ``` **Error**: ```php return response()->json([ 'success' => false, 'message' => 'Validation failed', 'errors' => $validator->errors() ], 422); ``` ### Blade View Responses ```php return view('tasks.index', compact('tasks', 'lookup')); ``` ### Conditional Responses ```php if ($request->ajax()...

### LookupDataService **Purpose**: Centralized lookup data retrieval with DTOs ```php // app/Services/LookupDataService.php namespace App\Services; use App\DataTransferObjects\LookupDataDTO; use App\Models\{Area, Context, Project, Zone, Quadrant}; class LookupDataService { public function getAllLookupData(?int $zoneId = null): LookupDataDTO { $allAreasQuery = Area::query(); $parentAreasQuery = Area::with('children')->where('area_level', 1); $allContextsQuery =...

### Controller Domains | Domain | Count | Controllers | |--------|-------|-------------| | **Task** | 9 | TaskController, TaskFilterController, TaskConversionController, TaskDependencyController, TaskDocumentController, TaskChunkController, TaskBatchController, TaskDataController, TaskRelationshipController | | **Project** | 5 | ProjectController, ProjectFilterController, ProjectConversionController, ProjectDocumentController, ProjectBatchController | | **Reference** | 4 | ReferenceController, ...

### 1. Rich Enums (6 total) **Purpose**: Type-safe value objects with behavior, replacing magic strings **Location**: `app/Enums/` #### ActionState Enum ```php // app/Enums/ActionState.php namespace App\Enums; enum ActionState: string { case NEXT = 'next'; case LATER = 'later'; case SOMEDAY = 'someday'; case WAITING = 'waiting'; case INBOX = 'inbox'; public function label(): string { return match ($this) { self::NEXT => 'Next Action', ...

The backend follows **Laravel MVC architecture** enhanced with **modern PHP patterns**. Post-refactoring, it consists of: - **42 specialized controllers** (from 19) - **6 service classes** - **24 models** with Enum casts - **6 rich Enums** with behavior - **2 DTOs** for type safety - **4 Form Request classes** for validation - **2 helper classes** ### Architecture Layers ``` HTTP Request ↓ Routes (web.php) - 215 routes ↓ Form Requests (4) - Validation ↓ Controllers (42) ← Inject → ...

The frontend is designed for: - **Simplicity**: Server-rendered, progressively enhanced - **Reliability**: Works without JavaScript (graceful degradation) - **Performance**: Minimal client-side overhead - **Maintainability**: Standard Laravel/Bootstrap patterns - **User Experience**: Responsive, accessible, intuitive

### Loading States ```javascript async function loadTasks() { const spinner = document.getElementById('loadingSpinner'); spinner.classList.remove('d-none'); try { const response = await axios.get('/tasks'); renderTasks(response.data.tasks); } finally { spinner.classList.add('d-none'); } } ``` ### Notifications ```javascript function showNotification(message, type = 'info') { const alert = document.createElement('div'); alert.className = `al...

1. **Eager Loading**: Load relationships in controllers to avoid N+1 2. **Pagination**: All lists paginated (15-20 items per page) 3. **Asset Bundling**: Vite bundles and minifies JS/CSS 4. **Lazy Loading**: Images loaded on demand 5. **Caching**: Browser caching for static assets

### Vite Configuration **vite.config.js**: ```javascript import { defineConfig } from 'vite'; import laravel from 'laravel-vite-plugin'; export default defineConfig({ plugins: [ laravel({ input: ['resources/css/app.css', 'resources/js/app.js'], refresh: true, }), ], }); ``` ### Development ```bash npm run dev # Start Vite dev server with HMR ``` ### Production ```bash npm run build # Build optimized assets ```

### Main Stylesheet **resources/css/app.css**: ```css @import 'bootstrap/dist/css/bootstrap.min.css'; /* Custom styles */ .task-completed { text-decoration: line-through; opacity: 0.6; } .task-urgent { border-left: 4px solid red; } .task-high-energy { background-color: #fff3cd; } /* Responsive */ @media (max-width: 768px) { .task-table { font-size: 0.9rem; } } ```