Meshtastic-Apple/.specify/memory/constitution.md

Meshtastic Apple Constitution

Core Principles

I. SwiftUI-Native

All user interface code MUST be built with SwiftUI. UIKit views are not permitted. New views MUST follow the existing feature-folder structure under Meshtastic/Views/ (e.g., Messages/, Nodes/, Settings/, Connect/). Reusable view components MUST be placed in Meshtastic/Views/Helpers/. Navigation state MUST flow through the centralized Router — views MUST NOT manage their own tab or deep-link routing.

Rationale: A single UI framework eliminates cross-paradigm complexity and keeps the codebase approachable for contributors familiar with modern Apple development.

II. Core Data Persistence

All persistent application data MUST be stored in Core Data using the existing PersistenceController.shared singleton. Schema changes MUST be added as a new numbered model version (currently V57) with appropriate migration support. Entity query functions MUST reside in Meshtastic/Persistence/QueryCoreData.swift. Entity update operations MUST be performed through the MeshPackets actor on a background context to ensure thread safety. Entity extensions providing computed properties MUST be placed in Meshtastic/Extensions/CoreData/.

Rationale: Core Data is the established persistence layer with 57 migration versions. Consistency in where queries and updates live prevents data-access fragmentation.

III. Protocol-Oriented Transport

All device communication MUST go through the Transport and Connection protocol abstractions defined in Meshtastic/Accessory/Protocols/. New transport types MUST implement these protocols and be registered in AccessoryManager. Direct CoreBluetooth or network calls outside the Accessory layer are not permitted. The AccessoryManager singleton MUST be the single entry point for connection lifecycle management. Legacy BLEManager references MUST be migrated to AccessoryManager when touched.

Rationale: The protocol-oriented transport layer enables BLE, TCP, and Serial transports to be swapped transparently. Centralizing connection state prevents race conditions and duplicated logic.

IV. Structured Logging

All diagnostic output MUST use the OSLog Logger extension defined in Meshtastic/Extensions/Logger.swift with the appropriate category (.admin, .data, .mesh, .mqtt, .radio, .services, .transport, .tak). print() statements are banned and enforced by the disable_print SwiftLint custom rule. New subsystem categories MUST be added to the Logger extension when introducing a distinct functional area.

Rationale: Structured, categorized logging enables effective filtering in Console.app and integrates with the Datadog observability pipeline. Unstructured print output is invisible in production.

V. Protobuf Contract Fidelity

All Meshtastic wire-protocol types MUST be generated from the protobufs/ git submodule using scripts/gen_protos.sh. Hand-editing generated .pb.swift files in MeshtasticProtobufs/Sources/ is forbidden. Proto extensions and convenience accessors MUST be placed in Meshtastic/Extensions/Protobufs/. When upstream proto definitions change, the generation script MUST be re-run and the resulting changes committed atomically.

Rationale: Generated protobuf code ensures type-safe interoperability with Meshtastic firmware. Manual edits create drift that breaks cross-platform compatibility.

VI. Lint-Clean Commits

All committed Swift code MUST pass SwiftLint validation. The pre-commit hook (scripts/hooks/pre-commit) MUST remain active and auto-fix lint issues on staged files. The project uses two SwiftLint configurations: .swiftlint.yml for IDE use and .swiftlint-precommit.yml for the commit hook. Generated code in MeshtasticProtobufs/ is excluded from linting. New SwiftLint rules MUST NOT be disabled without documented justification.

Rationale: Automated lint enforcement at commit time prevents style drift and keeps PRs focused on logic rather than formatting.

VII. Platform Parity

The app MUST support the last two major OS versions on iOS, iPadOS, and macOS (via Catalyst). Platform-specific code MUST use conditional compilation (#if targetEnvironment(macCatalyst), #if canImport(ActivityKit)). Features available on one platform SHOULD have graceful degradation or equivalent functionality on others. SFSymbols MUST be used for all iconography to ensure cross-platform rendering consistency.

Rationale: Meshtastic users span Apple devices. Conditional compilation keeps a single codebase while respecting platform capabilities.

Technology Stack & Constraints

• Language: Swift (latest stable), using Swift Concurrency (actor, @MainActor, async/await)
• UI: SwiftUI with ObservableObject / @Published state management
• Persistence: Core Data (NSPersistentContainer) with progressive migration
• Networking: CoreBluetooth (BLE), Network.framework (TCP), IOKit (Serial/macCatalyst), CocoaMQTT (MQTT proxy)
• Protobufs: apple/swift-protobuf (>= 1.33.3) via local SPM package
• Observability: Datadog SDK (RUM, Crash Reporting, Logs, Tracing, Session Replay on TestFlight)
• Testing: Swift Testing framework (@Suite, @Test, #expect, #require)
• Linting: SwiftLint with pre-commit hook auto-fix
• CI/CD: Xcode Cloud with pre-build secrets injection
• IDE: Latest release version of Xcode
• License: GPL v3
• Deep Links: meshtastic:/// URL scheme for navigation, shortcuts, and widget integration

Development Workflow

• Branching: Trunk-based development targeting main. Release branches follow X.YY.ZZ-release naming via scripts/create-release-branch.sh.
• Commits: Imperative mood subject line. Body explains what and why. Rebase onto main before PR — no merge commits in feature branches.
• Pull Requests: Target main. Small, incremental, self-contained changes. PR description MUST clearly describe the change. Code review by a project maintainer is required before merge.
• Testing: All existing tests MUST pass before PR submission. New features and bug fixes SHOULD include tests using the Swift Testing framework in MeshtasticTests/.
• Git Hooks: Contributors MUST run scripts/setup-hooks.sh to install the pre-commit lint hook.
• Protobuf Updates: Run scripts/gen_protos.sh, build, test, and commit the generated changes.
• Documentation: Update project documentation to reflect changes. Release notes go in Meshtastic/RELEASENOTES.md.

Governance

This constitution is the authoritative reference for architectural decisions and development standards in the Meshtastic Apple repository. All pull requests and code reviews MUST verify compliance with these principles.

• Amendments require a documented rationale, maintainer approval, and an updated constitution version. Changes MUST include a migration plan if they affect existing code.
• Versioning follows semantic versioning: MAJOR for backward-incompatible principle changes, MINOR for new principles or expanded guidance, PATCH for clarifications and typo fixes.
• Compliance review: Maintainers SHOULD periodically audit the codebase against these principles, particularly during major releases.
• Complexity justification: Deviations from these principles MUST be justified in the PR description and approved by a maintainer.

Version: 1.0.0 | Ratified: 2026-04-15 | Last Amended: 2026-04-15