jan-henrik/constellation-analyzer
1
0
Fork 0
mirror of https://github.com/OFFIS-ESC/constellation-analyzer synced 2026-01-26 23:43:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
constellation-analyzer/docs/TEMPORAL_SCENARIO_IMPLEMENTATION_PLAN.md
Jan-Henrik Bruhn f0862650f4 doc: move some plans around
2025-10-11 22:08:53 +02:00

36 KiB
Raw Permalink Blame History

Temporal & Scenario Analysis Implementation Plan

Executive Summary

This implementation plan transforms Constellation Analyzer into a powerful tool for temporal evolution analysis and scenario exploration. This is NOT a version control system - it's a storytelling and analytical tool that helps users:

  1. Track temporal evolution: Show how constellations change over time (historical or projected)
  2. Explore scenarios: Branch from any point to explore alternative futures
  3. Compare and analyze: Visualize differences between states
  4. Present findings: Create compelling narratives about network dynamics

Key ChromaDB Integration Opportunities

ChromaDB should be leveraged for:

  • State metadata search: Find states by description, time period, or scenario assumptions
  • Actor trajectory analysis: Track how specific actors evolve across states
  • Pattern recognition: Identify similar states or recurring patterns
  • Annotation storage: Store and retrieve analytical notes about changes
  • Comparison results: Cache diff calculations for quick retrieval

1. Revised Data Model

1.1 Core Types (New File: /src/types/temporal.ts)

/**
 * Type of analysis state
 */
export type StateType = 'temporal' | 'scenario';

/**
 * Temporal metadata for time-based states
 */
export interface TemporalMetadata {
  // Absolute date/time
  timestamp?: string;  // ISO 8601 format

  // Relative ordering
  sequenceNumber?: number;

  // Human-readable labels
  label: string;  // e.g., "Q1 2023", "Session 5", "Post-Merger"

  // Period information
  periodStart?: string;
  periodEnd?: string;

  // Display properties
  displayFormat?: 'date' | 'sequence' | 'label';
}

/**
 * Scenario metadata for branched alternatives
 */
export interface ScenarioMetadata {
  // Scenario identification
  label: string;  // e.g., "Strategy A", "Pessimistic Outlook"

  // Analytical context
  description: string;
  assumptions: string[];  // Key assumptions for this scenario

  // Probability/confidence
  probability?: number;  // 0-1 scale
  confidence?: 'high' | 'medium' | 'low';

  // Visual properties
  color?: string;  // Color code for this scenario branch
}

/**
 * Relationship between states
 */
export interface StateRelationship {
  type: 'temporal-next' | 'temporal-previous' | 'scenario-branch' | 'scenario-parent';
  targetStateId: string;
}

/**
 * Analysis state - represents the constellation at a specific point in time or scenario
 */
export interface AnalysisState {
  // Identity
  stateId: string;
  stateType: StateType;

  // Graph snapshot
  snapshot: {
    nodes: SerializedActor[];
    edges: SerializedRelation[];
    // Note: nodeTypes and edgeTypes inherited from document
  };

  // Metadata based on type
  temporal?: TemporalMetadata;
  scenario?: ScenarioMetadata;

  // Relationships
  relationships: StateRelationship[];

  // Annotations and analysis
  notes?: string;
  tags?: string[];

  // Tracking
  createdAt: string;
  createdBy?: string;

  // ChromaDB integration
  embeddingId?: string;  // ID in ChromaDB for semantic search
}

/**
 * Diff between two states
 */
export interface StateDiff {
  fromStateId: string;
  toStateId: string;

  // Actor changes
  actorsAdded: SerializedActor[];
  actorsRemoved: SerializedActor[];
  actorsModified: Array<{
    actorId: string;
    changes: {
      label?: { from: string; to: string };
      type?: { from: string; to: string };
      position?: { from: { x: number; y: number }; to: { x: number; y: number } };
      metadata?: { from: any; to: any };
    };
  }>;

  // Relation changes
  relationsAdded: SerializedRelation[];
  relationsRemoved: SerializedRelation[];
  relationsModified: Array<{
    relationId: string;
    changes: {
      type?: { from: string; to: string };
      directionality?: { from: string; to: string };
      strength?: { from: number; to: number };
    };
  }>;

