Developer & Debug Tools

NoteCove includes powerful diagnostic tools for debugging storage issues, inspecting CRDT files, and understanding sync behavior.

Storage Inspector

The Storage Inspector provides a low-level view of your storage directory, similar to Wireshark for network packets.

Opening the Storage Inspector

Menu: Tools > Advanced > Storage Inspector

Keyboard: Cmd/Ctrl+Shift+I (Desktop only)

Features

Directory Tree:

Browse entire storage directory structure
See notes, tasks, folders, projects, media, activity logs
Sharded directory visualization
File type detection and icons

File Details:

File size and modification time
CRDT log record counts
Snapshot vector clock information
Activity log entry counts

Hex Viewer:

Low-level binary inspection
Color-coded byte groups:
- Header: Magic number, version
- Metadata: Sequence numbers, lengths
- Data: CRDT update payloads
Offset display (hex and decimal)
ASCII representation

Structured View:

Parse CRDT logs into readable records
Show sequence numbers and data lengths
Extract vector clocks from snapshots
Display activity log entries

Use Cases

Debugging Sync Issues:

Open Storage Inspector
Navigate to problematic note/task
Check for missing log files
Verify sequence numbers are contiguous
Inspect vector clock for gaps

Understanding Storage Layout:

Browse notes/ or tasks/ directory
See sharding in action (first/second/)
Understand file organization
Verify migration completed correctly

Low-Level Inspection:

Select a .crdtlog file
Open hex viewer
See binary format structure
Verify magic numbers and versions

Item Info

Get detailed metadata and storage information for any note or task.

Opening Item Info

Menu: Tools > Advanced > Item Info

Keyboard: Cmd/Ctrl+I (Desktop only)

Context: Must have a note or task open in editor

Information Displayed

Item Metadata:

Title
Created timestamp
Modified timestamp
Folder location
Pinned status
Deleted status

Storage Details:

Storage directory path (sharded)
Number of CRDT log files
Number of snapshot files
Total file size (all logs + snapshots)

Sync Status:

Vector clock per instance
Latest sequence numbers
Activity log entries

Use Cases

Verify Storage Path:

Check if note/task is in correct shard
Verify path format after migration
Confirm file locations

Monitor Disk Usage:

See how much space a note/task uses
Identify large CRDT logs
Decide when to create snapshots

Debug Sync:

Check if updates are being written
Verify activity log entries exist
See which instances have updated

View Item JSON

Export full item data as JSON for debugging or analysis.

Opening View Item JSON

Menu: Tools > Advanced > View Item JSON

Keyboard: Cmd/Ctrl+J (Desktop only)

Context: Must have a note or task open in editor

JSON Contents

Metadata:

{
  "id": "a1b2c3d4e5f6g7h8j9k0m1n2p3q4",
  "title": "My Note",
  "sdId": "storage-directory-id",
  "folderId": "folder-id-or-null",
  "created": 1702234567890,
  "modified": 1702234600000,
  "deleted": false,
  "pinned": false,
  "contentPreview": "Preview text..."
}

Editor Content:

{
  "editorContent": {
    "type": "doc",
    "content": [
      {
        "type": "heading",
        "attrs": { "level": 1 },
        "content": [{ "type": "text", "text": "My Note" }]
      },
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "Content here" }]
      }
    ]
  }
}

Task-Specific (if task):

{
  "projectId": "project-id",
  "stateId": "in-progress",
  "priority": 2,
  "typeId": "feature",
  "slug": "PROJ-123"
}

Use Cases

Debug Editor Issues:

See exact ProseMirror document structure
Verify mark and node formatting
Identify malformed content

Export Data:

Copy full item data
Use in external tools
Archive item information

Understand Schema:

See how NoteCove stores data
Learn ProseMirror document format
Study task metadata structure

Sync Events Log

Monitor real-time sync activity across your storage directory.

Opening Sync Events

Menu: Tools > Advanced > Sync Events

Keyboard: Cmd/Ctrl+Shift+S (Desktop only)

Event Types

Note Events:

Note created
Note updated
Note deleted
Note moved to folder

Task Events:

Task created
Task updated
Task state changed
Task priority changed

Folder Events:

Folder created
Folder renamed
Folder moved
Folder deleted

Sync Events:

Activity log polled
CRDT update applied
Snapshot created
File watcher triggered

Use Cases

Monitor Sync:

Watch changes sync in real-time
Verify polling intervals
See file watcher triggers

Debug Performance:

Identify excessive updates
Find polling bottlenecks
Monitor memory usage

Understand Workflow:

See event sequence
Learn sync timing
Verify proper ordering

Console Commands

Advanced users can use the developer console for diagnostics.

Opening Developer Console

Menu: View > Toggle Developer Tools

Keyboard: Cmd/Ctrl+Shift+I (same as Storage Inspector shortcut)

Useful Commands

Check vector clock:

await window.electronAPI.note.getInfo('note-id');

List all storage directories:

await window.electronAPI.storageDir.list();

Get note metadata:

await window.electronAPI.note.get('note-id');

Search notes:

