callumalpass_tasknotes/Tasknotes-Development-Guidelines.md

TaskNotes Plugin: Architecture & Developer's Guide

1. Introduction & Guiding Principles

This guide is designed to help you understand the architecture of the TaskNotes plugin, ensuring that new features and updates are implemented in a way that is consistent, maintainable, and performant.

The architecture of this plugin is built on several key principles:

• Separation of Concerns: Logic is separated into distinct layers: UI (Views & Components), Business Logic (Services), and Data (Cache & File System). This makes the codebase easier to reason about and test.
• Single Source of Truth: The CacheManager is the canonical source for all task and note data at runtime. All reads should go through the cache, and all writes must be funneled through a Service that updates both the file system and the cache.
• Unidirectional Data Flow: Changes flow in one direction: User Action -> Service -> File System -> Cache -> Event -> UI Update. This predictable pattern prevents complex state management issues and race conditions.
• Event-Driven Communication: Components are decoupled. Instead of calling each other directly, they emit and listen for events via a central EventEmitter. This allows new components to be added without modifying existing ones.
• Performance First: The architecture is designed to be highly performant, especially for users with large vaults. This is achieved through aggressive caching, request deduplication, and an efficient DOM reconciliation strategy.
• Configuration-Driven: Core functionalities like statuses, priorities, and field names are not hard-coded. They are managed by dedicated services (StatusManager, PriorityManager, FieldMapper) that interpret user settings, making the plugin highly customizable.
• Obsidian Optimization Compliance: The plugin follows Obsidian's best practices for load time optimization and deferred view compatibility, ensuring fast startup and smooth integration with the latest Obsidian versions.

2. High-Level Architecture Diagram

This diagram illustrates the flow of data and events within the plugin.

+----------------+       +------------------+       +------------------+
|   User Input   |------>|   UI / Views     |------>|   Services       |
| (Click, Drag)  |       | (Agenda, Kanban) |       | (TaskService, etc) |
+----------------+       +------------------+       +------------------+
      ^                                                     |
      |                                                     | (1. Write to file)
      |                                                     v
      |                                               +------------+
      | (5. UI Update via                               | File System|
      |     DOMReconciler)                              |  (.md)     |
      |                                               +------------+
      |                                                     ^
      |                                                     | (2. Update cache)
      +---------------------+                               |
+---------------------+     |                         +------------------+
|    DOMReconciler    |     | (4. Views listen        |  CacheManager    | (Single Source
| (Efficient Updates) |<----+     for events)         | (In-memory data) |  of Truth)
+---------------------+     |                         +------------------+
                            |                               |
                            |                               | (3. Emit event)
                            v                               v
                          +-----------------------------------+
                          |     EventEmitter (Decouples)      |
                          +-----------------------------------+

3. Directory Structure

The project is organized to reflect the architectural layers:

• /src/
  • main.ts: The plugin's entry point. It initializes all services, views, and commands.
  • types.ts: Crucial. Contains all shared type definitions. All new types should be added here.
  • /views/: Contains the primary UI views (TaskListView, AgendaView, KanbanView, etc.), which are ItemView implementations registered with Obsidian.
  • /ui/: Contains reusable, "dumb" UI components like TaskCard, NoteCard, and FilterBar. These components are responsible for rendering data, not fetching it.
  • /modals/: Contains all modals for user interaction (TaskCreationModal, TaskEditModal, etc.).
  • /services/: The core business logic of the plugin resides here. Each service has a specific responsibility (e.g., TaskService for CRUD, FilterService for querying, PomodoroService for timers).
  • /editor/: Contains CodeMirror extensions that enhance the Obsidian editor, like TaskLinkWidget and InstantConvertButtons.
  • /utils/: Contains helper classes and functions that support the entire plugin, such as CacheManager, EventEmitter, dateUtils, and DOMReconciler.
  • /settings/: Contains the settings tab UI and default settings configuration.
• /styles/: Contains all CSS files, which are compiled into a single styles.css.

4. Key Architectural Concepts

4.1. The Data Flow: A Step-by-Step Guide

Understanding this flow is the most important part of contributing to the plugin.