  // Summary statistics
  summary: {
    totalActorChanges: number;
    totalRelationChanges: number;
    networkDensityChange?: number;
    centralityChanges?: Map<string, number>;  // Actor ID -> centrality delta
  };
}

/**
 * Actor journey - tracks a specific actor across multiple states
 */
export interface ActorJourney {
  actorId: string;
  label: string;

  // Appearances in different states
  appearances: Array<{
    stateId: string;
    stateLabel: string;
    actor: SerializedActor;
    timestamp?: string;
  }>;

  // Summary
  firstAppearance: string;  // State ID
  lastAppearance: string;   // State ID
  appearanceCount: number;
}

/**
 * Timeline - ordered sequence of temporal states
 */
export interface Timeline {
  timelineId: string;
  label: string;
  description?: string;

  // Ordered states
  states: string[];  // State IDs in temporal order

  // Display settings
  displaySettings: {
    showGrid: boolean;
    snapToInterval?: 'day' | 'week' | 'month' | 'quarter' | 'year';
    autoLayout: boolean;
  };
}

/**
 * Scenario tree - hierarchical structure of branched scenarios
 */
export interface ScenarioTree {
  rootStateId: string;
  branches: Array<{
    branchId: string;
    label: string;
    states: string[];  // State IDs in this branch
    color?: string;
  }>;
}

1.2 Updated Document Type

// Update to ConstellationDocument in /src/stores/persistence/types.ts
export interface ConstellationDocument {
  metadata: {
    version: string;
    appName: string;
    createdAt: string;
    updatedAt: string;
    lastSavedBy: string;
    documentId?: string;
    title?: string;

    // NEW: Multi-state support
    supportsStates?: boolean;  // Feature flag
  };

  // Current/working graph state
  graph: {
    nodes: SerializedActor[];
    edges: SerializedRelation[];
    nodeTypes: NodeTypeConfig[];
    edgeTypes: EdgeTypeConfig[];
  };

  // NEW: Temporal and scenario states
  states?: {
    // All states
    stateList: AnalysisState[];

    // Current active state
    currentStateId: string | null;

    // Organization
    timelines: Timeline[];
    scenarioTrees: ScenarioTree[];

    // Settings
    settings: {
      enableAutoDiff: boolean;
      showChangeIndicators: boolean;
      defaultStateType: StateType;
    };
  };
}

2. Component Architecture

2.1 New Components

/src/components/TemporalAnalysis/ (New Directory)

TimelinePanel.tsx

  • Bottom panel for timeline/scenario visualization
  • Horizontal axis: temporal progression
  • Vertical axis: scenario branches
  • Interactive timeline scrubber
  • State creation and navigation controls

StateSelector.tsx

  • Dropdown/modal for selecting states
  • Filter by type (temporal/scenario)
  • Search by label, description, tags
  • Visual tree/timeline representation

ComparisonView.tsx

  • Side-by-side or overlay comparison of two states
  • Diff highlighting (added/removed/modified)
  • Toggle between different comparison modes
  • Export comparison reports

StateDiffViewer.tsx

  • Visual representation of changes between states
  • Color-coded change indicators
  • Summary statistics panel
  • Drill-down into specific changes

StateMetadataEditor.tsx

  • Edit temporal/scenario metadata
  • Set labels, timestamps, descriptions
  • Manage assumptions for scenarios
  • Add tags and notes

ActorJourneyViewer.tsx

  • Track specific actors across states
  • Timeline visualization of actor evolution
  • Relationship changes over time
  • Export actor-specific reports

StateAnimator.tsx

  • Smooth transitions between states
  • Configurable animation speed
  • Morph visualization (actors moving, appearing, disappearing)
  • Playback controls (play, pause, step forward/back)

PresentationMode.tsx

  • Slideshow through states
  • Full-screen mode
  • Annotations and narration
  • Export as video/animated GIF

/src/components/Panels/ (Updates to Existing)

BottomPanel.tsx (Replace or Extend)

  • Integrate TimelinePanel
  • Collapsible/expandable
  • Drag to resize height
  • State management controls

