From 1f1fa64f052ac36169c155ddc886d67aa2a9b195 Mon Sep 17 00:00:00 2001
From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
Date: Thu, 7 Nov 2024 10:12:41 -0500
Subject: [PATCH] wip - maintenance mode doc

---
 docs/maintenance-mode.mdx | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
 create mode 100644 docs/maintenance-mode.mdx

diff --git a/docs/maintenance-mode.mdx b/docs/maintenance-mode.mdx
new file mode 100644
index 0000000000..b54a56a799
--- /dev/null
+++ b/docs/maintenance-mode.mdx
@@ -0,0 +1,14 @@
+---
+title: Maintenance Mode
+description: Learn about Clerk's Maintenance Mode.
+---
+
+Maintenance Mode is a special operational state designed to ensure minimal disruption to signed in users during critical database upgrades or outages.
+
+{/* TODO: the following sentence might not be worth mentioning: */}
+
+When enabled, the system becomes aware that the primary database might be unavailable, but it can still operate using the read replica and Redis to process read requests and maintain session-related functionalities.
+
+Since the majority of requests in production environments are either GET requests or session refresh requests, maintenance mode allows us to serve most users with minimal interruption.
+
+Mutation methods (POST, PATCH, PUT, DELETE) will be rejected with a `503 Service Unavailable` status and an error message informing users that the system is temporarily unavailable.