Implement comments and rephrase where necessary

edge_manager/edge_mgmt_arch.adoc

@@ -1,26 +1,28 @@
 [#edge-mgmt-arch]
-= Understanding the {rhem} architecture
+= {rhem} architecture
 
 You can manage individual devices or an entire fleet 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 even under limited network conditions.
+The {rhem} uses an agent-based architecture that allows for a scalable and robust device management, even with limited network conditions.
+By deploying a {rhem} agent to a device, the agent autonomously manages and monitors the device while periodically communicating with the {rhem} service to check for new configurations and to report device status.
 
-The image-based OS that is distributed to the devices includes a {rhem} agent and its configuration.
-This means that the {rhem} agent autonomously manages and monitors each device while periodically communicating with the {rhem} service to check for new configurations and to report device status.
+The {rhem} also utilizes image-based operating systems.
+You can include the {rhem} agent and the agent configuration in the image that is distributed to the devices.
+Image-based operating systems allow the agent to initiate a transactional update of the image and to roll back to the previous version in case of an update error.
 
-The {rhem} architecture has the following main concepts:
+The {rhem} architecture has the following main features:
 
 * Agent
 * Service
-* Image-based OS
+* Image-based operating system
 * API server 
 * Database
 * Device
 * Device fleet
 
-For more information, see the following documentation:
+Learn more from the following sections:
 
-* <<agent-service,Understanding the {rhem} agent and service>>
-* <<api-server,Understanding the {rhem} API server>>
+* <<agent-service,{rhem} agent and service>>
+* <<api-server,{rhem} API server>>
 ////
 TODO include links when docs are ready
 - Build images
@@ -30,38 +32,51 @@ TODO include links when docs are ready
 ////
 
 [#agent-service]
-== Understanding the {rhem} agent and service
+== {rhem} agent and service
 
-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 periodic communication, the agent enrolls the devices into the service, checks for changes, and reports device status.
-When the agent is not actively connected to the service, the agent can apply configuration updates independently from the service.
+The {rhem} agent is a process running on each managed device that periodically communicates the {rhem} service on the {acm-short} hub cluster.
+The agent is responsible for the following tasks:
 
-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 an SQL database that stores the inventory and runtime information, such as the current target configuration and the reported actual configuration.
+* enroll devices into the service for the first time
+* periodically check with the service for changes in the device specification, such as changes to the operating system, configuration, and applications
+* if the agent detects changes in the device specification, apply the updates independently from the service
 
-*Note:* You can maintain fleet definitions in Git that the {rhem} periodically syncs with the fleet definitions in the SQL database.
+The {rhem} service is responsible for the following tasks:
 
-When the agent receives a new target configuration from the service, the agent does the following:
+* authenticate and authorize users and agents
+* enroll devices
+* manage device inventory
+* report status from individual devices or fleets
 
-. To avoid depending on network connectivity during the update, the agent downloads all required resources, such as the OS image and application container images, over the network to disk.
-. The agent updates the OS image by delegating to `bootc` or `rpm-ostree`.
-. 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 applications to reload the updated configuration.
+The service also communicates with a database that stores the device inventory and the target device configuration.
+When communicating with the service, the agent polls the service for changes in the configuration.
+If the the agent detects that the current configuration deviates from the target configuration, the agent attempts to apply the changes to the device.
+
+When the agent receives a new target configuration from the service, the agent does the following tasks:
+
+. To avoid depending on network connectivity during the update, the agent downloads all required resources, such as the operating system image and application container images, over the network to disk.
+. The agent updates the operating system image by delegating to `bootc`.
+. The agent updates configuration files on the file system of the device by overlaying a set of files that the service sends to the device.
+. If necessary, the agent reboots into the new operating system.
+Otherwise, the agent signals system services and applications to reload the updated configuration.
 . 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.
+If the update fails or the system does not return online after rebooting, the agent rolls back to the previous operating system image and configuration.
+
+*Note:* You can maintain fleet definitions in Git.
+The {rhem} periodically syncs with the fleet definitions in the database.
 
 [#api-server]
-== Understanding the {rhem} API server
+== {rhem} API server
 
-The API server is a core component 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.
+The API server is a core component of the {rhem} service that allows users and agents to communicate with the service.
 
-For the external communication, the {rhem} service's API server exposes two endpoints:
+The API server exposes the following endpoints:
 
-User-facing API endpoint:: Users can connect to the user-facing API endpoint from the CLI or the web UI.
+User-facing API endpoint:: Users can connect to the user-facing API endpoint from the CLI or the web console.
 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, which is mTLS-protected.
-The service authenticates the device based on its X.509 client certificates. 
+The service authenticates the device based on the X.509 client certificates.
+
+The {rhem} service also communicates with various external systems to authenticate and authorize users, get mTLS certificates signed, or query configuration for managed devices.

modules/common-attributes.adoc

@@ -28,3 +28,4 @@
 :gitops-short: OpenShift GitOps
 :cim: central infrastructure management
 :infra: infrastructure operator for Red Hat OpenShift
+:rhem: Red Hat Edge Manager