RightPanel.tsx (Update)

  • Add "State History" section
  • Show current state metadata
  • Quick comparison tools
  • State navigation shortcuts

2.2 Component Hierarchy

App
├── MenuBar
│   └── States Menu (new)
│       ├── Create State
│       ├── View Timeline
│       ├── Compare States
│       └── Manage Scenarios
├── Toolbar
│   └── State Controls (new)
│       ├── Current State Indicator
│       ├── Quick State Switch
│       └── Create Snapshot Button
├── GraphEditor
│   └── State Overlay (new)
│       ├── Change Indicators
│       └── Diff Highlighting
├── BottomPanel
│   └── TimelinePanel (new)
│       ├── Timeline View
│       ├── Scenario Tree View
│       └── State Creation Controls
└── Modals
    ├── ComparisonView (new)
    ├── StateMetadataEditor (new)
    ├── ActorJourneyViewer (new)
    └── PresentationMode (new)

3. Store Architecture

3.1 New Store: stateStore.ts

// /src/stores/stateStore.ts

import { create } from 'zustand';
import type { AnalysisState, StateDiff, Timeline, ScenarioTree, StateType } from '../types/temporal';

interface StateStore {
  // State management
  states: Map<string, AnalysisState>;
  currentStateId: string | null;

  // Organization
  timelines: Timeline[];
  scenarioTrees: ScenarioTree[];

  // Actions
  createState: (
    type: StateType,
    snapshot: { nodes: SerializedActor[]; edges: SerializedRelation[] },
    metadata: Partial<TemporalMetadata> | Partial<ScenarioMetadata>,
    parentStateId?: string
  ) => string;

  loadState: (stateId: string) => void;
  deleteState: (stateId: string) => void;
  updateStateMetadata: (stateId: string, updates: Partial<AnalysisState>) => void;

  // Timeline management
  createTimeline: (label: string, stateIds: string[]) => string;
  addStateToTimeline: (timelineId: string, stateId: string, position?: number) => void;
  removeStateFromTimeline: (timelineId: string, stateId: string) => void;
  reorderTimeline: (timelineId: string, newOrder: string[]) => void;

  // Scenario management
  createScenarioBranch: (parentStateId: string, label: string) => string;
  addStateToScenario: (branchId: string, stateId: string) => void;

  // Comparison and analysis
  compareStates: (stateId1: string, stateId2: string) => StateDiff;
  getActorJourney: (actorId: string, stateIds?: string[]) => ActorJourney;

  // Navigation
  getNextState: (currentStateId: string, type?: 'temporal' | 'scenario') => string | null;
  getPreviousState: (currentStateId: string) => string | null;
  getStatesByTimeline: (timelineId: string) => AnalysisState[];
  getStatesByScenario: (branchId: string) => AnalysisState[];

  // ChromaDB integration
  indexStateForSearch: (stateId: string) => Promise<void>;
  searchStates: (query: string) => Promise<AnalysisState[]>;
}

3.2 Updated workspaceStore.ts

Add state-related actions:

interface WorkspaceActions {
  // ... existing actions ...

  // State operations
  captureCurrentState: (type: StateType, metadata: any) => string;
  restoreState: (stateId: string) => void;
  exportStatesTimeline: (timelineId: string) => void;
  importStatesTimeline: () => Promise<void>;
}

4. Implementation Phases

Phase 1: Core State Management (Week 1-2)

Priority: HIGH - Foundation for all features

  1. Data Model Setup

    • Create /src/types/temporal.ts
    • Update ConstellationDocument type
    • Add migration for existing documents

  2. Basic State Store

    • Implement stateStore.ts
    • Basic CRUD operations for states
    • Simple state switching

  3. Snapshot Functionality

    • Capture current graph as state
    • Store state metadata
    • Load state back to graph

  4. UI Integration

    • Add "Capture State" button to toolbar
    • Basic state selector dropdown
    • Current state indicator

Deliverable: Users can create snapshots and switch between them

Phase 2: Temporal Analysis (Week 3-4)

