From 4bdebd3d40145bca23bdcb58d4676ceaea7b1595 Mon Sep 17 00:00:00 2001
From: hitchhooker <tommi@niemi.lol>
Date: Sun, 12 Jan 2025 11:50:52 +0700
Subject: [PATCH] add entry about redis structure

---
 src/SUMMARY.md |  1 +
 src/redis.md   | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+)
 create mode 100644 src/redis.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index 858928d..729f550 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -3,6 +3,7 @@
 - [Intro](./intro.md)
 - [Bridge](./bridge.md)
 - [Backend](./backend.md)
+  - [Redis](./redis.md)
 - [Frontend](./frontend.md)
 - [Setup testnet](./testnet.md)
 - [Proxy setup](./proxy_setup.md)
diff --git a/src/redis.md b/src/redis.md
new file mode 100644
index 0000000..fd429ba
--- /dev/null
+++ b/src/redis.md
@@ -0,0 +1,95 @@
+# Redis
+
+We use Redis as a cache to maintain application statelessness in our Kubernetes
+setup. This allows us to scale horizontally while keeping track of ongoing
+verification challenges. If Redis data is lost, users simply need to restart
+their verification challenges.
+
+## Architecture Overview
+
+The application uses Redis to temporarily store verification states and
+challenge tokens. This eliminates the need for local state management in
+application instances, making them stateless and easily scalable.
+
+## Data Structure
+
+We use hash maps (HSET/HGETALL) with composite keys to store verification states
+and challenge data.
+
+### Key Structure
+
+- Main verification state: `{network}:{account_address}`
+- Media-specific state: `{network}:{account_address}:{media_type}`
+
+### Main Verification State
+
+```redis
+HGETALL "polkadot:5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
+```
+
+Fields:
+- `status`: Overall verification status (Done/Pending)
+- `created_at`: Timestamp when verification process started
+- `updated_at`: Timestamp of last status change
+- `media_types`: Comma-separated list of media accounts being verified
+
+Example:
+```redis
+{
+    "status": "Pending",
+    "created_at": "2024-01-11T22:25:36",
+    "updated_at": "2024-01-11T22:26:36",
+    "media_types": "discord,twitter,matrix"
+}
+```
+
+### Media-Specific State
+
+```redis
+HGETALL "polkadot:5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY:discord"
+```
+
+Fields:
+- `name`: Username on the platform
+- `status`: Verification status for this specific media
+- `token`: Verification token
+
+Example:
+```redis
+{
+    "name": "patchwinner",
+    "status": "Pending",
+    "token": "Q8KGYC7P"
+}
+```
+
+## Examples
+
+### Storing New Verification State
+
+```python
+# Create main verification state
+redis_client.hmset(f"{network}:{address}", {
+    "status": "Pending",
+    "created_at": datetime.utcnow().isoformat(),
+    "updated_at": datetime.utcnow().isoformat(),
+    "media_types": ",".join(media_types)
+})
+
+# Create media-specific state
+redis_client.hmset(f"{network}:{address}:discord", {
+    "name": username,
+    "status": "Pending",
+    "token": generate_token()
+})
+```
+
+### Retrieving Verification State
+
+```python
+# Get main verification state
+state = redis_client.hgetall(f"{network}:{address}")
+
+# Get media-specific state
+discord_state = redis_client.hgetall(f"{network}:{address}:discord")
+```