Palmier Pro Project Structure: Complete Architecture Guide for the Swift Video Editor

Palmier Pro organizes its Swift codebase into purpose-driven directories that separate UI components, data models, editor logic, media processing, AI generation, and export pipelines, with clear architectural entry points in Sources/PalmierPro/App/ and business logic centralized in observable ViewModels.

The Palmier Pro project structure is designed for a modern macOS-only video editing application built entirely in Swift. Hosted at palmier-io/palmier-pro, the repository follows a clean, layered architecture that separates concerns across distinct modules, making it easy to locate functionality ranging from GPU-accelerated color grading to AI-driven clip generation.

High-Level Directory Layout

The repository root organizes code and resources into clearly defined top-level folders. Swift Package Manager manages the build process via Package.swift, while production code lives exclusively under Sources/.

• Sources/ – Contains all production Swift code organized by functional domain (App, UI, Models, Editor, Generation, Export, Audio, MediaPanel, Utilities, Project, Telemetry).
• Tests/ – Houses unit and integration tests, such as Tests/PalmierProTests/Transcription/TranscriptSearchTests.swift.
• Metal/ – Stores custom GPU shaders for video effects, including HueCurves.metal and GradeCurves.metal.
• mcpb/ – Minimal MCP server shipped with the application containing server/index.js and manifest.json.
• scripts/ – Build and release automation scripts (dev.sh, release.sh, bundle.sh).
• docs/ and assets/ – Documentation and README images.

Application Bootstrap and Global State

The entry point at Sources/PalmierPro/App/main.swift launches the macOS application, instantiates the top-level AppState, and registers the updater. The AppState object, defined in Sources/PalmierPro/App/AppState.swift, holds app-wide services and preferences, injected into the view hierarchy via SwiftUI’s environment.

// Sources/PalmierPro/App/main.swift (simplified)
import SwiftUI
import PalmierPro

@main
struct PalmierProApp: App {
    @StateObject private var appState = AppState()
    var body: some Scene {
        WindowGroup {
            ContentView()
                .environmentObject(appState)
        }
    }
}

Visual consistency is enforced through Sources/PalmierPro/UI/AppTheme.swift, which defines the design system. All views consume AppTheme.Spacing, AppTheme.FontSize, and AppTheme.Color to guarantee uniform styling and simplify future theming.

Core Data Models and Project Management

The Models directory at Sources/PalmierPro/Models/ defines the domain layer representing the video editing timeline and its components:

• Timeline.swift – Manages ordered tracks and clips.
• MediaAsset.swift – Wraps video/audio files, thumbnails, and metadata.
• Keyframe.swift, BlendMode.swift, Effect.swift – Describe compositing and animation properties.

Project-level orchestration resides in Sources/PalmierPro/Project/. The VideoProject.swift struct aggregates the timeline, media library, and user settings, while ProjectRegistry.swift handles persistence and disk operations.

import PalmierPro

// Create and save a new project
let project = VideoProject(name: "My First Film")
project.timeline.addTrack()
project.timeline.addClip(
    MediaAsset(url: Bundle.main.url(forResource: "intro", withExtension: "mov")!),
    at: .zero
)
try ProjectRegistry.shared.save(project)

Editor Architecture and ViewModels

Interactive editing logic is centralized in Sources/PalmierPro/Editor/ViewModel/ using the MVVM pattern. The EditorViewModel.swift serves as the primary observable object driving the UI, with focused extensions breaking functionality into manageable units:

• EditorViewModel+Tracks.swift – Track manipulation.
• EditorViewModel+Selection.swift – Selection handling.
• EditorViewModel+AIEdit.swift – AI generation integration.

The ViewModel is injected into SwiftUI views via environmentObject, enabling reactive updates across the interface.

// Inside a SwiftUI view with @EnvironmentObject var vm: EditorViewModel
Button("Add Clip") {
    let asset = MediaAsset(url: selectedURL)
    vm.addClip(asset, to: vm.timeline.currentTrack, at: vm.playheadPosition)
}