Priority: HIGH - Core use case

  1. Timeline Management

    • Create Timeline data structure
    • Timeline CRUD operations
    • State ordering and sequencing

  2. Timeline Panel UI

    • Bottom panel with timeline visualization
    • Horizontal timeline scrubber
    • State markers with labels
    • Click to load state

  3. Temporal Metadata

    • Date/time picker for states
    • Sequence number assignment
    • Period labeling

  4. Timeline Navigation

    • Previous/Next state navigation
    • Keyboard shortcuts (← →)
    • Timeline auto-scrolling

Deliverable: Users can create temporal sequences and navigate through time

Phase 3: Comparison & Diff Analysis (Week 5-6)

Priority: HIGH - Key analytical feature

  1. Diff Calculation Engine

    • Implement compareStates() function
    • Actor-level diff detection
    • Relation-level diff detection
    • Change summarization

  2. Visual Diff Indicators

    • Overlay mode on graph
    • Color coding (green=added, red=removed, yellow=modified)
    • Change badges/icons
    • Animated transitions

  3. Comparison View Component

    • Side-by-side state comparison
    • Synchronized panning/zooming
    • Difference highlighting
    • Export comparison report

  4. Change Summary Panel

    • Statistics dashboard
    • List of changes
    • Filter by change type
    • Jump to changed actors

Deliverable: Users can compare any two states and see visual differences

Phase 4: Scenario Branching (Week 7-8)

Priority: MEDIUM - Advanced feature

  1. Scenario Data Model

    • Scenario tree structure
    • Branch metadata management
    • Parent-child relationships

  2. Scenario Creation UI

    • "Branch from here" action
    • Scenario metadata form
    • Assumptions editor
    • Probability/confidence inputs

  3. Scenario Tree Visualization

    • Vertical branching in timeline panel
    • Branch color coding
    • Branch labels and descriptions
    • Interactive branch selection

  4. Scenario Navigation

    • Switch between branches
    • Compare scenario outcomes
    • Merge/delete branches

Deliverable: Users can create and explore alternative scenarios

Phase 5: Actor Tracking & Journeys (Week 9-10)

Priority: MEDIUM - Valuable analysis tool

  1. Journey Calculation

    • Track actor across states
    • Detect appearances/disappearances
    • Calculate trajectory metrics
    • Relationship evolution tracking

  2. Journey Viewer UI

    • Actor selection interface
    • Timeline visualization of actor
    • Relationship changes display
    • Export actor report

  3. Multi-Actor Comparison

    • Compare multiple actor journeys
    • Network position changes
    • Relationship dynamics

Deliverable: Users can follow specific actors through time/scenarios

Phase 6: Animation & Presentation (Week 11-12)

Priority: MEDIUM - Storytelling feature

  1. State Animation Engine

    • Smooth transitions between states
    • Actor movement interpolation
    • Fade in/out for added/removed actors
    • Configurable animation speed

  2. Animation Controls

    • Play/pause/step controls
    • Speed adjustment
    • Loop options
    • Auto-play through timeline

  3. Presentation Mode

    • Full-screen slideshow
    • Narration/annotation overlay
    • Custom sequence selection
    • Export as video/GIF (stretch goal)

Deliverable: Users can create animated presentations of their analyses

Phase 7: ChromaDB Integration (Week 13-14)

Priority: MEDIUM - Enhanced search and analysis

  1. State Indexing

    • Index state metadata in ChromaDB
    • Include descriptions, assumptions, notes
    • Tag-based organization
    • Semantic embeddings

  2. Semantic Search

    • Search states by description
    • Find similar states
    • Query by temporal criteria
    • Tag-based filtering

  3. Pattern Recognition

    • Identify recurring patterns
    • Find similar network structures
    • Anomaly detection
    • Trend analysis

  4. Annotation Storage

    • Store analytical notes in ChromaDB
    • Link notes to specific changes
    • Search annotations
    • Generate analysis reports

Deliverable: Users can semantically search and analyze their state history

Phase 8: Advanced Features (Week 15-16)

Priority: LOW - Nice-to-have enhancements

  1. Automatic State Capture

    • Periodic auto-snapshots
    • Significant change detection
    • Configurable triggers

  2. State Templates

    • Save state as template
    • Apply template to create new state
    • Template library

  3. Collaborative Features

    • Share timelines/scenarios
    • Comment on states
    • Approval workflows

  4. Advanced Analytics

    • Network metrics over time
    • Predictive modeling
    • Statistical analysis
    • Export to analysis tools

