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

> Explore the Palmier Pro project structure, a complete architecture guide for the Swift video editor. Understand its purpose-driven directories for UI, data, logic, media, AI, and export.

- Repository: [Palmier/palmier-pro](https://github.com/palmier-io/palmier-pro)
- Tags: architecture
- Published: 2026-06-30

---

**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`](https://github.com/palmier-io/palmier-pro/blob/main/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`](https://github.com/palmier-io/palmier-pro/blob/main/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`](https://github.com/palmier-io/palmier-pro/blob/main/server/index.js) and [`manifest.json`](https://github.com/palmier-io/palmier-pro/blob/main/manifest.json).
- **`scripts/`** – Build and release automation scripts ([`dev.sh`](https://github.com/palmier-io/palmier-pro/blob/main/dev.sh), [`release.sh`](https://github.com/palmier-io/palmier-pro/blob/main/release.sh), [`bundle.sh`](https://github.com/palmier-io/palmier-pro/blob/main/bundle.sh)).
- **`docs/`** and **`assets/`** – Documentation and README images.

## Application Bootstrap and Global State

The entry point at [`Sources/PalmierPro/App/main.swift`](https://github.com/palmier-io/palmier-pro/blob/main/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`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/App/AppState.swift), holds app-wide services and preferences, injected into the view hierarchy via SwiftUI’s environment.

```swift
// 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`](https://github.com/palmier-io/palmier-pro/blob/main/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`](https://github.com/palmier-io/palmier-pro/blob/main/Timeline.swift)** – Manages ordered tracks and clips.
- **[`MediaAsset.swift`](https://github.com/palmier-io/palmier-pro/blob/main/MediaAsset.swift)** – Wraps video/audio files, thumbnails, and metadata.
- **[`Keyframe.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Keyframe.swift)**, **[`BlendMode.swift`](https://github.com/palmier-io/palmier-pro/blob/main/BlendMode.swift)**, **[`Effect.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Effect.swift)** – Describe compositing and animation properties.

Project-level orchestration resides in `Sources/PalmierPro/Project/`. The **[`VideoProject.swift`](https://github.com/palmier-io/palmier-pro/blob/main/VideoProject.swift)** struct aggregates the timeline, media library, and user settings, while **[`ProjectRegistry.swift`](https://github.com/palmier-io/palmier-pro/blob/main/ProjectRegistry.swift)** handles persistence and disk operations.

```swift
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`](https://github.com/palmier-io/palmier-pro/blob/main/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.

```swift
// 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`](https://github.com/palmier-io/palmier-pro/blob/main/WaveformExtractor.swift)** – Extracts visual waveform data.
- **[`AudioTrackReader.swift`](https://github.com/palmier-io/palmier-pro/blob/main/AudioTrackReader.swift)** – Handles audio file reading.
- **[`AudioSyncCorrelator.swift`](https://github.com/palmier-io/palmier-pro/blob/main/AudioSyncCorrelator.swift)** – Assists AI-driven audio alignment.

## AI Generation Pipeline

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

- **[`GenerationService.swift`](https://github.com/palmier-io/palmier-pro/blob/main/GenerationService.swift)** – Orchestrates generation requests.
- **[`GenerationBackend.swift`](https://github.com/palmier-io/palmier-pro/blob/main/GenerationBackend.swift)** – Low-level HTTP client for the MCP server.
- **[`VideoGenerationSubmission.swift`](https://github.com/palmier-io/palmier-pro/blob/main/VideoGenerationSubmission.swift)** – Represents pending generation jobs.

UI components trigger generation through the ViewModel extension:

```swift
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`](https://github.com/palmier-io/palmier-pro/blob/main/ExportCoordinator.swift)** orchestrates the workflow, while **[`ExportService.swift`](https://github.com/palmier-io/palmier-pro/blob/main/ExportService.swift)** handles file I/O and progress reporting. Specific converters like **[`FCPXMLExporter.swift`](https://github.com/palmier-io/palmier-pro/blob/main/FCPXMLExporter.swift)** and **[`PalmierProjectExporter.swift`](https://github.com/palmier-io/palmier-pro/blob/main/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.

```swift
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`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/App/main.swift) bootstraps the application and `AppState`.
- **Design System** – Centralized in [`Sources/PalmierPro/UI/AppTheme.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Sources/PalmierPro/UI/AppTheme.swift).
- **Domain Models** – [`Timeline.swift`](https://github.com/palmier-io/palmier-pro/blob/main/Timeline.swift), [`MediaAsset.swift`](https://github.com/palmier-io/palmier-pro/blob/main/MediaAsset.swift), and related structs define the editing domain.
- **Persistence** – [`ProjectRegistry.swift`](https://github.com/palmier-io/palmier-pro/blob/main/ProjectRegistry.swift) and [`VideoProject.swift`](https://github.com/palmier-io/palmier-pro/blob/main/VideoProject.swift) manage project lifecycle.
- **Editor Logic** – [`EditorViewModel.swift`](https://github.com/palmier-io/palmier-pro/blob/main/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`](https://github.com/palmier-io/palmier-pro/blob/main/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`](https://github.com/palmier-io/palmier-pro/blob/main/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`](https://github.com/palmier-io/palmier-pro/blob/main/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`](https://github.com/palmier-io/palmier-pro/blob/main/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.