gsd-task-manager copilot-instructions.md

Copilot Instructions for GSD Task Manager

This guide enables AI coding agents to work productively in the GSD Task Manager codebase. Follow these project-specific conventions and workflows for best results.

Architecture Overview

Core Stack

• Next.js 16 App Router: All routes in app/. Matrix view: app/(matrix)/page.tsx. Dashboard: app/(dashboard)/dashboard/page.tsx. PWA install: app/(pwa)/install/page.tsx.
• Client-side only: No server rendering. All components use "use client".
• Data Layer: IndexedDB via Dexie v4 (lib/db.ts, current schema v13). CRUD in lib/tasks.ts. Live queries via useTasks() hook (lib/use-tasks.ts).
• Quadrant System: Tasks classified by urgent/important booleans → 4 quadrants. Logic in lib/quadrants.ts.
• Schema Validation: Zod schemas in lib/schema.ts for all data types.

Database Schema (v13)

• Tables: tasks, archivedTasks, smartViews, notificationSettings, syncQueue, syncMetadata, deviceInfo, archiveSettings, syncHistory, appPreferences
• Task Fields: Core (id, title, description, urgent, important, quadrant, completed, completedAt, dueDate, createdAt, updatedAt) + Advanced (recurrence, tags, subtasks, dependencies, notifyBefore, snoozedUntil, estimatedMinutes, timeSpent, timeEntries)
• Indexes: Performance-critical indexes on quadrant, completed, dueDate, completedAt, createdAt, updatedAt, *tags, *dependencies, notificationSent
• Migrations: Schema changes always require migration in lib/db.ts. See DATABASE_ARCHITECTURE.md for full ERD.
• Schema change checklist: Zod schema changes typically require updates in three places: lib/constants/schema.ts (add/update limits), taskDraftSchema in lib/schema.ts, and taskRecordImportSchema in lib/schema.ts (a separate definition that uses .strip() — not derived from the draft schema for validation rules).

Key Architectural Decisions

1. PocketBase cloud sync: Optional cloud sync via self-hosted PocketBase server. Tasks stored as plaintext (user owns the server). OAuth authentication with Google/GitHub.
2. Last-write-wins conflict resolution: Conflicts resolved using client_updated_at timestamps. BFS algorithm prevents circular dependencies in task graph.
3. Modular components: Large files split into <300 line modules. Example: lib/sync/ has 20+ focused modules vs monolithic sync engine.
4. Pure analytics functions: All metric calculations in lib/analytics/ are side-effect-free for testability and composability.
5. Transaction-based batch operations: lib/bulk-operations.ts ensures atomicity (all-or-nothing) for multi-task updates.