10. Codebase Overview

Codebase Overview

Language: English. Chinese version: 10. Codebase Overview (中文)

Trail Mate is no longer a repository with only a few .ino files and some UI pages. It now spans device firmware, protocol interoperability, offline maps, Team, HostLink, multi-hardware adaptation, and shared UI logic. Because of that, the repository structure is part of the system design rather than just an organizational convenience.

The goal of this page is not to walk through every file. It is to answer a more practical question: if you need to find a certain kind of logic, where should you look first.

How To Read The Top Level

The most important top-level directories in the current repository are:

apps/
boards/
docs/
modules/
platform/
tools/
variants/
src/

apps/

This directory holds application shells and entry points. Current subdirectories include:

esp_pio/
esp_idf/
gat562_mesh_evb_pro/
linux_sim/
linux_rpi/
linux_unoq/

The most useful ones to understand first are:

• apps/esp_pio/: the Arduino and PlatformIO mainline shell
• apps/esp_idf/: the shared ESP-IDF shell root
• apps/gat562_mesh_evb_pro/: the independent nRF52 monochrome target shell

If you want to know where the program starts, when board initialization happens, or where AppContext is assembled, this is the first place to look.

boards/

This directory is where board truth and board runtime live, not just a list of configuration names. Current board directories include:

gat562_mesh_evb_pro/
tab5/
tdeck/
tdeck_pro/
tlora_pager/
twatchs3/
t_display_p4/

If you need:

• pin-level facts
• board initialization sequence
• GPS, LoRa, SD, or input-device bring-up
• an explanation of why one board behaves differently from another

start here before guessing from the shared UI or protocol layers.

modules/

This is the main home of shared logic. Current module families include:

core_chat/
core_gps/
core_hostlink/
core_sys/
core_team/
ui_mono_128x64/
ui_shared/

A useful shorthand is:

• core_chat/: chat, contacts, shared protocol logic, node identity, and related flows
• core_gps/: GPS configuration, filters, status, and movement strategy
• core_hostlink/: HostLink protocol logic and shared models
• core_sys/: application configuration and system-level shared structures
• core_team/: Team domain model, protocol, and use cases
• ui_shared/: most shared pages and shared menu logic
• ui_mono_128x64/: runtime for the monochrome small-screen UI

If you are changing project-wide behavior, this directory is often more relevant than boards/.

platform/

This is the platform adaptation layer. Current branches include:

esp/
linux/
nrf52/
shared/

Its responsibility is not to define product behavior, but to connect shared logic to platform capabilities such as:

• BLE
• LoRa transport
• GPS hardware
• file systems
• clocks and timers
• display and input adaptation

When shared business logic starts depending directly on Arduino, ESP-IDF, or board-specific headers, the project boundary is usually being weakened.

variants/

This directory mainly serves the PlatformIO route. Many differences in build environments, screen size, radio variants, and debug macros are defined here rather than in the root platformio.ini.

If you need to find:

• SCREEN_WIDTH or SCREEN_HEIGHT
• which debug macros are enabled on a target
• whether a radio variant has a dedicated environment

this is often the right entry point.

docs/

This is not just a place for loose notes. It holds many of the project’s actual boundary facts and design intentions. Especially useful documents include:

• ARCHITECTURE.md
• MULTI_PROTOCOL_SUPPORT.md
• TEAM.md
• map/SD_CARD_MAP_STRUCTURE_CN.md
• devices/*

If you only read code and skip these documents, it is easy to mistake current implementation details for the intended long-term boundary.

src/

This directory still exists, but the architecture notes make it clear that the project is continuing to move reusable logic toward modules/ and cleaner platform boundaries. So src/ should not automatically be treated as the repository’s only main battlefield.

Rough Flow From Startup To Main Menu

Using the current PlatformIO path as an example, startup roughly looks like this:

1. apps/esp_pio/startup_runtime.cpp brings up serial and basic clock providers
2. board initialization enters a concrete board runtime through platform startup support
3. display and LVGL initialization happens
4. AppContext binds board, protocol, GPS, Team, background tasks, and related runtime pieces
5. ui::startup_shell and app_catalog_builder assemble the visible menu structure for the current device

This is important because it shows that the main menu is not a fixed hard-coded page list. It is assembled according to hardware capability, shell path, and runtime state.

Where To Look For Specific Problems

Protocol interoperability or messaging

Start with:

• modules/core_chat/
• platform/esp/.../chat/infra/
• platform/nrf52/.../chat/infra/
• docs/MULTI_PROTOCOL_SUPPORT.md

Maps, tracks, and GPS

Start with:

• modules/core_gps/
• platform/esp/.../gps/
• map-related UI under the platform and shared UI paths
• docs/map/SD_CARD_MAP_STRUCTURE_CN.md

Team

Start with:

• modules/core_team/
• platform/esp/.../team/
• docs/TEAM.md

Board adaptation

Start with:

• boards/<target>/
• variants/<target>/
• the device-specific documentation

Menus and pages

Start with:

• modules/ui_shared/
• modules/ui_mono_128x64/
• modules/ui_shared/src/ui/app_catalog_builder.cpp

The Most Important Point For Maintainers

The repository is not yet a finished post-refactor end state. docs/ARCHITECTURE.md already makes clear that the project is converging toward one shared core with multiple platform shells, while trying to avoid cloning full source trees again.

Because of that, the biggest maintenance risks are:

• putting shared business logic back into a board-specific shell
• letting platform details leak into shared modules
• cloning near-duplicate parallel implementations just to get one board working quickly

Those three mistakes matter more to the project’s future than the naming of any one function.