Skip to content

Refactor: Implement Immutable Base + Overlay Model Architecture#61

Merged
ssweber merged 17 commits intomainfrom
dev
Jan 22, 2026
Merged

Refactor: Implement Immutable Base + Overlay Model Architecture#61
ssweber merged 17 commits intomainfrom
dev

Conversation

@ssweber
Copy link
Owner

@ssweber ssweber commented Jan 22, 2026

Summary

This PR introduces a major architectural refactor replacing the previous data management approach with an Immutable Base + Overlay Model. This new architecture cleanly separates database truth from user edits, enabling robust undo/redo, targeted UI updates, and better handling of external database changes.

Key Changes

  • New Data Layer Architecture

    • AddressStore: Core store managing base/overlay/visible layers with observer pattern
    • EditSession: Context manager for atomic, undoable edits
    • MutableRowBuilder: Builder pattern for accumulating row changes
    • UndoFrame: Snapshot-based undo/redo with 50-level history

  • Simplified Data Model

    • AddressRow now immutable (frozen=True dataclass)
    • Block colors extracted from rows to separate mutable store
    • Removed complex state management from row model

  • Service Layer Improvements

    • BlockService: Refactored to use apply_block_tag for sync operations
    • RowService: Updated to work with edit sessions
    • Removed DependencyService (functionality integrated into store)

  • View Layer Updates

    • All views now use observer pattern for targeted updates
    • Dirty state detection via reference equality
    • Address Editor, Dataview Editor, and Tag Browser updated

  • Bug Fixes

    • Fixed AddressRow validation for empty initial values
    • Corrected MDB upsert operations
    • Fixed interleaved block tag pair syncing
    • Fixed CSV import to align with CLICK export format
    • Dataview node rename prevention

  • Testing

    • Added comprehensive tests for AddressStore (463 lines)
    • Added tests for MutableRowBuilder (161 lines)
    • Simplified existing tests with new architecture

  • Documentation

    • Updated CLAUDE.md to reflect new architecture patterns
    • Removed obsolete ARCHITECTURE_PLAN.md

Benefits

  1. Undo/Redo: Full 50-level undo/redo tracking user intent only
  2. Clean Separation: Database truth vs. user edits clearly separated
  3. Performance: Reference equality enables fast dirty detection and targeted UI updates
  4. Immutability: Eliminates race conditions and simplifies reasoning about state
  5. External Updates: Database refreshes preserve user overrides correctly

Test Plan

  • All existing tests pass
  • New tests for AddressStore operations
  • New tests for MutableRowBuilder
  • Undo/redo functionality verified
  • CSV import/export validated
  • MDB read/write operations tested
  • Block tag sync verified
  • Address Editor UI updates correctly
  • Dataview Editor integration confirmed

ssweber and others added 17 commits January 20, 2026 13:55
@ssweber
Squashed commit of the following:
2254091 
commit f8e3854
Author: ssweber <57631333+ssweber@users.noreply.github.com>
Date:   Tue Jan 20 13:51:33 2026 -0500

    update cell notes regardless

commit 1625d4f
Author: ssweber <57631333+ssweber@users.noreply.github.com>
Date:   Tue Jan 20 13:48:37 2026 -0500

    more fixes

commit dcead7e
Author: ssweber <57631333+ssweber@users.noreply.github.com>
Date:   Tue Jan 20 13:22:37 2026 -0500

    more changes

commit 1a76543
Author: ssweber <57631333+ssweber@users.noreply.github.com>
Date:   Tue Jan 20 11:47:55 2026 -0500

    Update IMPLEMENTATION_PLAN.md

commit e04f7be
Author: ssweber <57631333+ssweber@users.noreply.github.com>
Date:   Tue Jan 20 11:21:41 2026 -0500

    renaming/ using new store

commit 91dd1c8
Author: ssweber <57631333+ssweber@users.noreply.github.com>
Date:   Tue Jan 20 09:39:09 2026 -0500

    more work

commit 00de867
Author: ssweber <57631333+ssweber@users.noreply.github.com>
Date:   Tue Jan 20 08:36:00 2026 -0500

    Update IMPLEMENTATION_PLAN.md

commit 892791d
Author: ssweber <57631333+ssweber@users.noreply.github.com>
Date:   Tue Jan 20 08:24:01 2026 -0500

    Restore a few files that seem fine

commit eec3694
Author: ssweber <57631333+ssweber@users.noreply.github.com>
Date:   Tue Jan 20 08:20:51 2026 -0500

    delete 1st attempt

commit ff57fd7
Author: ssweber <57631333+ssweber@users.noreply.github.com>
Date:   Tue Jan 20 07:53:53 2026 -0500

    remove unneeded dev deps

commit 6f6ec19
Author: ssweber <57631333+ssweber@users.noreply.github.com>
Date:   Tue Jan 20 07:53:35 2026 -0500

    lint/sort

commit 90d1359
Author: ssweber <57631333+ssweber@users.noreply.github.com>
Date:   Mon Jan 19 15:04:46 2026 -0500

    Create IMPLEMENTATION_PLAN.md

commit 22b19a1
Author: ssweber <57631333+ssweber@users.noreply.github.com>
Date:   Mon Jan 19 14:32:44 2026 -0500

    Phase 1
@ssweber
copy/ update claude to reflect change from skeleton/unidirectional to…
6bc8091 
… Immutable Base + Overlay Model
@ssweber
ssort and lint fixes
fe602ae
@ssweber
fix/convert csv to new format. Align with CLICK export
78b6940
@ssweber
fix/dont allow node rename in Dataview
3d96d4c
@ssweber @claude
refactor: extract block_color from AddressRow to mutable store
2074546 
Move block_color out of the frozen AddressRow dataclass into a separate
mutable dictionary in AddressStore. This eliminates unnecessary row
recreation when block colors change and keeps derived display state out
of the undo/redo system.

Changes:
- Add block_colors dict and get_block_color() accessor to AddressStore
- Update _update_block_colors(), _recompute_all_block_colors(), and
  _apply_initial_block_colors() to use dict instead of row objects
- Remove block_color field from AddressRow and MutableRowBuilder
- Update row_styler to read colors from store.get_block_color()
- Update tests to use new accessor method
- Document block colors pattern in CLAUDE.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ssweber
fix/mdb upsert
69821fc
@ssweber
deadcode
d2a72d7
@ssweber
fix/dont track exists_in_mdb now that we use upsert
810c31a
@ssweber
fix: correct is_empty
400e80f 
Before it was just tracking nickname, now all content
@ssweber
fix: AddressRow corrected needs_full_delete if initial_value is ""/0
c6bc63c
@ssweber
refac/ move imports to top (where applicable)
68ea1d2
@ssweber
fix/ sync both opening and closing of interleaved pair
d4655fd
@ssweber
refac/ BlockService: move & rename sync_block_tag -> apply_block_tag
99c75bc
@ssweber
feat/ Clean MDB dev feature
d8858ce
@ssweber
feat/ Clean MDB dev feature
d7675e1
@ssweber
Merge branch 'dev' of https://github.com/ssweber/clicknick into dev
b3cbd31
@ssweber ssweber merged commit 9004329 into main Jan 22, 2026
3 checks passed
@ssweber ssweber deleted the dev branch January 22, 2026 19:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ssweber