5. File Structure

/src
├── types/
│   ├── index.ts (existing)
│   └── temporal.ts (NEW)
│
├── stores/
│   ├── workspaceStore.ts (update)
│   ├── stateStore.ts (NEW)
│   ├── panelStore.ts (existing)
│   └── toastStore.ts (existing)
│
├── components/
│   ├── TemporalAnalysis/ (NEW)
│   │   ├── TimelinePanel.tsx
│   │   ├── StateSelector.tsx
│   │   ├── ComparisonView.tsx
│   │   ├── StateDiffViewer.tsx
│   │   ├── StateMetadataEditor.tsx
│   │   ├── ActorJourneyViewer.tsx
│   │   ├── StateAnimator.tsx
│   │   └── PresentationMode.tsx
│   │
│   ├── Panels/ (existing, update)
│   │   ├── LeftPanel.tsx
│   │   ├── RightPanel.tsx (update)
│   │   └── BottomPanel.tsx (update or replace)
│   │
│   ├── Toolbar/ (existing, update)
│   │   └── StateControls.tsx (NEW)
│   │
│   └── Menu/ (existing, update)
│       └── StatesMenu.tsx (NEW)
│
├── utils/
│   ├── stateComparison.ts (NEW)
│   ├── stateDiff.ts (NEW)
│   ├── stateAnimation.ts (NEW)
│   └── chromaIntegration.ts (NEW)
│
├── hooks/
│   ├── useStateManagement.ts (NEW)
│   ├── useStateDiff.ts (NEW)
│   ├── useStateAnimation.ts (NEW)
│   └── useActorJourney.ts (NEW)
│
└── contexts/
    └── StateContext.tsx (NEW, optional)

6. Terminology Guide

Old (Version Control) → New (Temporal/Scenario Analysis)

Old Term New Term Context
Version State / Timepoint / Scenario General
Commit Capture State / Create Snapshot Action
Checkout Load State / View State Action
Branch Create Scenario Branch Action
Version History Timeline / State History View
Version Graph Timeline / Scenario Tree Visualization
Diff Comparison / Change Analysis Analysis
Merge N/A (not applicable) -
Revert Restore State Action

7. UI/UX Wireframes

7.1 Bottom Timeline Panel

┌─────────────────────────────────────────────────────────────────┐
│ Timeline: Project Evolution          [+] Create State   [≡] View │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ ●─────●─────●─────●─────●────────┬──●────●────●         │   │
│  │ Q1    Q2    Q3    Q4    Current  │  B1   B2   B3        │   │
│  │ 2023  2023  2023  2023   (2024)  │ (Strat A)            │   │
│  │                                   │                       │   │
│  │                                   └──●────●              │   │
│  │                                      C1   C2             │   │
│  │                                   (Strat B)              │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                   │
│  Timeline: ◀ ▶   Scenarios: ▲ ▼   Compare: [Select Two]         │
└─────────────────────────────────────────────────────────────────┘

7.2 State Selector Dropdown

┌────────────────────────────────────┐
│ Current State: Q4 2023        ▼   │
├────────────────────────────────────┤
│ Recent States:                     │
│  ● Current (Unsaved)              │
│  ● Q4 2023                        │
│  ● Q3 2023                        │
│                                    │
│ Timelines:                         │
│  📅 Project Evolution (5 states)  │
│  📅 Historical (3 states)         │
│                                    │
│ Scenarios:                         │
│  🌿 Strategy A Branch (3 states)  │
│  🌿 Strategy B Branch (2 states)  │
│                                    │
│ [View All States] [New State]     │
└────────────────────────────────────┘

7.3 Comparison View

