Skip to content

DAG.md

Latest commit

 

History

History
572 lines (535 loc) · 32.3 KB

DAG.md

File metadata and controls

572 lines (535 loc) · 32.3 KB

System DAG (Directed Acyclic Graph)

Overview

This document describes the Directed Acyclic Graph (DAG) representing the dependencies and data flow in Vectorizer Sync. The DAG shows how components interact and the order of operations.

Component Dependencies DAG

┌─────────────────────────────────────────────────────────────────┐
│                        Application Entry                        │
│                         (main/index.ts)                        │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
                    ┌────────────────┐
                    │  Database      │
                    │  Manager       │
                    │  (init)        │
                    └────────┬───────┘
                             │
                             ▼
                    ┌────────────────┐
                    │  User Settings │
                    │  (load)        │
                    └────────┬───────┘
                             │
                             ▼
                    ┌────────────────┐
                    │  UI Renderer   │
                    │  (React App)   │
                    └────────┬───────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        ▼                    ▼                    ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│   Project     │   │   Workspace   │   │   Sync        │
│   Manager     │   │   Exporter    │   │   Manager     │
└───────┬───────┘   └───────┬───────┘   └───────┬───────┘
        │                   │                   │
        │                   │                   │
        ▼                   ▼                   ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│   Database    │   │   File        │   │   File        │
│   (projects)  │   │   Scanner     │   │   Watcher     │
└───────────────┘   └───────┬───────┘   └───────┬───────┘
                            │                   │
                            └─────────┬─────────┘
                                      │
                                      ▼
                            ┌─────────────────┐
                            │   File Filter   │
                            └────────┬────────┘
                                     │
                    ┌────────────────┼────────────────┐
                    │                │                │
                    ▼                ▼                ▼
            ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
            │   Workspace │  │   File       │  │   HiveHub    │
            │   Generator  │  │   Metadata   │  │   API Client │
            └──────────────┘  └───────┬──────┘  └───────┬──────┘
                                      │                 │
                                      └────────┬────────┘
                                               │
                                               ▼
                                      ┌─────────────────┐
                                      │   Database      │
                                      │   (file_metadata)│
                                      └─────────────────┘

File Synchronization DAG

┌─────────────────────────────────────────────────────────────┐
│                    File System Event                         │
│              (create, modify, delete)                        │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
                ┌────────────────┐
                │  File Watcher   │
                │  (chokidar)     │
                └────────┬───────┘
                         │
                         ▼
                ┌────────────────┐
                │  Event Queue   │
                │  (debounced)   │
                └────────┬───────┘
                         │
                         ▼
                ┌────────────────┐
                │  File Filter    │
                │  (exclusions)  │
                └────────┬───────┘
                         │
            ┌────────────┴────────────┐
            │                        │
            ▼                        ▼
    ┌───────────────┐        ┌───────────────┐
    │   Excluded    │        │   Included    │
    │   (skip)      │        │   (process)   │
    └───────────────┘        └───────┬───────┘
                                     │
                                     ▼
                            ┌────────────────┐
                            │  Hash          │
                            │  Calculator    │
                            └───────┬────────┘
                                    │
                    ┌───────────────┼───────────────┐
                    │               │               │
                    ▼               ▼               ▼
            ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
            │   New File   │  │   Modified   │  │   Deleted    │
            │   (upload)   │  │   (update)   │  │   (delete)   │
            └──────┬───────┘  └──────┬───────┘  └──────┬───────┘
                   │                 │                 │
                   └─────────────────┼─────────────────┘
                                     │
                                     ▼
                            ┌────────────────┐
                            │  Sync Queue    │
                            │  (prioritized) │
                            └───────┬────────┘
                                    │
                                    ▼
                            ┌────────────────┐
                            │  Quota Check   │
                            └───────┬────────┘
                                    │
                    ┌───────────────┴───────────────┐
                    │                               │
                    ▼                               ▼
            ┌──────────────┐              ┌──────────────┐
            │   Quota OK   │              │   Quota     │
            │   (proceed)  │              │   Exceeded  │
            └──────┬───────┘              │   (block)   │
                   │                      └─────────────┘
                   ▼
            ┌────────────────┐
            │  HiveHub API   │
            │  (upload/update)│
            └───────┬────────┘
                    │
        ┌───────────┼───────────┐
        │           │           │
        ▼           ▼           ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│  Success  │ │  Partial  │ │  Failed   │
