mirror of https://github.com/johannesjo/super-productivity.git synced 2026-07-17 16:37:43 +00:00

Johannes Millan bfdac6d19a refactor(op-log): merge LWWOperationFactory into ConflictResolutionService

- Consolidate LWWOperationFactory methods (createLWWUpdateOp, mergeAndIncrementClocks)
  into ConflictResolutionService to reduce service count
- Remove redundant caching in SuperSyncProvider (SyncCredentialStore already caches)
- Remove _onBlurWhenNotTracking$ sync trigger from SyncTriggerService
- Add documentation for dueDay/dueWithTime mutual exclusivity pattern
- Change docker-compose postgres port to 55432 to avoid conflicts

2026-01-29 18:24:15 +01:00

3.3 KiB

Raw Blame History

AI/Developer Architecture Documentation

This directory contains architectural documentation, design patterns, and guides specifically written for AI assistants and developers working on the Super Productivity codebase.

Core Patterns & Architecture

Task Scheduling & Date Management

dueDay/dueWithTime Mutual Exclusivity Pattern ⭐ CRITICAL
- Explains how dueDay and dueWithTime fields interact on tasks
- Why it matters: These fields are mutually exclusive; setting one clears the other
- When to read: Before working with task scheduling, planner, or date selectors
- Related commit: 400ca8c1 (2026-01-29)
TODAY_TAG Architecture ⭐ CRITICAL
- Explains the virtual tag pattern for the TODAY_TAG
- Why it matters: TODAY_TAG behaves fundamentally differently from regular tags
- When to read: Before working with today's task list, planner, or tag operations
- Related: Uses the dueDay/dueWithTime mutual exclusivity pattern

Entity Management

Adding New Entity Type Checklist
- Step-by-step guide for adding new entity types to the app
- When to use: When adding a new feature that requires persistent state

Sync & Operation Log

File-Based OpLog Sync Implementation Plan
- Technical plan for file-based sync implementation
- Related: See also docs/sync-and-op-log/ for comprehensive sync documentation

Plugin System

Issue Providers to Plugins Evaluation
- Analysis of migrating issue providers to plugin architecture
Plugin UI Consistency Plan
- Design plan for consistent plugin UI/UX

Documentation Conventions

Document Types

Architecture Docs - Explain fundamental patterns (e.g., virtual tags, mutual exclusivity)
Implementation Plans - Detailed technical plans for features
Checklists - Step-by-step guides for common tasks
Evaluations - Analysis of technical decisions

Criticality Markers

⭐ CRITICAL: Must read before working in related areas
📋 REFERENCE: Useful reference material
📝 DRAFT: Work in progress, may be incomplete

When to Update

After architectural changes: Document new patterns immediately
When patterns emerge: If you notice repeated code patterns, document them
When questions arise: If developers ask the same question twice, document the answer
After major refactors: Especially when behavior changes (like 400ca8c1)

docs/sync-and-op-log/ - Comprehensive operation log and sync documentation
docs/wiki/ - User-facing wiki documentation
docs/long-term-plans/ - Future technical plans and proposals

Contributing

When adding new documentation to this directory:

Use clear titles that describe the pattern/feature
Add a summary section explaining what, why, and when to read
Include code examples showing correct and incorrect usage
Link related files using relative paths
Update this README with your new document
Reference related commits when documenting a specific change

3.3 KiB Raw Blame History