From 7c597bfaa91092fa5050f0ad167b26de9371896e Mon Sep 17 00:00:00 2001
From: Stefan Strigler <stefan.strigler@emqx.io>
Date: Thu, 30 Mar 2023 16:05:32 +0200
Subject: [PATCH] docs: give a better idea of what this application is supposed
 to do

---
 apps/emqx_management/README.md | 46 ++++++++++++++++++++++++++++------
 1 file changed, 39 insertions(+), 7 deletions(-)

diff --git a/apps/emqx_management/README.md b/apps/emqx_management/README.md
index fa37d0f0f..2edeae91a 100644
--- a/apps/emqx_management/README.md
+++ b/apps/emqx_management/README.md
@@ -1,12 +1,44 @@
 
-# emqx-management
+# EMQX Management
 
-EMQX Management API
+EMQX Management offers various interfaces for administrators to interact with
+the system, either by a remote console attached to a running node, a CLI (i.e.
+`./emqx ctl`), or through its rich CRUD-style REST API (mostly used by EMQX'
+dashboard). The system enables administrators to modify both cluster and
+individual node configurations, and provides the ability to view and reset
+different statistics and metrics.
 
-## How to Design RESTful API?
+## Functionality
 
-http://restful-api-design.readthedocs.io/en/latest/scope.html
+Amongst others it allows to manage
 
-default application see:
-header:
-authorization: Basic YWRtaW46cHVibGlj
+* alarms,
+* API Keys,
+* banned clients, users or hosts,
+* connected clients including their topic subscriptions,
+* cluster configurations,
+* configuration of MQTT listeners,
+* node configuration,
+* custom plugins,
+* fixed subscriptions,
+* and topics.
+
+Moreover it lets you
+
+* modify hot and non-hot updatable configuration values,
+* publish messages, as well as bulk messages,
+* create trace files,
+* and last but not least monitor system status.
+
+## Implementation Notes
+
+API endpoints are implemented using the `minirest` framework in combination with
+`hoconsc` and `emqx_dashboard_swagger`.
+
+## TODO/FIXME
+
+At its current state there are some reverse dependencies from other applications
+that do calls directly into `emqx_mgmt`.
+
+Also, and somewhat related, its bpapi proto modules do calls directly into
+other applications.