Architecture

opencut/
├── apps/
│   └── web/                    # Main Next.js application
│       ├── src/
│       │   ├── components/     # UI and editor components
│       │   ├── core/           # EditorCore singleton and managers
│       │   ├── hooks/          # Custom React hooks
│       │   ├── lib/            # Domain-specific logic
│       │   ├── services/       # External service integrations
│       │   ├── stores/         # State management (Zustand)
│       │   ├── types/          # TypeScript type definitions
│       │   └── utils/          # Generic helper utilities
│       ├── public/             # Static assets
│       └── package.json
├── packages/
│   ├── ui/                     # Shared UI component library
│   └── env/                    # Environment variable validation
├── docker-compose.yml
├── turbo.json                  # Turborepo configuration
└── package.json                # Root package.json

EditorCore (singleton)
├── command: CommandManager        # Undo/redo system
├── playback: PlaybackManager      # Video playback controls
├── timeline: TimelineManager      # Timeline and track management
├── scenes: ScenesManager          # Scene composition
├── project: ProjectManager        # Project metadata and settings
├── media: MediaManager            # Media asset management
├── renderer: RendererManager      # Preview and export rendering
├── save: SaveManager              # Auto-save functionality
├── audio: AudioManager            # Audio processing
└── selection: SelectionManager    # Element selection state

import { useEditor } from '@/hooks/use-editor';

function MyComponent() {
  const editor = useEditor();
  const tracks = editor.timeline.getTracks();

  // Call methods
  editor.timeline.addTrack({ type: 'media' });

  // Display data (auto re-renders on changes)
  return <div>{tracks.length} tracks</div>;
}

// In utilities, event handlers, or non-React code
import { EditorCore } from "@/core";

const editor = EditorCore.getInstance();
await editor.export({ format: "mp4", quality: "high" });

export const ACTIONS = {
  "split-selected": {
    description: "Split selected elements at playhead",
    category: "editing",
    defaultShortcuts: ["ctrl+b"],
  },
  "delete-selected": {
    description: "Delete selected elements",
    category: "editing",
    defaultShortcuts: ["Delete"],
  },
  // ...
};

import { useActionHandler } from '@/hooks/use-action-handler';

function useEditorActions() {
  const editor = useEditor();

  useActionHandler(
    "split-selected",
    () => {
      const selected = editor.selection.getSelectedElements();
      if (selected.length === 0) {
        toast.error("No elements selected");
        return;
      }
      editor.timeline.splitElements({ ids: selected });
      toast.success("Elements split");
    },
    undefined,
  );
}

import { invokeAction } from '@/lib/actions';

// Good - uses action system (toasts, validation, shortcuts)
const handleSplit = () => invokeAction("split-selected");

// Avoid - bypasses UX layer
const handleSplit = () => editor.timeline.splitElements({ ... });

import { Command } from './base-command';

export class SplitElementCommand extends Command {
  private previousState: any;

  constructor(private elementId: string) {
    super();
  }

  execute() {
    // Save current state
    this.previousState = getCurrentState();
    
    // Perform the mutation
    splitElement(this.elementId);
  }

  undo() {
    // Restore the saved state
    restoreState(this.previousState);
  }
}

lib/commands/
├── base-command.ts         # Base Command class
├── timeline/               # Timeline-related commands
├── media/                  # Media asset commands
└── scene/                  # Scene composition commands

import { create } from 'zustand';

export const useUIStore = create((set) => ({
  sidebarOpen: true,
  toggleSidebar: () => set((state) => ({ 
    sidebarOpen: !state.sidebarOpen 
  })),
}));