Media, Audio, and Drag-and-Drop

The MediaPanel/ directory provides the library UI for browsing assets. Due to SwiftUI’s .onDrop limitations with nested targets, the implementation uses a hybrid AppKit-based drop area (MediaPanelDropArea) to handle complex drag-and-drop interactions.

Audio processing utilities in Sources/PalmierPro/Audio/ support the timeline’s waveform visualization:

• WaveformExtractor.swift – Extracts visual waveform data.
• AudioTrackReader.swift – Handles audio file reading.
• AudioSyncCorrelator.swift – Assists AI-driven audio alignment.

AI Generation Pipeline

The Generation module at Sources/PalmierPro/Generation/ interfaces with external AI services:

• GenerationService.swift – Orchestrates generation requests.
• GenerationBackend.swift – Low-level HTTP client for the MCP server.
• VideoGenerationSubmission.swift – Represents pending generation jobs.

UI components trigger generation through the ViewModel extension:

func generateClip(prompt: String) async {
    await editorViewModel.generateClip(with: prompt) { result in
        switch result {
        case .success(let newClip):
            editorViewModel.insertGeneratedClip(newClip)
        case .failure(let error):
            print("Generation failed:", error.localizedDescription)
        }
    }
}

Export Pipeline and GPU Effects

The Export/ directory implements a multi-stage export system. ExportCoordinator.swift orchestrates the workflow, while ExportService.swift handles file I/O and progress reporting. Specific converters like FCPXMLExporter.swift and PalmierProjectExporter.swift translate internal project data into external formats such as Final Cut Pro XML.

GPU-accelerated video effects reside in the Metal/ folder, containing .metal files like HueCurves.metal and GradeCurves.metal that perform color grading on the GPU.

func exportCurrentProject() async throws {
    let exporter = ExportCoordinator(project: editorViewModel.project)
    try await exporter.export(to: .fcpXML, destination: URL(fileURLWithPath: "/tmp/MyFilm.fcpxml"))
}

Summary

Understanding the Palmier Pro project structure enables efficient navigation and extension of the codebase:

• Entry Point – Sources/PalmierPro/App/main.swift bootstraps the application and AppState.
• Design System – Centralized in Sources/PalmierPro/UI/AppTheme.swift.
• Domain Models – Timeline.swift, MediaAsset.swift, and related structs define the editing domain.
• Persistence – ProjectRegistry.swift and VideoProject.swift manage project lifecycle.
• Editor Logic – EditorViewModel.swift and its extensions handle all user interactions.
• Specialized Pipelines – Dedicated directories for Audio/, Generation/, and Export/ separate complex processing concerns.
• GPU Acceleration – Metal shaders in Metal/ provide hardware-accelerated effects.

Frequently Asked Questions

Where is the main entry point in the Palmier Pro project structure?

The application launches from Sources/PalmierPro/App/main.swift, which defines the @main SwiftUI App struct. This file creates the top-level AppState and sets up the main window group, injecting the global state into the view hierarchy.

How does Palmier Pro handle project persistence?

Project persistence is managed by Sources/PalmierPro/Project/ProjectRegistry.swift, which provides static methods to save and load VideoProject instances. The VideoProject struct itself, defined in Sources/PalmierPro/Project/VideoProject.swift, encapsulates the timeline, media library, and user settings as the single source of truth for an editing session.

What is the role of the EditorViewModel in the architecture?

The EditorViewModel serves as the central reactive coordinator between the UI and the data models. Located in Sources/PalmierPro/Editor/ViewModel/EditorViewModel.swift, it exposes observable state for the timeline and playhead, while extensions like EditorViewModel+AIEdit.swift and EditorViewModel+Tracks.swift encapsulate specific editing operations such as AI generation and track manipulation.

How are GPU video effects implemented in the codebase?

GPU-accelerated effects are implemented using Metal shaders stored in the top-level Metal/ directory. Files like HueCurves.metal and GradeCurves.metal contain compute shaders that perform color grading operations directly on the GPU, integrated with the Swift rendering pipeline.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}