diff --git a/backend/services/matching_service/README.md b/backend/services/matching_service/README.md
index 1f629bc0..f9aeba81 100644
--- a/backend/services/matching_service/README.md
+++ b/backend/services/matching_service/README.md
@@ -1 +1,50 @@
-### README for matching service
\ No newline at end of file
+## Matchmaking Flow
+
+The following sequence diagram shows the sequence for the endpoints for the Matching Service:
+
+```mermaid
+sequenceDiagram
+    participant Frontend
+    participant MS as Matching Service
+    participant Redis
+
+    Frontend->>MS: POST /match/request
+    MS->>Redis: equeue user + TTL
+    Redis-->>MS: OK
+    MS-->>Frontend: 200 OK
+
+    loop Every 1-3 seconds
+        Frontend->>MS: GET /match/status/{userId}
+        MS->>Redis: QUERY userId pool
+        Redis-->>MS: waiting / matched / timeout
+
+        alt User in waiting pool
+            MS-->>Frontend: 200, waiting + timeRemaining
+
+        else User in matched pool
+            MS-->>Frontend: 200, matched + sessionId
+
+        else User in timeout pool
+            MS-->>Frontend: 200, timeout
+        end
+    end
+```
+
+The following component diagram shows the Redis structures used by the Matching Service:
+
+```mermaid
+graph TD
+    MS(Matching Service) --> Redis
+
+    subgraph RedisPools["Redis Structures"]
+        EQ("Entry Queue (List)")
+        WPool("Waiting Pool (Hash)")
+        MPool("Matched Pool (Set)")
+        TPool("Timeout Pool (Set)")
+    end
+
+    Redis --> EQ
+    Redis --> WPool
+    Redis --> MPool
+    Redis --> TPool
+```
\ No newline at end of file
diff --git a/backend/services/matching_service/docs/api/OPENAPI_EG_DOCS.yaml b/backend/services/matching_service/docs/api/OPENAPI_EG_DOCS.yaml
index ac00a349..33852db6 100644
--- a/backend/services/matching_service/docs/api/OPENAPI_EG_DOCS.yaml
+++ b/backend/services/matching_service/docs/api/OPENAPI_EG_DOCS.yaml
@@ -1,7 +1,7 @@
 openapi: 3.0.4
 info:
-  title: Sample API
-  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
+  title: Matching Service API
+  description: The matching service is responsible for matching users based on some reasonable criteria (e.g., topics and difficulty level of questions, proficiency level of the users, etc.)
   version: 0.1.9
 
 servers:
@@ -11,16 +11,83 @@ servers:
     description: Optional server description, e.g. Internal staging server for testing
 
 paths:
-  /users:
+  /match/request:
+    post:
+      summary: Request to be matched.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - userId
+                - criteria
+              properties:
+                userId:
+                  type: string
+                criteria:
+                  type: object
+                  required:
+                   - difficulty
+                   - topics
+                  properties:
+                    difficulty:
+                      type: string
+                      enum: [easy, medium, hard]
+                    topics:
+                      type: array
+                      items:
+                        type: string
+                    # proficiency:
+                    #   type: string
+                    #   enum: [beginner, intermediate, advance]
+      responses:
+        '200':
+          description: Request accepted; user queued
+        '400':
+          description: Request rejected; user not queued due to invalid request (e.g. missing userId, criteria, or duplicate request)
+
+  /match/status/{userId}:
     get:
-      summary: Returns a list of users.
-      description: Optional extended description in CommonMark or HTML.
+      summary: Get matching status for a user
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: string
       responses:
-        "200": # status code
-          description: A JSON array of user names
+        '200':
+          description: Current matching status
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  type: string
\ No newline at end of file
+                type: object
+                properties:
+                  status:
+                    type: string
+                    enum: [waiting, matched, timeout]
+                  remainingTime:
+                    type: integer
+                    description: Remaining seconds until timeout (only if waiting)
+                  sessionId:
+                    type: string
+                    description: Session ID for collaboration service (only if matched)
+        '404':
+          description: User not found in the queue
+
+  /match/cancel/{userId}:
+    delete:
+      summary: Cancel matching request for a user.
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Matchmaking cancelled successfully
+        '404':
+          description: User not found in queue
diff --git a/backend/services/matching_service/docs/diagrams/to_del.png b/backend/services/matching_service/docs/diagrams/to_del.png
deleted file mode 100644
index 96806f86..00000000
Binary files a/backend/services/matching_service/docs/diagrams/to_del.png and /dev/null differ