1. User Action: A user interacts with the UI (e.g., clicks "Archive" on a TaskCard).
2. Service Call: The UI component's event handler calls the relevant method in a service (e.g., plugin.taskService.toggleArchive(task)). UI components should never modify data directly.
3. File System Write: The service performs the necessary changes on the Markdown file's frontmatter.
4. Cache Update: After a successful file write, the service proactively updates the CacheManager with the new TaskInfo object. This is critical for keeping the UI instantly responsive.
5. Event Emission: The service emits a global event via plugin.emitter (e.g., EVENT_TASK_UPDATED) with the updated data.
6. View Refresh: All active views listen for relevant events. Upon receiving an event, they trigger a refresh, fetching the new, authoritative data from the CacheManager.
7. DOM Reconciliation: Views use the DOMReconciler to efficiently update only the parts of the UI that have changed, preventing full-page re-renders and preserving UI state like scroll position.

4.2. The Cache (CacheManager) - The Single Source of Truth

The CacheManager is the heart of the plugin's data layer. It provides a fast, in-memory representation of all tasks and notes.

• Purpose: To minimize disk I/O and provide instantaneous data access to the UI. It prevents every view from having to read and parse files independently.
• How it Works:
  • On startup, it performs an initial scan of the vault to build its indexes.
  • It maintains several caches: raw file content, parsed YAML, and fully processed TaskInfo and NoteInfo objects.
  • It creates and maintains several indexes for fast lookups (e.g., tasksByDate, tasksByStatus, overdueTasks).
  • It listens to vault events (modify, delete, rename) to automatically keep the cache up-to-date.
• Developer Best Practices:
  • Always read from the cache. Use cacheManager.getCachedTaskInfo(path) for synchronous access or cacheManager.getTaskInfo(path) for an async call that reads from the file if not cached.
  • NEVER write to the cache directly. All writes must go through a service (e.g., TaskService).
  • Services are responsible for calling cacheManager.updateTaskInfoInCache(path, newTaskInfo) after a file has been successfully modified. This proactive update is key to UI responsiveness.
  • When adding a new indexed property, ensure you add logic to both updateTaskIndexes and removeFromIndexes in CacheManager for it to be maintained correctly.

4.3. The Event System (EventEmitter)

The EventEmitter is the nervous system of the plugin, enabling decoupled communication.

• Purpose: To allow components to react to changes without having direct references to each other. For example, when TaskService updates a task, it doesn't need to know which views are open; it just emits an EVENT_TASK_UPDATED event.
• How it Works: It's a simple pub/sub model. Components on() an event and provide a callback. Other components emit() an event, triggering all subscribed callbacks.
• Developer Best Practices:
  • Use predefined event types from /src/types.ts. If you need a new event, add it there first.
  • Keep event payloads minimal and consistent. Pass the essential data needed for subscribers to react (e.g., { path, updatedTask }).
  • Remember to clean up listeners. All views that register listeners should call the returned unsubscribe function in their onClose() or destroy() methods. The provided code already does this correctly in a listeners array.

4.4. Date and Time Management (dateUtils.ts)

Handling dates and times is notoriously difficult due to timezones and different formats. This plugin standardizes date/time handling through dateUtils.ts.

• The Problem: JavaScript's new Date() is inconsistent. new Date('2023-10-27') creates a UTC date, while new Date('2023-10-27T10:00:00') creates a local timezone date. This leads to "off-by-one-day" errors.
• The Solution: A set of centralized utility functions in dateUtils.ts that handle these nuances.
• Developer Best Practices:
  • Never use new Date(dateString) directly. Always use parseDate(dateString) from dateUtils.ts. It intelligently handles both date-only and full ISO timestamp strings.
  • For comparisons, use the provided safe functions: isSameDateSafe, isBeforeDateSafe, isOverdueTimeAware. These functions correctly normalize dates before comparing.
  • When creating a new timestamp for dateCreated or dateModified, always use getCurrentTimestamp(). This generates a consistent, timezone-aware ISO string.
  • When you only need the date part (e.g., YYYY-MM-DD), use getDatePart(dateString).
  • Use hasTimeComponent(dateString) to determine if a date string includes time information, and branch your logic accordingly.

4.5. The UI Layer (Views and Components)

• Views (/views/): These are the main panels of the plugin (e.g., AgendaView). They are stateful and responsible for fetching data (via FilterService), managing user interactions, and orchestrating the rendering of their content. They should contain the FilterBar and the main content display.
• Reusable Components (/ui/): These are "dumb" components like TaskCard and NoteCard.
  • They receive data as props (createTaskCard(task, plugin, options)).
  • They are responsible only for rendering that data into HTML.
  • They should not contain business logic. Any user interaction (like a button click) should call a method on the plugin or a service passed in as a prop.
