README Formatting improvements and added key concepts #285

Author: TheNinth7

source/README.md

@@ -28,7 +28,7 @@ All `.mc` files include inline comments and documentation describing the purpose
 
 ---
 
-## Subfolders
+## Folder Structure
 
 ### Subfolder `config/`
 

source/config/README.md

@@ -14,7 +14,7 @@ The Garmin SDK’s _Properties_ are stored externally from the app and persist a
 
 ---
 
-## Structure and Usage
+## Key Concepts
 
 All devices inherit default values from `BaseConfig` and `GlanceBaseConfig`, which define all configuration values used in the _Widget_ and _Glance_, respectively.
 
@@ -24,7 +24,7 @@ Additional base classes can be introduced for specific device families. For exam
 
 ---
 
-## Key Files and Directories
+## Folder Structure
 
 - `base/`:
   Contains `BaseConfig` and `GlanceBaseConfig`, which define the baseline values for all devices.

source/main/README.md

@@ -7,7 +7,7 @@ While most code in this directory is shared, certain parts are conditionally inc
 
 ---
 
-## Subfolder Structure
+## Folder Structure
 
 ### Subfolder `data/`
 
@@ -22,8 +22,6 @@ This includes:
 
 For more details, see the folder’s [README](data/README.md).
 
----
-
 ### Subfolder `infrastructure/`
 
 Provides the technical foundation of the application.
@@ -32,8 +30,6 @@ It contains the main `OHApp` class responsible for managing the application life
 
 For more details, see the folder’s [README](infrastructure/README.md).
 
----
-
 ### Subfolder `user-interface/`
 
 Contains all presentation-layer code.

source/main/data/README.md

@@ -4,24 +4,20 @@ Implements the data layer of the application.
 
 ---
 
-## Subfolder Structure
+## Folder Structure
 
 ### Subfolder `communications/`
 
 Responsibel for keeping the data layer in sync with the openHAB server.
 
 For more details, see the folder’s [README](communications/README.md).
 
----
-
 ### Subfolder `sitemap/`
 
 This folder defines the data model for parsing and representing sitemap content from openHAB. The classes defined in sitemap feed the data to be displayed to the user interface.
 
 For more details, see the folder’s [README](sitemap/README.md).
 
----
-
 ### Subfolder `storage/`
 
 Handles reading from and writing to persistent storage.

source/main/data/communications/README.md

@@ -6,16 +6,40 @@ This folder contains the connection management logic, HTTP request handling and
 
 ---
 
