12. Design Decisions

Design Decisions

Language: English. Chinese version: 12. Design Decisions (中文)

This page records not only how the code works today, but why the project keeps making these choices. For long-term maintenance, those judgments are easier to lose than the visible implementation, and they are often more important.

Why Position It As A Decentralized Phone On MCU Hardware

Trail Mate exists so identity, contacts, messages, position, maps, and team awareness live on an MCU device without requiring cellular service, a central account, cloud infrastructure, or another phone.

That loop is concrete:

• a user needs to know where they are
• teammates need to keep basic communication
• a small team needs to know whether it is still together
• the device needs to support basic operation without requiring a phone

This makes it close to a decentralized phone without copying cellular-smartphone broadband behavior. Anonymous operation, decentralization, offline operation, and TAK are the four constraints for every design decision.

Why Reduce The Number Of Centers That Must Be Trusted

Privacy does not fail only when data leaks. When identity, contacts, position, messages, and behavior must pass through one platform to become useful, that platform controls the gateway, the data, and the power to interpret it. Each collection decision may have a local justification while their long-term aggregation still creates an imbalance that users cannot observe, challenge, or leave.

Trail Mate does not solve this by asking users to trust a nicer platform forever. It reduces required trust architecturally: local identity, local contacts, local data, offline maps, and on-device operation come first; cloud services, phones, MQTT, and Center remain optional connections. The system does not promise zero trust or absolute privacy, but every new design must explain whose trust it adds, what it collects, who can interpret it, and whether the user can refuse and exit.

This is an engineering precaution against possible algorithmic bureaucracy: an invisible and unaccountable profile must not become the authority deciding whether a user's communication, position, and collaboration are allowed to function.

Why The Device Must Be Usable On Its Own

This is a direct product decision. Trail Mate does not reject phones or desktop tools, but it does not want to outsource basic input, viewing, configuration, and state confirmation to them.

The reason is not ideological. It is operational. In real outdoor conditions, every extra dependency weakens the whole chain. If a device becomes hard to use without a phone, its value in disconnected conditions drops immediately.

That is why the project favors:

• keyboard-capable handhelds
• devices that can actually display a useful map
• targets that can complete basic input and configuration locally

Why Support Meshtastic, MeshCore, and Reticulum/LXMF Paths At The Same Time

The project is meeting real ecosystems rather than an empty greenfield market. Some users already use Meshtastic. Some prefer MeshCore. Some want a genuine Reticulum/LXMF path, or a real RNode modem route for an external host.

But the decision is not “more protocols is always better”. The actual judgment is:

• use a common adapter boundary to receive several real protocol ecosystems
• support device-side LXMF while distinguishing the separate bridge role of RNode Bridge
• still keep runtime single-protocol rather than trying to make protocol magic happen automatically

The value here is stable entry into several real ecosystems, not protocol spectacle.

Why Keep A Single-Protocol Runtime

Automatic protocol detection and mixed operation sound convenient, but in practice they make the system harder to reason about, harder to debug, and more likely to behave unpredictably in edge conditions.

Trail Mate therefore chooses:

• configuration decides the active protocol
• startup instantiates the corresponding adapter
• raw packets go directly to that active adapter

This gives up some apparent cleverness in exchange for clearer boundaries and lower maintenance cost.

Why Maps Are Offline-First

Because the project’s main scenario is precisely where public connectivity is weak or absent. A map system that depends on online fetches would lose much of its value inside Trail Mate.

Making maps offline-first also means the project has to take resource preparation seriously. Directory structure, export workflow, desktop tooling, and display boundaries all matter. That is why maps need a substantial wiki section rather than a single screenshot in the README.

Why Maps Stay North-Up And Use Directory Tiles

These two choices may look like implementation details, but they are design judgments.

North-up reduces both cognitive load and rendering complexity, and it gives multiple users a shared reference frame that is easier to discuss in the field.

Directory tiles instead of mbtiles make device-side reading simpler, keep resource boundaries explicit, and make it easier for the desktop tool to export to SD in a format the device can validate directly.

This design is not chasing the most modern map experience. It is chasing the most dependable map experience for the current hardware and scenario.

Why Team Has Its Own Extension Layer

Team is not solving the same problem as ordinary protocol chat. The project’s current view of Team includes questions such as:

• how a field unit forms
• how members share position and assembly points
• how team state remains visible over time
• how some actions can be conveyed without free-form text
• how the lifecycle can be reviewed later

Those needs are beyond ordinary message delivery. That is why the project is willing to define its own Team ports, management semantics, and encryption model.

Why Team Formation Uses ESP-NOW And Runtime Uses LoRa

Because those two phases have different needs.

• formation emphasizes nearby, secure, and fast TeamKey exchange
• runtime emphasizes long-range, low-power, and sustained coordination

Treating them as two different problems is more realistic than trying to force one mechanism to do both equally well.

Why Not Every Feature Is Exposed On Every Device

In a multi-hardware project, the hard part is not “can this compile”. It is “does this feature make sense on this hardware”. Trail Mate deliberately accepts different capability boundaries on different targets.

For example:

• GAT562 explicitly removes Team, HostLink, SD, and CJK
• T-Watch S3 is not currently the main GPS and SD route
• large-screen IDF targets do not yet have the same maturity as the main PlatformIO handhelds

The underlying decision is simple: feature trimming is a product boundary, not always a temporary deficiency.

Why Keep HostLink And A Desktop Companion

Because small embedded screens are not the right place for every preparation and troubleshooting job. Offline map preparation, raw frame inspection, event export, and multi-node situational viewing are all more practical on a desktop.

Keeping HostLink and Trail Mate Center does not demote the handheld into an accessory. It splits the system into a field terminal and a desktop workbench that complement each other.

Why Logging And Troubleshooting Are Treated As First-Class Capabilities

Trail Mate operates in weak-network, weak-power, limited-input, multi-hardware conditions. Without strong debugging paths, it would quickly become a black box that only the original author can maintain.

That is why serial logs, debug environments, HostLink, raw-frame inspection, and the wiki troubleshooting pages are part of the product, not documentation leftovers.

Why The MCU Feature Set Is Frozen

The product already has a complete capability loop. Adding major domains would dilute anonymity, decentralization, offline use, and TAK while consuming finite MCU memory, storage, power, and radio budgets.

Continued work is therefore limited to defects, reliability, security, interoperability correctness, resource efficiency, hardware adaptation, tools, tests, and documentation. Protocol adapters carry existing identity and position semantics; they may not redefine discovery, position authorization, or what remains available offline.

What The Project Is Explicitly Not Trying To Be

To prevent boundary drift, some non-goals are worth stating plainly:

• it does not copy the mobile Internet, app store, or broadband public-social features of cellular smartphones
• it does not add new major MCU feature domains
• it does not let position transmission drift away from anonymous authorization and Team/TAK awareness
• it is not trying to auto-mix multiple protocols inside one runtime
• it is not trying to force identical feature sets onto every board
• it does not treat every code path in the repository as a stable public promise
• it does not prioritize adding features that do not clearly help offline field coordination

These are permanent constraints after feature freeze, not temporarily deferred work. They let maintainers distinguish product improvement from requests that would turn Trail Mate into another product.