docs: Add strategy for project structure refactoring

[philprime]

#skip-changelog

[philprime]

From Project Structure Discussion (Nov 20, 2025):

Attendees: @philprime @philipphofmann @itaybre @noahsmartin

Instead of adding targets to Xcode (even if in a SPM structure) we should migrate to SPM first and use targets there

Order of migration:

1. We should start off with removing SentryDependencyContainer.sharedInstance()
2. Replace Cocoapods with SPM to build Xcode framework
3. Remove Xcode project to test
4. Remove Xcode project to build
5. Rewrite integration types in Swift (e.g. SentryCrashIntegration.m) ← highest priority

Step 1, 2, 3 and 5 can be parallelized.

Important: Framework built with Cocoapods is not the same as a framework built with SPM.

Caveat: Internal types need to be public to be exposed when using in hierarchy:

// Package.swift

.target(name: "TargetA", dependencies: ["TargetB")

// Target A
import TargetB

public class TargetA {
  public func getUser() -> User? {
    nil
  }
}

// Target B

public class User {}

We would have to wrap internal types:

// Target A
import TargetB

public class TargetA {
  public func getUser() -> UserWrapper? {
    nil
  }
}

public class UserWrapper {
  private let user: User
}

Modules are not the only way to enforce architecture, e.g. using namespaces via enum types.

• Create issues for todo list (@philprime)

[philprime]

Closing this in favor of follow-up issues