┌─────────────────────────────────────────────────────────────────┐
│ Compare States                                             [×]  │
├─────────────────────────────────────────────────────────────────┤
│ From: Q3 2023 ▼            To: Q4 2023 ▼        Mode: Side-by  │
├──────────────────────────────┬──────────────────────────────────┤
│                              │                                  │
│  State: Q3 2023             │  State: Q4 2023                 │
│                              │                                  │
│  [Graph Visualization]       │  [Graph Visualization]          │
│                              │                                  │
│  Actors: 12                  │  Actors: 15 (+3)                │
│  Relations: 18               │  Relations: 22 (+4)             │
│                              │                                  │
├──────────────────────────────┴──────────────────────────────────┤
│ Changes Summary:                                                │
│  Added: 3 actors, 4 relations                                  │
│  Removed: 0 actors, 0 relations                                │
│  Modified: 2 actors (properties changed)                       │
│                                                                 │
│  [View Detailed Changes] [Export Report]                       │
└─────────────────────────────────────────────────────────────────┘

8. Key Algorithms

8.1 State Diff Calculation

// /src/utils/stateDiff.ts

export function calculateStateDiff(
  fromState: AnalysisState,
  toState: AnalysisState
): StateDiff {
  const diff: StateDiff = {
    fromStateId: fromState.stateId,
    toStateId: toState.stateId,
    actorsAdded: [],
    actorsRemoved: [],
    actorsModified: [],
    relationsAdded: [],
    relationsRemoved: [],
    relationsModified: [],
    summary: {
      totalActorChanges: 0,
      totalRelationChanges: 0,
    },
  };

  // Create lookup maps
  const fromActors = new Map(
    fromState.snapshot.nodes.map(n => [n.id, n])
  );
  const toActors = new Map(
    toState.snapshot.nodes.map(n => [n.id, n])
  );

  // Find added actors
  toState.snapshot.nodes.forEach(actor => {
    if (!fromActors.has(actor.id)) {
      diff.actorsAdded.push(actor);
    }
  });

  // Find removed actors
  fromState.snapshot.nodes.forEach(actor => {
    if (!toActors.has(actor.id)) {
      diff.actorsRemoved.push(actor);
    }
  });

  // Find modified actors
  fromState.snapshot.nodes.forEach(fromActor => {
    const toActor = toActors.get(fromActor.id);
    if (toActor) {
      const changes = detectActorChanges(fromActor, toActor);
      if (Object.keys(changes).length > 0) {
        diff.actorsModified.push({
          actorId: fromActor.id,
          changes,
        });
      }
    }
  });

  // Similar logic for relations...

  // Calculate summary
  diff.summary.totalActorChanges =
    diff.actorsAdded.length +
    diff.actorsRemoved.length +
    diff.actorsModified.length;

  return diff;
}

function detectActorChanges(
  fromActor: SerializedActor,
  toActor: SerializedActor
): any {
  const changes: any = {};

  if (fromActor.data.label !== toActor.data.label) {
    changes.label = {
      from: fromActor.data.label,
      to: toActor.data.label,
    };
  }

  if (fromActor.data.type !== toActor.data.type) {
    changes.type = {
      from: fromActor.data.type,
      to: toActor.data.type,
    };
  }

  if (
    fromActor.position.x !== toActor.position.x ||
    fromActor.position.y !== toActor.position.y
  ) {
    changes.position = {
      from: fromActor.position,
      to: toActor.position,
    };
  }

  return changes;
}

8.2 Actor Journey Tracking

// /src/utils/actorJourney.ts

export function getActorJourney(
  actorId: string,
  states: AnalysisState[]
): ActorJourney {
  const appearances = states
    .map(state => {
      const actor = state.snapshot.nodes.find(n => n.id === actorId);
      if (actor) {
        return {
          stateId: state.stateId,
          stateLabel: state.temporal?.label || state.scenario?.label || 'Unknown',
          actor,
          timestamp: state.temporal?.timestamp,
        };
      }
      return null;
    })
    .filter(Boolean);

  return {
    actorId,
    label: appearances[0]?.actor.data.label || 'Unknown',
    appearances,
    firstAppearance: appearances[0]?.stateId || '',
    lastAppearance: appearances[appearances.length - 1]?.stateId || '',
    appearanceCount: appearances.length,
  };
}

8.3 State Animation Interpolation

// /src/utils/stateAnimation.ts