│  (update  │ │  (retry)  │ │  (log)    │
│  metadata)│ │           │ │           │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
      │             │             │
      └─────────────┼─────────────┘
                    │
                    ▼
            ┌────────────────┐
            │  Database      │
            │  (update sync  │
            │   history)     │
            └────────────────┘

Workspace Export DAG

┌─────────────────────────────────────────────────────────────┐
│                    User Action: Export                      │
│                    Workspace.yml                            │
└────────────────────────┬──────────────────────────────────┘
                          │
                          ▼
                 ┌─────────────────┐
                 │  Project        │
                 │  Selection      │
                 └────────┬────────┘
                          │
                          ▼
                 ┌─────────────────┐
                 │  File Scanner   │
                 │  (recursive)    │
                 └────────┬────────┘
                          │
                          ▼
                 ┌─────────────────┐
                 │  File Filter     │
                 │  (exclusions)    │
                 └────────┬────────┘
                          │
                          ▼
                 ┌─────────────────┐
                 │  Collection      │
                 │  Grouping        │
                 └────────┬────────┘
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
        ▼                 ▼                 ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  Source Code │  │  Docs        │  │  Config      │
│  Collection  │  │  Collection │  │  Collection  │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       └─────────────────┼─────────────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Pattern         │
                │  Matching        │
                └────────┬─────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  YAML Generator  │
                │  (workspace.yml) │
                └────────┬─────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  File Writer    │
                │  (save to disk)  │
                └────────┬─────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Database       │
                │  (save config)  │
                └─────────────────┘

Database Operations DAG

┌─────────────────────────────────────────────────────────────┐
│                    Database Operation                       │
└────────────────────────┬──────────────────────────────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
        ▼                ▼                ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│   Read       │  │   Write      │  │   Transaction│
│   Operation  │  │   Operation  │  │   Operation │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       ▼                 ▼                 ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  Prepared    │  │  Prepared    │  │  Begin       │
│  Statement   │  │  Statement   │  │  Transaction │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       ▼                 ▼                 ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  Execute     │  │  Execute     │  │  Execute     │
│  Query       │  │  Query       │  │  Operations  │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       │                 │                 │
       └─────────────────┼─────────────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Result         │
                │  Processing     │
                └────────┬────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
        ▼                ▼                ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  Return      │  │  Update      │  │  Commit/     │
│  Data        │  │  Cache        │  │  Rollback    │
└──────────────┘  └──────────────┘  └──────────────┘

Notification Flow DAG

┌─────────────────────────────────────────────────────────────┐
│                    Notification Source                      │
└────────────────────────┬──────────────────────────────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
        ▼                ▼                ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  Internal    │  │  HiveHub     │  │  System      │
│  Event       │  │  API         │  │  Event       │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       └─────────────────┼─────────────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Notification   │
                │  Processor      │
                └────────┬────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Severity       │
                │  Check          │
                └────────┬────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
        ▼                ▼                ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│   Info       │  │   Warning    │  │   Error      │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       └─────────────────┼─────────────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Database        │
                │  (store)         │
                └────────┬────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Notification   │
                │  Dispatcher     │
                └────────┬────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
        ▼                ▼                ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  UI          │  │  System Tray │  │  Sound       │
│  Notification│  │  Badge      │  │  Alert       │
│  Center      │  │              │  │  (optional)  │
└──────────────┘  └──────────────┘  └──────────────┘

Startup Sequence DAG

┌─────────────────────────────────────────────────────────────┐
│                    Application Start                       │
└────────────────────────┬──────────────────────────────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Initialize     │
                │  Electron       │
                └────────┬────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Check Database │
                │  Directory      │
                └────────┬────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Initialize     │
                │  Database       │
                │  (schema)       │
                └────────┬────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Load User      │
                │  Settings      │
                └────────┬────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Load Projects  │
                │  from Database  │
                └────────┬────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Initialize     │
                │  File Watchers  │
                │  (if enabled)  │
                └────────┬────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Initialize     │
                │  HiveHub API    │
                │  (if configured)│
                └────────┬────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Create Browser  │
                │  Window         │
                └────────┬────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Load React App │
                └────────┬────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Application    │
                │  Ready          │
                └─────────────────┘