-## Subfolder Structure
+## Key Concepts
+
+### Connection Mode
+
+The app supports two connection modes: Bluetooth Low Energy (BLE) via the paired phone and direct Wi-Fi.
+
+The BLE connection is effectively always on and allows regular polling of the sitemap, including state updates. In contrast, using Wi-Fi requires entering a dedicated Garmin sync mode. During this process, native Garmin system views are shown to indicate sync progress and completion.
+
+Because of this limitation, no item states are displayed while operating in Wi-Fi mode. Commands can still be sent, but they are executed within the sync workflow. A manual sitemap refresh can also be triggered from the settings menu, though this updates only the sitemap structure and does not display live states.
+
+The decision not to display states in Wi-Fi mode is intentional. State accuracy is critical, and showing potentially outdated or inconsistent information would be misleading. In particular, after sending a command there is no reliable way to predict possible side effects on related items. For example, switching on a light could affect a nearby group item. Without real-time updates, the UI might display inconsistent states. In such cases, it is preferable to show no state at all rather than an incorrect one.
+
+See also the user manual’s [Network Access](https://next.openhab.org/docs/apps/garmin/#network-access) section for a user-facing explanation of this behavior.
+
+### Sitemap Updates
+
+Connect IQ does not support subscribing to sitemap updates from openHAB. Therefore, the app periodically polls the complete sitemap via a web request and rebuilds the menu structure based on the response.
+
+The polling interval can be configured by the user in the app settings.
+
+### Commands
+
+Commands are sent using a dedicated command web request. This request is triggered by the menu items representing the corresponding sitemap elements.
+
+---
+
+## Folder Structure
 
 ### Subfolder `connection/`
 
 Contains the `ConnectionManager`, which tracks the currently available connection type (BLE vs. Wi-Fi) and manages transitions between normal, degraded (Wi-Fi), and offline modes.
 
 For more details on connection behavior, see the [Network Access](https://next.openhab.org/docs/apps/garmin/#network-access) section of the user manual.
 
----
-
 ### Subfolder `sync-delegates/`
 
 Implements Wi-Fi-based synchronization used when no BLE connection is available.
@@ -35,7 +59,7 @@ Implements communication with the openHAB server using the Connect IQ SDK’s `T
 
 These requests are used for both BLE communication and Wi-Fi mode. In addition to sending and receiving data, this layer is responsible for processing server responses—for example, initializing a new sitemap and forwarding it to the user interface.
 
-#### Subfolders
+#### Folder Structure
 
 - **`web-requests/base/`**  
   Contains `BaseRequest`, the abstract base class for all HTTP requests.  

source/main/data/sitemap/README.md

@@ -8,25 +8,31 @@ See the user manual for details: [User Manual – Sitemap Setup](https://next.op
 
 ---
 
-## Subfolder Structure
+## Key Concepts
+
+The sitemap data structure represents a single sitemap response received from openHAB. It is therefore inherently transient and exists only until the next response is received from the server, at which point it is fully replaced.
+
+As a general rule, the sitemap data structure is not modified after it has been created. Instead, it reflects exactly the state provided by the server.
+
+There is one exception to this rule. When a command is sent successfully, the UI immediately reflects the expected new state without waiting for the next server response. This behavior is controlled by the corresponding menu items, which update the sitemap data structure locally to match the anticipated state. We refer to this as an internal update.
+
+---
+
+## Folder Structure
 
 ### Subfolder `base/`
 
 Contains `SitemapElement.mc`, the abstract base class for all sitemap elements.
 
 It defines shared properties and common parsing logic used by all concrete sitemap element types.
 
----
-
 ### Subfolder `json/`
 
 The Connect IQ API delivers JSON data as a dictionary.  
 `JsonObjectAdapter` provides type-safe accessors for retrieving objects, arrays, strings, numbers, and booleans from the JSON structure.
 
 This layer isolates JSON handling details from the higher-level sitemap model.
 
----
-
 ### Subfolder `pages/`
 
 Contains classes representing the **content** of container-type sitemap elements (e.g., frames or groups).
@@ -35,15 +41,13 @@ These classes model the internal structure and child elements of a container. Th
 
 To keep the UI responsive and avoid limitations such as the Watchdog timeout for long-running code and stack size restrictions caused by recursive processing, pages are processed asynchronously and non-recursively. The work is split into small tasks that are executed by the task queue implementation.
 
----
-
 ### Subfolder `widgets/`
 
 Contains `SitemapElement` subclasses representing concrete sitemap widgets, such as switches, sliders, text labels, and container elements.
 
 For container-type elements (e.g., frames or groups), the widget class describes the container itself and links to the corresponding implementation in `pages/` to represent its content.
 
-#### Subfolders
+#### Folder Structure
 
 - **`base/`**  
   Contains `SitemapWidget`, the base class for all widget-type elements.  

source/main/infrastructure/README.md

@@ -6,7 +6,7 @@ It contains the main `OHApp` class responsible for managing the application life
 
 ---
 
-## Subfolder Structure
+## Folder Structure
 
 ### Subfolder `appbase/`
 

source/main/user-interface/README.md

@@ -6,7 +6,9 @@ This directory defines how the app is rendered and how users interact with it. I
 
 ---
 
-## Subfolder `base/`
+## Folder Structure
+
+### Subfolder `base/`
 
 Provides abstract and shared base classes for menu implementations:
 
@@ -20,19 +22,15 @@ Provides abstract and shared base classes for menu implementations:
 Additional sitemap-specific styling logic is implemented in  
 `features/sitemap/menu-items/base/BaseSitemapMenuItem`.
 
----
-
-## Subfolder `fallbacks/`
+### Subfolder `fallbacks/`
 
 Contains components responsible for fallback behavior, such as error handling and the loading view.
 
 These classes are used when normal feature rendering cannot proceed (e.g., due to communication failures or missing data). They ensure that the application remains robust and provides meaningful feedback to the user.
 
 For more details, see the folder’s [README](fallbacks/README.md).
 
----
-
-## Subfolder `features/`
+### Subfolder `features/`
 
 Implements the main user-facing features of the application.
 
@@ -44,19 +42,15 @@ The current feature categories are:
 
 For more details, see the folder’s [README](features/README.md).
 
----
-
-## Subfolder `shared/`
+### Subfolder `shared/`
 
 Contains reusable UI components that are used across multiple features.
 
 These classes represent visible UI elements or composable building blocks that can be rendered in different contexts.
 
 For more details, see the folder’s [README](shared/README.md).
 
----
-
-## Subfolder `ui-infrastructure/`
+### Subfolder `ui-infrastructure/`
 
 Contains central, stateful runtime facilities that support the user interface.
 

source/main/user-interface/fallbacks/README.md

@@ -4,7 +4,9 @@ Contains components responsible for fallback behavior, including error handling
 
 ---
 
-## Subfolder `error-handling/`
+## Folder Structure
+
+### Subfolder `error-handling/`
 
 Manages the detection, handling, and presentation of exceptions within the app.
 
@@ -17,9 +19,7 @@ Manages the detection, handling, and presentation of exceptions within the app.
 - `WarningToastHandler`  
   Determines whether a non-fatal error should be displayed as a toast notification and provides the functionality to show these notifications.
 
----
-
-## Subfolder `loading-view/`
+### Subfolder `loading-view/`
 
 Implements a full-screen loading indicator that signals data is being retrieved.
 

source/main/user-interface/features/README.md

@@ -30,64 +30,21 @@ The _Settings_ menu is also implemented using `CustomMenu`.
 
 ---
 
-## Subfolder `glance/`
+## Folder Structure
 
-Implements the Glance feature.
-
-`GlanceSitemapView` provides a compact view that reads the sitemap label from persistent storage and displays it in the glance carousel.
-
-When the app is launched in glance mode, `OHApp.getGlanceView()` acts as the entry point and prepares the corresponding view.
+### Subfolder `glance/`
 
-### Memory Constraints
-
-When running as a glance, available memory is very limited. Connect IQ supports scoped classes and resources for this purpose. Classes required in glance mode must be annotated with `(:glance)`, and only the strictly necessary classes should be included in this scope.
+Implements the Glance feature.
 
----
+For detailed information, see the folder’s [README](glance/README.md).
 
-## Subfolder `settings-menu/`
+### Subfolder `settings/`
 
 Implements the _Settings_ feature.
 
-Currently provides the following information and actions:
-
-- App version  
-- openHAB server URL  
-- Current connection mode (Phone/BLE, Wi-Fi, Offline)  
-- Timestamp of the last sitemap update  
-- Manual sitemap update over Wi-Fi  
-
-Because Wi-Fi mode does not automatically poll for structural sitemap changes, updates must be triggered manually when operating without a BLE connection.  
-See [No Polling of Sitemap Changes and States](https://next.openhab.org/docs/apps/garmin/#no-polling-of-sitemap-changes-and-states) in the user manual for details and screenshots.
-
-### Platform-Specific Behavior
-
-- **Button-based devices**  
-  The _Settings_ menu appears as a parallel menu to the homepage. It is accessed by scrolling beyond the title or footer of the _Homepage_ menu, mimicking the system settings access pattern on devices such as the Fenix 7 Pro or Epix 2 Pro.
-
-- **Touch-based devices**  
-  Due to more limited gesture support, the _Settings_ menu is implemented as a regular menu item within the _Homepage_.
-
-Device-specific behavior is defined in the `monkey.jungle` build file. Exclusion annotations (also used in input delegates) ensure that the correct implementation is compiled per device.
-
-### Subfolders
-
-#### Subfolder `manager/`
-
-Contains `SettingsMenuManager`, which controls the lifecycle and presentation of the settings menu.
-
-It maintains singleton instances of the menu and its input delegate, tracks whether the menu is currently visible, and coordinates transitions between the homepage and the settings view. It also determines focus behavior based on slide direction and input type, and manages pushing and popping the view on the `ViewStack`.
-
-#### Subfolder `menu/`
-
-Contains the `SettingsMenu` implementation based on `BaseMenu`, along with the corresponding input delegates for handling user interaction.
-
-#### Subfolder `menu-items/`
-
-Contains the individual menu items displayed within the _Settings_ menu.
-
----
+For detailed information, see the folder’s [README](settings/README.md).
 
-## Subfolder `sitemap/`
+### Subfolder `sitemap/`
 
 Implements the core UI for displaying and interacting with openHAB sitemap content.