export function interpolateStates(
  fromState: AnalysisState,
  toState: AnalysisState,
  progress: number // 0 to 1
): { nodes: Actor[]; edges: Relation[] } {
  // For each actor, interpolate position and properties
  const interpolatedNodes = toState.snapshot.nodes.map(toNode => {
    const fromNode = fromState.snapshot.nodes.find(n => n.id === toNode.id);

    if (!fromNode) {
      // Actor being added - fade in
      return {
        ...toNode,
        style: {
          opacity: progress,
        },
      };
    }

    // Interpolate position
    const x = fromNode.position.x + (toNode.position.x - fromNode.position.x) * progress;
    const y = fromNode.position.y + (toNode.position.y - fromNode.position.y) * progress;

    return {
      ...toNode,
      position: { x, y },
    };
  });

  // Handle actors being removed (fade out)
  fromState.snapshot.nodes.forEach(fromNode => {
    const existsInTo = toState.snapshot.nodes.find(n => n.id === fromNode.id);
    if (!existsInTo) {
      interpolatedNodes.push({
        ...fromNode,
        style: {
          opacity: 1 - progress,
        },
      });
    }
  });

  // Similar logic for edges...

  return { nodes: interpolatedNodes, edges: interpolatedEdges };
}

9. ChromaDB Integration Details

9.1 Collections Structure

// State metadata collection
const stateMetadataCollection = {
  name: 'constellation_states',
  metadata: {
    description: 'Analysis states with temporal and scenario metadata',
  },
};

// Documents to index:
{
  id: stateId,
  embedding: [/* vector from description + notes + assumptions */],
  metadata: {
    documentId: string,
    stateType: 'temporal' | 'scenario',
    label: string,
    timestamp?: string,
    tags: string[],
    actorCount: number,
    relationCount: number,
  },
  document: `${label} ${description} ${notes} ${assumptions.join(' ')}`,
}

// Actor journey collection
const actorJourneyCollection = {
  name: 'actor_journeys',
  metadata: {
    description: 'Actor trajectories across states',
  },
};

// Comparison results collection (caching)
const comparisonCacheCollection = {
  name: 'state_comparisons',
  metadata: {
    description: 'Cached comparison results',
  },
};

9.2 Query Examples

// Find states by semantic search
async function searchStates(query: string): Promise<AnalysisState[]> {
  const results = await chromaClient.query({
    collection: 'constellation_states',
    queryTexts: [query],
    nResults: 10,
  });

  // Retrieve full states from store
  return results.ids[0].map(id => stateStore.states.get(id));
}

// Find similar states (pattern recognition)
async function findSimilarStates(stateId: string): Promise<AnalysisState[]> {
  const state = stateStore.states.get(stateId);
  const description = generateStateDescription(state);

  const results = await chromaClient.query({
    collection: 'constellation_states',
    queryTexts: [description],
    nResults: 5,
    where: {
      documentId: state.documentId,
      stateId: { $ne: stateId }, // Exclude self
    },
  });

  return results.ids[0].map(id => stateStore.states.get(id));
}

// Track actor mentions across states
async function findStatesWithActor(actorLabel: string): Promise<AnalysisState[]> {
  const results = await chromaClient.query({
    collection: 'constellation_states',
    queryTexts: [actorLabel],
    nResults: 20,
    where: {
      tags: { $contains: 'actor:' + actorLabel },
    },
  });

  return results.ids[0].map(id => stateStore.states.get(id));
}

10. Testing Strategy

10.1 Unit Tests

  • State creation and serialization
  • Diff calculation accuracy
  • Actor journey tracking
  • Timeline ordering
  • Scenario branching logic

10.2 Integration Tests

  • State store integration with workspace store
  • ChromaDB indexing and retrieval
  • UI component interactions
  • Animation performance

10.3 User Acceptance Tests

  • Create temporal sequence (historical and projected)
  • Create scenario branches
  • Compare two states visually
  • Track actor through timeline
  • Animate transition between states
  • Export comparison report
  • Search states semantically

11. Migration Strategy

11.1 Existing Documents

Documents without state support will continue to work normally. The states property in ConstellationDocument is optional.

11.2 Enabling States for Existing Documents

Users can "enable" temporal analysis for any document:

function enableStatesForDocument(documentId: string) {
  const doc = workspaceStore.documents.get(documentId);
  if (!doc) return;

  // Create initial state from current graph
  const initialState: AnalysisState = {
    stateId: generateStateId(),
    stateType: 'temporal',
    snapshot: {
      nodes: doc.graph.nodes,
      edges: doc.graph.edges,
    },
    temporal: {
      label: 'Initial State',
      timestamp: new Date().toISOString(),
      sequenceNumber: 0,
    },
    relationships: [],
    notes: 'Initial state captured when enabling temporal analysis',
    createdAt: new Date().toISOString(),
  };

  doc.states = {
    stateList: [initialState],
    currentStateId: initialState.stateId,
    timelines: [{
      timelineId: generateTimelineId(),
      label: 'Main Timeline',
      states: [initialState.stateId],
      displaySettings: {
        showGrid: true,
        autoLayout: true,
      },
    }],
    scenarioTrees: [],
    settings: {
      enableAutoDiff: true,
      showChangeIndicators: true,
      defaultStateType: 'temporal',
    },
  };

  doc.metadata.supportsStates = true;
  saveDocumentToStorage(documentId, doc);
}

12. Performance Considerations

12.1 State Storage

  • Store states in separate IndexedDB entries (not inline with document)
  • Lazy load states on demand
  • Implement state pagination for documents with many states

12.2 Diff Calculation

  • Cache diff results in ChromaDB
  • Compute diffs in Web Worker for large graphs
  • Implement incremental diff for sequential states

12.3 Animation

  • Use requestAnimationFrame for smooth animations
  • Implement frame skipping for performance
  • Provide quality/performance toggle

12.4 ChromaDB

  • Batch index operations
  • Implement indexing queue
  • Cache frequently accessed queries
  • Use metadata filtering to reduce embedding computations

13. Future Enhancements (Post-MVP)

13.1 Advanced Analytics

  • Network density over time
  • Centrality metrics evolution
  • Clustering coefficient changes
  • Community detection across states

13.2 Predictive Modeling

  • Extrapolate future states
  • Trend analysis
  • Anomaly detection
  • Pattern-based predictions

13.3 Collaborative Features

  • Share timelines with team
  • Comment threads on specific changes
  • Approval workflows for scenarios
  • Real-time collaboration

13.4 Export Capabilities

  • Export as video/GIF
  • Generate PowerPoint presentations
  • PDF reports with comparison analysis
  • Interactive HTML export

13.5 Integration

  • Import time-series data from external sources
  • API for programmatic state creation
  • Webhook triggers for auto-capture
  • Integration with project management tools

14. Success Metrics

14.1 Feature Adoption

  • % of documents with states enabled
  • Average number of states per document
  • Timeline vs. scenario usage ratio

14.2 User Engagement

  • Time spent in comparison view
  • Number of comparisons per session
  • Animation playback usage
  • Actor journey queries

14.3 Performance

  • State creation time < 500ms
  • Diff calculation time < 1s for typical graphs
  • Animation frame rate > 30fps
  • ChromaDB query latency < 200ms

15. Documentation Plan

15.1 User Guide

  • "Getting Started with Temporal Analysis"
  • "Creating and Managing Timelines"
  • "Exploring Scenarios"
  • "Comparing States Effectively"
  • "Tracking Actor Journeys"
  • "Presentation Mode Tutorial"

15.2 Developer Documentation

  • State data model reference
  • API documentation for stateStore
  • ChromaDB integration guide
  • Custom animation plugins
  • Extension points for advanced analytics

Conclusion

This implementation plan transforms Constellation Analyzer from a static graph editor into a powerful temporal and scenario analysis tool. By focusing on storytelling, comparison, and analysis rather than version control, we enable users to:

  1. Understand evolution: Track how networks change over time
  2. Explore alternatives: Branch and compare different scenarios
  3. Analyze dynamics: Identify patterns and trends
  4. Communicate insights: Present findings effectively

The phased approach ensures we deliver value incrementally while building toward a comprehensive solution. ChromaDB integration adds semantic search and pattern recognition capabilities that elevate the tool beyond simple visualization.

Recommended Starting Point: Begin with Phase 1 (Core State Management) and Phase 2 (Temporal Analysis) as these provide immediate value and establish the foundation for all subsequent features.