• DOMReconciler: To ensure high performance, views do not re-render their entire HTML on every data change. Instead, they use plugin.domReconciler.updateList(). This utility efficiently diffs the new data against the existing DOM, only adding, removing, or updating the elements that have changed. When creating new list-based UIs, you should use this reconciler.

4.6. The Field Mapper (FieldMapper.ts) - The Data Translator

This is a critical architectural component that enables user customization.

• Purpose: The FieldMapper is a "translator" service. Its primary purpose is to decouple the plugin's internal TaskInfo property names (e.g., scheduled, timeEstimate) from the user-configurable property names in the YAML frontmatter of their task files. This allows users to name their properties whatever they like (e.g., schedule_on, estimate_minutes) without breaking the plugin.

• How it Works: It provides a two-way mapping.

  • Reading (File -> TaskInfo): When CacheManager reads a file, its frontmatter is passed to fieldMapper.mapFromFrontmatter(frontmatter). The service uses the mapping in settings.fieldMapping to create a standardized TaskInfo object. For example, if the user setting is { due: "deadline" }, the mapper will take frontmatter.deadline and put its value into the taskInfo.due field.
  • Writing (TaskInfo -> File): When TaskService saves a task, it passes the internal TaskInfo object to fieldMapper.mapToFrontmatter(taskInfo). This creates a frontmatter object ready for serialization. For example, taskInfo.due will be written as deadline: ... in the YAML.

• Developer Best Practices:

  • Central Point of Interaction: Any service that directly reads or writes task frontmatter (CacheManager, TaskService) must use the FieldMapper.
  • Stable Internal API: Within the plugin's TypeScript code (views, components, other services), you should always interact with the standardized TaskInfo properties (task.due, task.priority, etc.). The FieldMapper is the boundary layer that handles the translation to/from the user's world.
  • Avoid Hard-coding: Never write code that directly accesses a frontmatter property like frontmatter.due. Always use the mapper to get the user-configured field name first.
  • Extensibility: When adding a new persistent property to tasks, you must add it to the FieldMapping type in types.ts, the DEFAULT_FIELD_MAPPING in settings.ts, and the mapping logic in FieldMapper.ts.

5. Developer's Guide: How to Implement Common Changes

5.1. Adding a New Property to Tasks

Let's say you want to add a complexity: 'simple' | 'medium' | 'hard' property to tasks.

1. Update types.ts: Add complexity?: string; to the TaskInfo interface.
2. Update settings.ts:
   • Add complexity: string; to the FieldMapping interface in DEFAULT_FIELD_MAPPING.
   • Add a new setting in the TaskNotesSettingTab to allow users to configure the property name.
3. Update FieldMapper.ts: Add logic to mapFromFrontmatter and mapToFrontmatter to handle the new complexity field.
4. Update TaskService.ts:
   • In createTask, handle the new property, possibly applying a default value.
   • In updateTask, ensure the new property can be updated.
5. Update BaseTaskModal.ts: Add a dropdown or input field to TaskCreationModal and TaskEditModal to allow users to set the complexity.
6. Update TaskCard.ts: In createTaskCard and updateTaskCard, add logic to display the new complexity information (e.g., an icon or text in the metadata line).
7. Update FilterService.ts (Optional): If you want to filter by complexity, you'll need to:
   • Add a complexity index to CacheManager.
   • Update updateTaskIndexes and removeFromIndexes in CacheManager to maintain the new index.
   • Add logic to FilterService.matchesQuery to filter by complexity.
   • Add a complexity filter control to FilterBar.ts.

5.2. Walkthrough: Modifying a Task Property

Let's trace the flow of changing a task's priority from a TaskCard.