await window.electronAPI.note.search('search query');

Activity Log Inspector

View and analyze activity logs for sync debugging.

Activity Log Format

note|a1b2c3d4e5f6g7h8j9k0m1n2p3q4|1
note|a1b2c3d4e5f6g7h8j9k0m1n2p3q4|2
task|z9y8x7w6v5u4t3s2r1q0p9n8m7k6|1
folder|0|1
project|0|1
media-note|a1b2c3d4e5f6g7h8j9k0m1n2p3q4|0

Reading Activity Logs

Navigate: Storage Inspector → activity/ directory
Select: {instanceId}.log file
View: See all activity entries
Filter: Search for specific item types or IDs

Use Cases

Track Updates:

See update sequence for an item
Verify sequence numbers increment correctly
Identify missing sequences

Debug Polling:

Check if new entries are being written
Verify format is correct
See which instances are active

Deletion Log Inspector

Inspect deletion logs and vector clocks.

Deletion Log Format

{
  "itemType": "note",
  "itemId": "a1b2c3...",
  "timestamp": 1702234567890,
  "vectorClock": {
    "instance1": {
      "sequence": 42,
      "offset": 8192,
      "file": "..."
    }
  }
}

Reading Deletion Logs

Navigate: Storage Inspector → deletion/ directory
Select: {instanceId}.jsonl file
View: See deletion entries with vector clocks

Use Cases

Conflict Resolution:

Understand delete vs. update conflicts
Verify vector clock data
Debug resurrection scenarios

Audit Trail:

See when items were deleted
Identify which instance deleted
Track deletion history

Migration Verification

Verify storage migration completed correctly.

Using Storage Inspector

Open Storage Inspector
Check structure:
- notes/ directory has sharding (first/second/)
- tasks/ directory has sharding
- SD_ID file exists (Base32)
- SD_VERSION shows “2”
Verify IDs:
- All IDs are lowercase Base32 (26 chars)
- No mixed-case UUIDs
- No Base64url IDs
Check attachments:
- Attachments stored in item directories (notes/{first}/{second}/{id}/attachments/)
- Files use ordinal naming (0.png, 1.jpg)
- Metadata files exist ({ordinal}.meta.json)
- No legacy media/ directory (or only contains old hash-based files)

Manual Verification

Count items:

# Count notes (should match pre-migration count)
find {SD}/notes -type d -depth 3 | wc -l

# Count tasks
find {SD}/tasks -type d -depth 3 | wc -l

Check ID format:

# All IDs should be lowercase Base32
find {SD}/notes -type d -depth 3 -exec basename {} \; | grep -v '^[0-9a-v]\{26\}$'
# Should output nothing (no non-Base32 IDs)

Performance Monitoring

Database Stats

Check SQLite cache performance:

Open console: View > Toggle Developer Tools

Run query:

await window.electronAPI.database.stats();

See:
- Note count
- Task count
- Folder count
- Database size

File System Stats

Monitor storage directory size:

macOS/Linux:

du -sh /path/to/storage-directory

Windows:

Get-ChildItem -Path "path\to\storage-directory" -Recurse | Measure-Object -Property Length -Sum

Memory Usage

Monitor NoteCove’s memory usage:

Open Activity Monitor (macOS) / Task Manager (Windows)
Find NoteCove process
Monitor:
- Main process memory
- Renderer process memory
- Total memory usage

Debugging Tips

Sync Not Working

Check activity logs: Are new entries being written?
Verify file watching: Is file watcher running?
Check polling: Is polling interval too long?
Inspect vector clocks: Are there gaps?

Missing Notes/Tasks

Open Storage Inspector: Does file exist?
Check database: Is item in SQLite cache?
Verify ID: Is ID format correct (Base32)?
Check deletion logs: Was item deleted?

Performance Issues

Check database size: Is SQLite too large?
Monitor CRDT logs: Are logs growing too large?
Create snapshots: Reduce log replay time
Check polling frequency: Is polling too aggressive?

Safety Warnings

::: danger Never manually edit storage directory files!

Editing CRDT logs, snapshots, or activity logs can corrupt your data and break sync. :::

::: warning Use developer tools only for inspection, not modification.

These tools are for debugging and understanding, not for making changes. :::

Offline Sync - How sync and storage works
Backup & Recovery - Protecting your data

Developer & Debug Tools

Storage Inspector

Opening the Storage Inspector

Features

Use Cases

Item Info

Opening Item Info

Information Displayed

Use Cases

View Item JSON

Opening View Item JSON

JSON Contents

Use Cases

Sync Events Log

Opening Sync Events

Event Types

Use Cases

Console Commands

Opening Developer Console

Useful Commands

Activity Log Inspector

Activity Log Format

Reading Activity Logs

Use Cases

Deletion Log Inspector

Deletion Log Format

Reading Deletion Logs

Use Cases

Migration Verification

Using Storage Inspector

Manual Verification

Performance Monitoring

Database Stats

File System Stats

Memory Usage

Debugging Tips

Sync Not Working

Missing Notes/Tasks

Performance Issues

Safety Warnings

Related Documentation