Data Flow

This page documents the key data flows and workflows in SpecTacular.

Project Initialization Flow

The complete flow from CLI installation to first spec.

File Editing Workflow

Complete cycle from opening a file to saving edits.

Task Status Auto-Update Flow

Automatic status updates when acceptance criteria are checked.

File Watching Flow

Real-time updates from external file changes (e.g., git pull).

AI Workflow Pipeline

Specification-driven development workflow using AI commands.

Configuration Loading Flow

How configuration is loaded and merged.

State Management

Extension Host State

Persistent:

• Global configuration (~/.spectacular/config.json)
• Workspace state (VS Code workspaceState)

Runtime:

• File watcher instances
• Dashboard panel instance (singleton)
• Modified files tracking
• Navigation history

Webview State

Persisted (via vscodeApi.setState()):

{
  currentFile: string | null;
  modifiedFiles: [string, string][]; // Map entries
  navigationHistory: string[];
  historyIndex: number;
}

Runtime (React state):

{
  rootPath: string | null;
  fileContent: string;
  isLoading: boolean;
  error: string | null;
  theme: 'light' | 'dark';
  isWatching: boolean;
}

Error Propagation

Extension → Webview

try {
  const content = await fs.readFile(filePath, 'utf8');
  panel.webview.postMessage({
    type: 'fileContent',
    data: { path: filePath, content }
  });
} catch (error) {
  panel.webview.postMessage({
    type: 'error',
    data: {
      message: `Failed to read file: ${error.message}`,
      code: 'READ_ERROR',
      path: filePath
    }
  });
}

Webview → User

useEffect(() => {
  const handleMessage = (event: MessageEvent) => {
    if (event.data.type === 'error') {
      setError(event.data.data.message);
      // Show error in UI
      toast.error(event.data.data.message);
    }
  };

  window.addEventListener('message', handleMessage);
  return () => window.removeEventListener('message', handleMessage);
}, []);

Performance Optimizations

Debouncing

Operation	Delay	Reason
File watcher	300ms	Batch rapid changes (git pull)
Search input	500ms	Reduce search queries
Auto-save (disabled)	N/A	Manual save only (Ctrl+S)

Lazy Loading

Resource	Strategy
File tree	Load on demand (expand folder)
File content	Load when selected
Markdown rendering	Render visible content only
Images	Lazy load images in preview

Caching

Data	Cache Location	Invalidation
File tree	Extension host memory	File watcher events
File content	Webview state	File change events
Rendered markdown	TipTap document	Content change
Configuration	Extension host	Config file change

Next Steps

• CLI Architecture - CLI tool details
• Extension Architecture - Extension host architecture
• Webview Architecture - React UI architecture
• Message Protocol - Communication details
• Overview - System overview