Architecture overview¶

Developer-facing summary. End-user docs live under Home; this section is for contributors and anyone curious about how it all fits together.

Hard constraints¶

Settled during product discovery and unchanged since:

• No system-level changes required from the user (no kernel extensions, no Recovery Mode, no csrutil tweaks).
• Authentication only via interactive browser. Users only, never service principals or client secrets.
• Multi-tenant and multi-account simultaneously, identified by user-chosen short aliases (work, client-a).
• Install via Homebrew cask.
• No external runtime dependency for end users (no Python, no .NET, no Node).
• macOS 14 Sonoma or later on Apple Silicon (arm64) only.
• Project communication, code, comments, commit messages, PR descriptions all in English so anyone can contribute.

Tech stack at a glance¶

• Swift for everything: host app, File Provider Extension, and the OfemKit engine package. See Tech stack.
• OfemKit local Swift Package — houses auth (MSAL Swift), OneLake DFS + Fabric REST clients, SQLite metadata cache, sync engine, telemetry.
• MSAL for Apple Platforms for Microsoft Entra authentication (Keychain-backed).
• Azure Application Insights for opt-out telemetry.
• Homebrew cask for distribution. xcodebuild + codesign + notarytool + create-dmg for the signed .app.

Process model¶

┌────────────────────────────────┐     XPC (NSFileProviderService)
│  OneLake.app (host, Swift)     │◄────────────────────────────────┐
│  - account add/remove UI       │                                 │
│  - menu bar status icon        │                                 │
│  - registers domains           │                                 │
└────────────────────────────────┘     ┌─────────────────────────────┐
                                       │  OneLakeFileProvider.appex  │
                                       │  (Swift, sandboxed)         │
                                       │  - NSFileProvider* classes  │
                                       │  - OfemKit engine (in-proc) │
                                       │  - auth, cache, sync        │
                                       └─────────────────────────────┘

What each process does:

• The host app holds the account-management UI, registers File Provider domains, and shows the menu bar status icon. It communicates with the FPE via NSFileProviderManager.service(name:for:) + XPC (protocol OfemClientControlProtocol). The host app also registers itself as a login item via SMAppService.mainApp.
• The File Provider Extension is sandboxed and macOS launches it on demand when Finder needs files. It implements the NSFileProvider* classes and owns all engine logic: auth (MSAL Swift), OneLake DFS, Fabric REST, cache (SQLite + blobs), sync, and telemetry. The XPC contract itself (protocol, NSXPCInterface factory, config-key vocabulary) lives in Shared/ so it can't drift between the two processes — see File Provider.

Both processes share state through a macOS App Group (6D79CUWZ4J.group.dev.debruyn.ofem, team-prefixed for both Developer ID and Mac App Store): config TOML, the SQLite metadata cache, the cached blob shards, and the per-account Keychain entries.

Source layout¶

onelake-explorer-macos/
├── OneLake.xcodeproj             # generated by XcodeGen from project.yml
├── project.yml                   # XcodeGen spec
├── OneLake/                      # host app (Swift)
├── OneLakeFileProvider/          # File Provider Extension (Swift)
├── Shared/                       # XPC protocol + types shared by both targets
├── Packages/
│   └── OfemKit/                  # local Swift Package: engine, auth, cache, sync
├── docs/                         # this site's source
├── scripts/                      # check-prereqs, seed-labels
├── homebrew/                     # cask template (also lives in homebrew-ofem tap)
└── .github/                      # workflows, issue templates, FUNDING.yml

Where to read more¶