Rephrase

edge_management/edge_mgmt_arch.adoc

@@ -1,60 +1,45 @@
 [#edge-mgmt-arch]
 = Understanding the {rhem} architecture
 
-The {rhem} uses an agent-based architecture, which means that a {rhem} agent runs on each edge device.
-The devices periodically communicate with the {rhem} service through the agent.
-The agent autonomously handles device management and monitoring.
-This agent-based architecture allows for a scalable and robust device management under limited network conditions.
+You can manage individual or a fleet of devices by using the {rhem}.
+The {rhem} uses an agent-based architecture with image-based operating systems (OS), that allows for a scalable and robust device management under limited network conditions.
 
-The {rhem} architecture has the following main concepts:
-
-Agent:: The {rhem} agent runs on each device. The agent periodically connects to the {rhem} service for monitoring and updates.
-Service:: The {rhem} service handles user and agent authentication and authorization, device enrollment and inventory, rolling out updates to devices, and rolling up status from devices.
-API server:: A part of the {rhem} service that exposes both agent-facing and user-facing API endpoints.
-Device:: A combination of a real or virtual machine, an operating system, and application workloads that function together to serve a specific purpose.
-Device spec:: A specification of a state of the device that the user defines.
-Device status:: A record of the state that the device is reported to actually have.
-Device template:: A template for device specs that serves to control deviations between the configurations of devices.
-Fleet:: A group of devices governed by a common device template and common management policies.
-PostgreSQL database:: A database for storing inventory and runtime information, such as the current target configuration and the reported actual configuration.
-////
-Field Selector:: Filters and selectors for {rhem} objects based on the values of specific resource fields.
-Field selectors follow the same syntax, principles, and support the same operators as Kubernetes field and label selectors.
-Labels:: Organizers for devices and other resources.
-Label Selector:: Groups or filters for devices and other resources based on assigned labels.
-////
+The image-based OS that is distributed to the devices includes a {rhem} agent and its configuration.
+This means that a {rhem} agent autonomously handles the management and monitoring of each device while the agent periodically communicates with a {rhem} service to query for new configuration and to report device status.
 
-== Understanding the {rhem} API server
-
-The {rhem} service communicates with various external systems to authenticate and authorize users, get mTLS certificates signed, or query configuration for managed devices.
-
-For the external communication, the {rhem} service's API server exposes two endpoints:
+The {rhem} architecture has the following main concepts:
 
-User-facing API endpoint:: Users can connect to the user-facing API endpoint from the CLI or the web UI.
-Users must authenticate with the configured external authentication service to obtain a JSON Web Token (JWT) token with which they can make HTTPS requests.
+* Agent
+* Service
+* Image-based OS
+* API server 
+* Database
+* Device
+* Device fleet
 
-Agent-facing API endpoint:: Agents connect to the agent-facing endpoint.
-The endpoint is mTLS-protected which means that the service authenticates the device based on its X.509 client certificates. 
-During enrollment, the device's unique certificate is bootstrapped based on hardware root of trust.
-The private key is protected by the Trusted Platform Module (TPM), therefore the client certificate cannot be used by another entity.
-Certificates are automatically rotated before they expire.
+For more information, see the following documentation:
 
-[#edge-mgmt-agent]
-== Understanding the {rhem} agent
+* <<agent-service,Understanding the {rhem} agent and service>>
+* <<api-server,Understanding the {rhem} API server>>
+////
+TODO include links when docs are ready
+- Build images
+- Provisioning
+- Managing devices
+- Managing device fleets
+////
 
-The {rhem} agent is a process running on each managed device that periodically communicates with the service.
-The periodic reporting allows the device to be on a private network or to have a dynamic IP address.
+[#agent-service]
+== Understanding the {rhem} agent and service
 
-The agent is responsible for the following processes:
+The {rhem} agent is a process running on each managed device that periodically communicates with the {rhem} service that runs on the {acm-short} hub cluster.
+During the periodical communication, the agent enrolls the devices into the service, queries the service for changes, and reports the status of devices.
+When the agent is not actively connected to the service, the agent can apply configuration updates independently from the service.
 
-* securely enrolling devices with the specified target configuration
-* periodically monitoring for new configuration from the service
-* autonomously applying updates
-* periodically notifying the service if a configuration deviates from the target configuration
-* reporting status on the updates and the health of devices back to the service
+The {rhem} service handles user and agent authentication and authorization, device enrollment and inventory, rolling out updates to devices, and reporting status from individual devices or fleets.
+The service communicates with a database that stores the inventory and runtime information, such as the current target configuration and the reported actual configuration.
 
-Thanks to the declarative nature of the device configuration, you can store the target configuration in a Git repository.
-The {rhem} service can periodically poll the repository for updates or receive updates from a webhook.
+*Note:* You can store the inventory and runtime information in a PostgreQSL database or a Git repository.
 
 When the agent receives a new target configuration from the service, the agent does the following:
 
@@ -63,8 +48,20 @@ When the agent receives a new target configuration from the service, the agent d
 . The agent updates configuration files on the device's file system by overlaying a set of files that the service sends to the device.
 . If necessary, the agent reboots into the new OS.
 Otherwise, the agent signals services to reload the updated configuration.
-. Updates applications running on Podman or MicroShift.
+. The agent updates applications running on Podman or MicroShift.
 
 If applying any of these changes fails or the system does not return online after rebooting, the agent rolls back to the previous OS image and configuration.
 
-//For more information, see...
+[#api-server]
+== Understanding the {rhem} API server
+
+The API server is a part of the {rhem} service that exposes both agent-facing and user-facing API endpoints.
+The {rhem} service communicates with various external systems to authenticate and authorize users, get mTLS certificates signed, or query configuration for managed devices.
+
+For the external communication, the {rhem} service's API server exposes two endpoints:
+
+User-facing API endpoint:: Users can connect to the user-facing API endpoint from the CLI or the web UI.
+Users must authenticate with the configured external authentication service to obtain a JSON Web Token (JWT) token with which they can make HTTPS requests.
+
+Agent-facing API endpoint:: Agents connect to the agent-facing endpoint.
+The endpoint is mTLS-protected which means that the service authenticates the device based on its X.509 client certificates. 

edge_management/main.adoc

@@ -2,4 +2,5 @@ include::modules/common-attributes.adoc[]
 
 = Edge management
 
-include::edge_mgmt_intro.adoc[leveloffset=+1]
+include::edge_mgmt_intro.adoc[leveloffset=+1]
+include::edge_mgmt_arch.adoc[leveloffset=+2]