1. UI (TaskCard.ts): The user right-clicks the card and selects a new priority from the context menu.
2. Event Handler: The onClick handler for the menu item calls plugin.updateTaskProperty(task, 'priority', newPriorityValue).
3. Main Plugin (main.ts): The updateTaskProperty method is a convenience wrapper that calls this.taskService.updateProperty(...).
4. Service (TaskService.ts): The updateProperty method is executed. a. It finds the TFile for the task. b. It uses app.fileManager.processFrontMatter() to open the file and update the YAML. It uses the fieldMapper to get the correct property name (e.g., it might write prio: high instead of priority: high if the user configured it that way). It also updates the dateModified property. c. After the file write is successful, it calls this.plugin.cacheManager.updateTaskInfoInCache(path, updatedTask) to proactively update the cache. d. It then calls this.plugin.emitter.emit(EVENT_TASK_UPDATED, { path, updatedTask }).
5. Event Listeners:
   • TaskListView.ts: The view's listener for EVENT_TASK_UPDATED fires. It finds the corresponding HTMLElement for the task in its taskElements map and calls updateTaskCard(element, updatedTask, ...) to efficiently re-render just that one card.
   • AgendaView.ts: Its listener fires. Since a priority change might affect sorting, it triggers a full refresh(), which re-fetches data from FilterService and uses the DOMReconciler to update the view.
   • Editor (TaskLinkOverlay.ts): The global listener in main.ts dispatches a taskUpdateEffect to all open editors. The TaskLinkField sees this effect and redraws any TaskLinkWidgets for the affected task path.

This entire flow happens almost instantaneously, giving the user immediate feedback while ensuring data integrity and consistency across the entire plugin. By following this pattern, you ensure your new features will be robust and well-integrated.

6. Performance Optimization & Obsidian Best Practices

6.1. Plugin Load Time Optimization

Following Obsidian's performance guidelines is crucial for user experience. The plugin implements several key optimizations:

Load Time Pattern:

async onload() {
    // Essential initialization only
    await this.loadSettings();
    this.initializeLightweightServices();
    
    // Register view types and commands
    this.registerViews();
    this.addCommands();
    
    // Defer expensive operations
    this.app.workspace.onLayoutReady(() => {
        this.initializeAfterLayoutReady();
    });
}

private async initializeAfterLayoutReady() {
    // Cache initialization
    await this.cacheManager.initializeCache();
    
    // Heavy service initialization
    await this.pomodoroService.initialize();
    
    // Editor services with async imports
    const { TaskLinkDetectionService } = await import('./services/TaskLinkDetectionService');
}

Developer Best Practices:

• Keep onload() lightweight: Only include essential setup (settings, service constructors, view registration)
• Defer expensive operations: Move cache initialization, file processing, and heavy imports to onLayoutReady
• Use async imports: Load large services dynamically to reduce initial bundle size
• Avoid vault events in constructors: Register file watchers after layout is ready

6.2. Deferred View Compatibility

The plugin is compatible with Obsidian v1.7.2+ deferred views:

View Implementation Pattern:

export class MyView extends ItemView {
    constructor(leaf: WorkspaceLeaf, plugin: TaskNotesPlugin) {
        super(leaf);
        this.plugin = plugin;
        // Lightweight constructor only
    }
    
    async onOpen() {
        // Wait for plugin readiness
        await this.plugin.onReady();
        
        // Initialize view after plugin is ready
        this.initializeView();
    }
}

Workspace Iteration Best Practices:

// Good - Handle deferred views
workspace.iterateRootLeaves((leaf) => {
    if (leaf.view && leaf.view.getViewType() === 'markdown') {
        // Safe to access view
    }
});

// Good - Use proper instanceof checks
const leaves = workspace.getLeavesOfType('my-view');
for (const leaf of leaves) {
    if (leaf.view instanceof MyCustomView) {
        // View is loaded and ready
    }
}

// Bad - Assumes view is loaded
workspace.iterateAllLeaves(leaf => {
    if (leaf.view.getViewType() === 'my-view') {
        let view = leaf.view as MyCustomView; // May fail with deferred views
    }
});

6.3. File System Event Handling

File system events must be handled carefully to avoid performance issues during Obsidian startup:

Proper Event Registration:

// In CacheManager.performInitialization() - called after layout ready
private registerFileEvents(): void {
    this.vault.on('modify', this.eventHandlers.modify);
    this.vault.on('create', this.eventHandlers.create);
    // Handle layout readiness check
    const handleCreate = (file) => {
        if (!this.app.workspace.layoutReady) {
            return; // Ignore events during startup
        }
        this.processFileCreate(file);
    };
}

Developer Best Practices:

• Never register vault events in constructors: Always defer until onLayoutReady
• Check layout readiness: Ignore file events during Obsidian's initialization
• Use debouncing: Prevent excessive processing of rapid file changes

