Updated documentation with new features and directory structure #285

Author: TheNinth7

README.md

@@ -12,7 +12,7 @@ The user manual is available in the openHAB documentation at <https://next.openh
 
 ---
 
-# Table of Contents
+## Table of Contents
 
 This README covers the following topics:
 
@@ -34,7 +34,7 @@ This README covers the following topics:
 
 ---
 
-# Introduction
+## Introduction
 
 This app is built using the Garmin Connect IQ SDK and is based on [openHAB sitemaps](https://www.openhab.org/docs/ui/sitemaps.html).
 
@@ -43,7 +43,9 @@ It includes two application types:
 - _**Glance**_: A lightweight, quick-access entry point.
 - _**Widget**_: The main, full-screen interface for interacting with the sitemap.
 
-## _Widget_ Overview
+<br>
+
+### _Widget_ Overview
 
 The _Widget_:
 
@@ -55,7 +57,7 @@ The _Widget_:
 
 <br>
 
-## _Glance_ Overview
+### _Glance_ Overview
 
 The _Glance_:
 
@@ -70,11 +72,11 @@ The _Glance_:
 
 ---
 
-# Project Structure
+## Project Structure
 
 The project is organised into the following directories:
 
-## Root Folder `/`
+### Root Folder `/`
 
 The root directory contains essential project files.
 
@@ -91,19 +93,19 @@ The root directory contains essential project files.
 
 <br>
 
-## Folder `/.vscode`
+### Folder `/.vscode/`
 
 Contains VS Code customizations.
 
 <br>
 
-## Folder `/docs`
+### Folder `/docs/`
 
 Contains the user manual, published at <https://next.openhab.org/docs/apps/garmin/>.
 
 <br>
 
-## Folder `/resources`
+### Folder `/resources/`
 
 In the Connect IQ SDK, resources define:
 
@@ -129,20 +131,20 @@ In the Connect IQ SDK, resources define:
 
 <br>
 
-## Folder `/source`
+### Folder `/source/`
 
 The app is written in **Monkey C**, Garmin's programming language, using the Connect IQ SDK API for UI, settings, persistent storage, and HTTP requests to openHAB.
 
 For more details, continue reading the folder’s [README](source/README.md).
 
 <br>
 
-# Build Instructions
+## Build Instructions
 
 Follow the steps below to build, run, and test the app using the Connect IQ SDK and Garmin simulator.
 <br>
 
-## To Run the App in the Garmin Simulator
+### To Run the App in the Garmin Simulator
 
 1. Install:
    - Visual Studio Code
@@ -158,13 +160,13 @@ Follow the steps below to build, run, and test the app using the Connect IQ SDK
 
 <br>
 
-## To Compile for a Single Device
+### To Compile for a Single Device
 
 1. Press `CTRL+SHIFT+P` → `Monkey C: Build Current Project`
 
 <br>
 
-## Generating the `.iq` File for Garmin Connect IQ Store Upload
+### Generating the `.iq` File for Garmin Connect IQ Store Upload
 
 Follow these steps to prepare and export your app for upload to the Garmin Connect IQ Store:
 
@@ -194,7 +196,7 @@ Follow these steps to prepare and export your app for upload to the Garmin Conne
 
 <br>
 
-## To Add a New Device
+### To Add a New Device
 
 To support a new device:
 
@@ -211,11 +213,11 @@ To support a new device:
 
 <br>
 
-# Helpful Tips and Notes
+## Helpful Tips and Notes
 
 A collection of useful information for working on this project.
 
-## Removing Debug Statements
+### Removing Debug Statements
 
 While debug statements are only printed in debug builds, they still occupy code space in release builds. Therefore, when building a release, all debug statements should be commented out.
 
@@ -233,7 +235,7 @@ To deactivate the debug statements, replace them with:
 
 This will comment them out without affecting any lines that are already commented.
 
-# Copyright Notice
+## Copyright Notice
 
 ```text
 Copyright (c) 2025 Contributors to the openHAB project
@@ -245,6 +247,6 @@ http://www.eclipse.org/legal/epl-2.0
 SPDX-License-Identifier: EPL-2.0
 ```
 
-# Attributions
+## Attributions
 
 The [interface icons](resources/icons-interface), except for the openHAB logo, are licensed under CC BY 3.0 by [Adrien Coquet](https://adrien-coquet.com/) from [Noun Project](https://thenounproject.com/creator/coquet_adrien/).

source/README.md

@@ -36,15 +36,15 @@ All `.mc` files include inline comments and documentation describing the purpose
 
 # Folder Structure
 
-## Folder `config`
+## Subfolder `config`
 
 This folder defines device-specific configuration using code-based _Constants_, which replace Garmin SDK _Properties_ due to their limitations. Unlike _Properties_, _Constants_ are embedded in the code, update automatically with new app versions, and benefit from compiler validation.
 
 For more details, continue reading the folder’s [README](config/README.md).
 
 <br>
 
-## Folder `main`
+## Subfolder `main`
 
 Contains the core application source code that is shared across all target devices. This includes the data layer, infrastructure and service components, as well as the user interface logic and views.
 
@@ -54,7 +54,7 @@ For additional details, refer to the folder’s [README](main/README.md).
 
 <br>
 
-## Folder `themes`
+## Subfolder `themes`
 
 Themes define the color schemes used in the app and can change dynamically at runtime. This also includes icons whose colors must be adapted to the active theme. Themes are used to implement the light and dark mode on Edge devices.
 

source/config/README.md

@@ -2,6 +2,8 @@
 
 This folder defines device-specific configuration via code-based constants, replacing Garmin SDK _Properties_, which have significant limitations.
 
+---
+
 ## Why Constants?
 
 The Garmin SDK’s _Properties_ are stored externally from the app and persist across installations. This means that when a new version of the app is installed, any existing properties from the previous version remain, unless the user performs a full uninstall and reinstall. To avoid this issue and allow reliable updates, the app uses _Constants_ instead:
@@ -10,19 +12,23 @@ The Garmin SDK’s _Properties_ are stored externally from the app and persist a
 - The compiler validates constant usage, reducing runtime errors.
 - Constants can be cleanly overridden for specific devices.
 
-### Structure and Usage
+---
+
+## Structure and Usage
 
 All devices inherit default values from `BaseConfig` and `GlanceBaseConfig`, which define all configuration values used in the _Widget_ and _Glance_, respectively.
 
 In the source code, these are accessed via the `Config` and `GlanceConfig` classes. Each supported device may override the defaults by providing its own implementation of these classes.
 
 Additional base classes can be introduced for specific device families. For example, `EdgeBaseConfig` inherits from `BaseConfig` and overrides values that apply to all Edge devices. Concrete `Config` implementations for individual Edge models can then further override selected values defined in the Edge base configuration.
 
-### Key Files and Directories
+---
+
+## Key Files and Directories
 
-- `base`:
+- `base/`:
   Contains `BaseConfig` and `GlanceBaseConfig`, which define the baseline values for all devices.
-- `device-default`:
+- `device-default/`:
   Contains default `Config` and `GlanceConfig` implementations. These inherit all values from the base without overrides.
-- `device-<device-name>`:
+- `device-<device-name>/`:
   Contains device-specific implementations of `Config` and `GlanceConfig`, overriding select values to adapt the UI for the particular device.

source/main/README.md

@@ -1,119 +1,43 @@
 # Folder `main`
 
-This folder contains the source code of the app, written in **Monkey C**, Garmin’s programming language. It uses the Connect IQ SDK for user interface components, application settings, persistent storage, and HTTP communication with the openHAB server.
+Contains the primary application source code shared across all target devices.  
+This folder includes the core implementation of the app, covering the data layer, infrastructure services, and the user interface.
 
----
-
-## Key Concepts
-
-### **Annotations**
-
-- `(:glance)` marks code that must be included in the _Glance_ view.
-- Exclude annotations are used to tailor the code for each target device. See the [`monkey.jungle`](../README.md#root-folder-) file in the root directory for details.
-
-### **Inline Documentation**
-
-All `.mc` files include inline comments and documentation describing the purpose and internal workings of each class.
-
-### **Further Reading**
-
-- [Connect IQ Core Topics](https://developer.garmin.com/connect-iq/core-topics/)
-- [Connect IQ API Docs](https://developer.garmin.com/connect-iq/api-docs/)
-
----
-
-## Folder Structure
-
-### Root Folder `/`
-
-Contains the `OHApp` class, the main entry point for the app. It handles:
-
-- Initialization of the initial view in both _Glance_ and _Widget_ modes
-- Startup and shutdown logic
-- Reactions to app updates and settings changes
-
----
-
-### Folder `exceptions`
-
-Defines all custom exception types used by the app. All exception classes extend the base class `GeneralException`.
+While most code in this directory is shared, certain parts are conditionally included or excluded per device using build annotations. Device-specific [constants](../config/README.md) and [themes](../themes/README.md) are maintained separately.
 
 ---
 
-### Folder `logging`
+## Subfolder Structure
 
-Contains the `Logger` class, which provides utility methods to output debug statements and exceptions to the system log.
+### `data/`
 
----
-
-### Folder `settings`
+Implements the data layer of the application.
 
-Includes the `AppSettings` class, which reads, validates, and exposes application settings through static accessor methods.
+This includes:
 
-**Related Resources:**
+- The internal sitemap representation  
+- Synchronization with the server (receiving updates and sending commands)  
+- Communication handling  
+- Persistence of sitemap data in storage  
 
-- [Connect IQ SDK Core Topics – Resources](https://developer.garmin.com/connect-iq/core-topics/resources/)
-- [Connect IQ API Docs – `Toybox.Application.Properties`](https://developer.garmin.com/connect-iq/api-docs/Toybox/Application/Properties.html)
-- See also: [Folder `resources`](https://github.com/TheNinth7/ohg#folder-resources)
+For more details, see the folder’s [README](data/README.md).
 
 ---
 
-### Folder `sitemap`
-
-This folder defines the data model for parsing and representing sitemap content from openHAB. It forms the foundation for building the user interface menus. The following subdirectories and files are included:
-
-- `base/SitemapElement`: The abstract base class for all sitemap elements.
-- `factory/SitemapElementFactory`: Responsible for instantiating the appropriate `SitemapElement` subclass from a JSON representation of a sitemap element.
-- `item-descriptions`: Contains classes that model the state and command descriptions of openHAB items.
-- `sitemap-pages`: Contains `SitemapElement` subclasses that act as containers, grouping other sitemap elements (e.g., frames, groups).
-- `sitemap-primitives`: Contains `SitemapElement` subclasses representing basic UI components such as switches, sliders, and text labels.
-
----
-
-### Folder `storage`
-
-Handles reading from and writing to persistent storage. As of now, the following data is stored:
-
-- **JSON Dictionary**: Caches the latest sitemap data for use on app startup.
-- **Sitemap Label**: Stored for display by the _Glance_, in case the sitemap cannot be loaded due to memory constraints.
-- **Sitemap Error Count**: Tracks non-fatal communication errors across _Glance_ and _Widget_ modes. If errors persist, they are escalated to fatal errors. This count is preserved across sessions and shared between both app modes.
+### `infrastructure/`
 
-**Related Resources:**
+Provides the technical foundation of the application.
 
-- [Connect IQ Core Topics – Persisting Data](https://developer.garmin.com/connect-iq/core-topics/persisting-data/)
-- [Connect IQ API Docs – `Toybox.Application.Storage`](https://developer.garmin.com/connect-iq/api-docs/Toybox/Application/Storage.html)
+It contains the main `OHApp` class responsible for managing the application lifecycle, along with cross-cutting services such as logging, memory management, task coordination, and other shared technical utilities.
 
----
-
-### Folder `user-interface`
-
-Contains all user interface implementations. For detailed documentation, see the folder’s [README](https://github.com/TheNinth7/ohg/tree/main/source/user-interface#folder-user-interface).
+For more details, see the folder’s [README](infrastructure/README.md).
 
 ---
 
-### Folder `web-requests`
-
-Implements communication with the openHAB server using the Connect IQ SDK's `Communication` module.
-
-#### Subfolders:
-
-- **`base/`**
-  Contains `BaseRequest`, the base class for all HTTP requests. It includes shared logic such as applying basic authentication and checking HTTP response codes.
-
-- **`command/`**
-  Implements requests for sending commands to openHAB. Supports both:
-
-  - The JSON-based REST API (available in openHAB 5 and as a backport for openHAB 4.3.x)
-  - A custom webhook integration
-    _(See the user manual for configuration details.)_
-
-- **`sitemap/`**
-  Handles sitemap retrieval, polling, and processing logic:
+### `user-interface/`
 
-  - `SitemapRequest`: Periodically fetches sitemap data from openHAB and triggers its processing.
-  - `SitemapProcessor` and `SitemapProcessorTasks`: Process the retrieved sitemap data and act as the interface between `SitemapRequest` and the menu update logic in `/user-interface/sitemap-menu`.
+Contains all presentation-layer code.
 
-**Further reading:**
+This folder defines how the application is rendered and how users interact with it. It includes feature screens, reusable UI components, global fallback states (e.g., error and loading views), and UI-specific infrastructure such as view management and theming.
 
-- [Connect IQ Core Topics - JSON REST Requests](https://developer.garmin.com/connect-iq/core-topics/https/)  
-- [Connect IQ API Docs - `Toybox.Communications`](https://developer.garmin.com/connect-iq/api-docs/Toybox/Communications.html)
+For more details, see the folder’s [README](user-interface/README.md).

source/main/data/README.md

@@ -0,0 +1,29 @@
+# Folder `data`
+
+Implements the data layer of the application.
+
+---
+
+## Subfolder Structure
+
+### Folder `communications/`
+
+Responsibel for keeping the data layer in sync with the openHAB server.
+
+For more details, see the folder’s [README](communications/README.md).
+
+---
+
+### Folder `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).
+
+---
+
+### Folder `storage/`
+
+Handles reading from and writing to persistent storage. 
+
+For more details, see the folder’s [README](storage/README.md).