Building a document browser app for custom file formats

At a glance

Project structure

Particles/
├── DocumentBrowserViewController.swift
├── DocumentViewController.swift
├── Document.swift
├── ParticleViewController.swift
├── EditorViewController.swift
└── AppDelegate.swift
ParticlesPreview/
└── PreviewViewController.swift
ParticlesThumbnails/
└── ThumbnailProvider.swift

Structure observations

• Document and particle rendering form the reusable core consumed by three targets.
• The main document screen composes separate renderer and inspector children.
• Quick Look targets adapt the core instead of duplicating file decoding or visual representation.

Overall architecture

flowchart LR
    Browser["DocumentBrowserViewController"] --> Document["Document : UIDocument"]
    Browser --> Screen["DocumentViewController"]
    Screen --> Particle["ParticleViewController"]
    Screen --> Editor["EditorViewController"]
    Screen --> Document
    Particle --> Document
    Editor --> Document
    Document --> System["SCNParticleSystem"]
    Preview["Quick Look Preview extension"] --> Document
    Preview --> Particle
    Thumbnail["Thumbnail extension"] --> Document
    Thumbnail --> Particle

Reference code

Particles/DocumentViewController.swift:77 — the compound screen opens one coordinated document and injects it into both child feature owners.

func setDocument(_ document: Document, completion: @escaping () -> Void) {
    self.document = document
    loadViewIfNeeded()
    document.open { success in
        if success {
            self.particleViewController.document = self.document
            self.editorViewController.document = self.document
        }
        completion()
    }
}

Interpretation

The custom-format boundary is Document, not a view controller. Main app and extensions open that same type and reuse ParticleViewController; only the surrounding lifecycle adapter changes.

Ownership and state

classDiagram
    DocumentBrowserViewController *-- UIDocumentBrowserTransitionController : retains current transition
    DocumentViewController *-- Document : retains while open
    DocumentViewController *-- ParticleViewController : creates
    DocumentViewController *-- EditorViewController : creates
    Document *-- SCNParticleSystem : decoded model
    ParticleViewController o-- Document : receives
    EditorViewController o-- Document : receives
    PreviewViewController *-- ParticleViewController : creates child
    ThumbnailProvider --> ParticleViewController : creates temporarily

Ownership evidence

Particles/DocumentViewController.swift:11 — document replacement is read-only to collaborators, while the compound controller privately owns its children.

class DocumentViewController: UIViewController {
    private(set) var document: Document?
    private let particleNavigationController = UINavigationController()
    private let particleViewController = ParticleViewController()
    private let editorViewController = EditorViewController()
}

Class and protocol design

The sample uses framework protocols at integration boundaries; it does not introduce an app-defined document-service protocol.

Access control

Reference code

Particles/EditorViewController.swift:74 — the inspector exposes its document input while keeping table schema and derived model access private.

private lazy var dataSource = makeDataSource()
var document: Document? { didSet { readValues() } }
private var particleSystem: SCNParticleSystem? { document?.particleSystem }
private var settings = [
    EditorSetting(keyPath: "birthRate", label: "Birth Rate", min: 0.1, max: 100, transformer: nil)
]

Logic ownership and placement

Design patterns

Naming conventions

• Document, DocumentBrowserViewController, and DocumentViewController distinguish model, root browser, and open-session UI.
• ParticleViewController names the reusable renderer; EditorViewController names mutation UI.
• Extension entry types use framework roles: PreviewViewController and ThumbnailProvider.
• Commands use lifecycle verbs: presentDocument, setDocument, open, close, and provideThumbnail.

Architecture takeaways

• Make the UIDocument subclass the custom-format authority shared by app and extensions.
• Reuse a focused renderer across editing, preview, and thumbnail contexts.
• Let the visible document screen own open/close and inject one document into child views.
• Use private(set) when navigation/restoration needs to inspect the current document but must not replace it.

Source map

• Official Apple documentation