Sync Operation DAG

┌─────────────────────────────────────────────────────────────┐
│                    Sync Trigger                             │
│        (manual, auto, file change)                         │
└────────────────────────┬──────────────────────────────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Validate       │
                │  Project        │
                └────────┬────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  Check Sync     │
                │  Enabled        │
                └────────┬────────┘
                         │
        ┌────────────────┴────────────────┐
        │                                 │
        ▼                                 ▼
┌──────────────┐                  ┌──────────────┐
│  Disabled    │                  │  Enabled     │
│  (skip)      │                  │  (proceed)   │
└──────────────┘                  └──────┬───────┘
                                         │
                                         ▼
                                ┌─────────────────┐
                                │  Create Sync    │
                                │  History Entry  │
                                └────────┬────────┘
                                         │
                                         ▼
                                ┌─────────────────┐
                                │  Scan Files     │
                                │  (if needed)    │
                                └────────┬────────┘
                                         │
                                         ▼
                                ┌─────────────────┐
                                │  Compare with   │
                                │  Metadata       │
                                └────────┬────────┘
                                         │
        ┌───────────────────────────────┼───────────────────────────────┐
        │                               │                               │
        ▼                               ▼                               ▼
┌──────────────┐              ┌──────────────┐              ┌──────────────┐
│  New Files   │              │  Modified    │              │  Deleted     │
│  (upload)    │              │  Files       │              │  Files       │
│              │              │  (update)    │              │  (delete)    │
└──────┬───────┘              └──────┬───────┘              └──────┬───────┘
       │                             │                             │
       └─────────────────────────────┼─────────────────────────────┘
                                     │
                                     ▼
                            ┌─────────────────┐
                            │  Batch          │
                            │  Operations     │
                            └────────┬────────┘
                                     │
                                     ▼
                            ┌─────────────────┐
                            │  Process Queue   │
                            │  (with retry)    │
                            └────────┬────────┘
                                     │
                                     ▼
                            ┌─────────────────┐
                            │  Update         │
                            │  Metadata       │
                            └────────┬────────┘
                                     │
                                     ▼
                            ┌─────────────────┐
                            │  Update Sync    │
                            │  History        │
                            └─────────────────┘

DAG Properties

Acyclicity

All DAGs in the system are acyclic, meaning:

  • No circular dependencies between components
  • Operations flow in one direction
  • No infinite loops in processing

Topological Order

Operations follow a topological order:

  1. Initialization: Database → Settings → Projects
  2. File Processing: Scan → Filter → Process → Store
  3. Sync Operations: Validate → Check → Process → Update

Parallelization Opportunities

The following operations can be parallelized:

  • File scanning (multiple directories)
  • File filtering (independent files)
  • File hash calculation (independent files)
  • Database queries (read operations)
  • API requests (independent operations)

Critical Path

The critical path for sync operations:

File Change → Watcher → Filter → Hash → Queue → Quota Check → API → Database Update

Implementation Notes

Dependency Management

Components are initialized in dependency order:

  1. Database (no dependencies)
  2. Settings (depends on Database)
  3. File Scanner (depends on Settings)
  4. File Watcher (depends on Scanner)
  5. Sync Engine (depends on Watcher, API)
  6. UI (depends on all above)

Error Handling

Errors propagate through the DAG:

  • Component errors are caught and logged
  • Failed operations are retried (with backoff)
  • Critical errors stop the operation flow
  • Non-critical errors allow partial success

Performance Optimization

  • Batching: Group operations to reduce overhead
  • Caching: Cache results to avoid recomputation
  • Lazy Loading: Load data only when needed
  • Debouncing: Batch rapid file changes

Visualization Tools

The DAG can be visualized using:

  • Graphviz: Generate visual representations
  • Mermaid: Render in markdown
  • D3.js: Interactive visualization
  • Cytoscape: Network analysis

Example Graphviz Code

digraph SyncFlow {
    FileChange -> FileWatcher
    FileWatcher -> EventQueue
    EventQueue -> FileFilter
    FileFilter -> HashCalculator
    HashCalculator -> SyncQueue
    SyncQueue -> QuotaCheck
    QuotaCheck -> HiveHubAPI
    HiveHubAPI -> DatabaseUpdate
}