7. External Data Integration

7.1. ICS Calendar Integration Architecture

The plugin supports both remote ICS subscriptions and local ICS files through a unified service architecture:

Service Structure:

interface ICSSubscription {
    id: string;
    name: string;
    type: 'remote' | 'local';
    url?: string;      // For remote subscriptions
    filePath?: string; // For local files
    color: string;
    enabled: boolean;
    refreshInterval: number;
}

Implementation Pattern:

async fetchSubscription(id: string): Promise<void> {
    const subscription = this.getSubscription(id);
    
    let icsData: string;
    if (subscription.type === 'remote') {
        icsData = await this.fetchRemoteICS(subscription.url);
    } else {
        icsData = await this.readLocalICS(subscription.filePath);
    }
    
    const events = this.parseICS(icsData);
    this.updateCache(id, events);
}

7.2. File Watching for Local Resources

Local ICS files are automatically monitored for changes:

File Watcher Pattern:

private startFileWatcher(subscription: ICSSubscription): void {
    const modifyRef = this.plugin.app.vault.on('modify', (file) => {
        if (file.path === subscription.filePath) {
            // Debounce changes
            setTimeout(() => this.refreshSubscription(subscription.id), 1000);
        }
    });
    
    // Store cleanup function
    this.fileWatchers.set(subscription.id, () => {
        this.plugin.app.vault.offref(modifyRef);
    });
}

Developer Best Practices:

• Debounce file changes: Prevent excessive refreshes on rapid file modifications
• Store cleanup references: Always provide proper cleanup in destroy() methods
• Handle file deletion: Gracefully handle cases where watched files are removed
• Unified interface: Keep local and remote data sources compatible through consistent interfaces

7.3. Adding New External Data Sources

When integrating new external data sources (APIs, file formats, etc.):

1. Create a dedicated service: Follow the pattern of ICSSubscriptionService
2. Use subscription model: Allow multiple sources of the same type
3. Implement caching: Cache parsed data with expiration
4. Add to settings UI: Provide user configuration interface
5. Handle errors gracefully: Show meaningful error messages to users
6. Support both local and remote: When possible, support both local files and remote URLs

8. Error Handling & Data Validation

8.1. Date/Time Error Prevention

The plugin implements robust date parsing to handle various formats:

Safe Date Parsing Pattern:

// Always use dateUtils for parsing
import { parseDate, validateDateInput } from '../utils/dateUtils';

// Good
try {
    const date = parseDate(dateString);
    // Process date
} catch (error) {
    // Handle invalid date
}

// Bad - Direct Date constructor
const date = new Date(dateString); // May create unexpected results

Supported Date Formats:

• ISO datetime: 2025-02-23T20:28:49
• Space-separated: 2025-02-23 20:28:49
• Date-only: 2025-02-23
• ISO week: 2025-W02

8.2. Type Safety & Validation

Interface Extension Pattern:

// When adding new optional properties
interface TaskInfo {
    // ... existing properties
    newProperty?: string; // Always optional for backward compatibility
}

// Provide defaults in service layer
const taskWithDefaults = {
    ...existingTask,
    newProperty: existingTask.newProperty || defaultValue
};

Developer Best Practices:

• Make new properties optional: Ensures backward compatibility
• Validate external data: Always validate data from external sources
• Provide meaningful errors: Help users understand what went wrong
• Graceful degradation: Continue functioning when optional features fail

9. Testing & Quality Assurance

9.1. Manual Testing Checklist

When implementing new features, test these scenarios:

Plugin Load Testing:

• Clean Obsidian startup (no existing plugin data)
• Startup with existing plugin data
• Startup with large vaults (1000+ files)
• Hot reload during development

View Testing:

• View opens correctly when deferred
• View responds to data changes
• View handles no data gracefully
• View cleanup on close

Data Integration Testing:

• External data source failures
• File watcher behavior
• Cache invalidation
• Concurrent data updates

9.2. Performance Testing

Load Time Metrics:

• Plugin should add <100ms to Obsidian startup
• Views should render within 200ms of opening
• File operations should not block UI

Memory Usage:

• Monitor cache size with large datasets
• Ensure proper cleanup of event listeners
• Check for memory leaks in long-running sessions

This comprehensive architecture ensures the plugin remains performant, maintainable, and compatible with Obsidian's evolution while providing robust external data integration capabilities.