From 9de79d20431346c6447408a1760f6c6e0cfd766a Mon Sep 17 00:00:00 2001
From: Golden_Eagle07 <challamanideepreddy@gmail.com>
Date: Wed, 8 Jul 2026 16:51:22 +0530
Subject: [PATCH 1/3] updated docs

---
 README.md             |  21 --
 docs/API_CONTRACTS.md | 708 ++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 689 insertions(+), 40 deletions(-)

diff --git a/README.md b/README.md
index ea19717..c06ad3f 100644
--- a/README.md
+++ b/README.md
@@ -102,27 +102,6 @@ go run main.go
  
 Make sure PostgreSQL is running and reachable using the values in your `.env` file (`POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`).
  
-### Running database migrations
- 
-```bash
-cd server
-psql "postgres://$POSTGRES_USER:$POSTGRES_PASSWORD@$POSTGRES_HOST:$POSTGRES_PORT/$POSTGRES_DB" \
-for migration in /app/migrations/*_up.sql; do
-    filename=$(basename "$migration")
-    already_applied=$(psql "${DB_URL}" -tAc \
-        "SELECT COUNT(*) FROM schema_migrations WHERE filename = '${filename}'")
-    if [ "$already_applied" = "0" ]; then
-        echo "Applying ${filename}..."
-        psql "${DB_URL}" -f "$migration"
-        psql "${DB_URL}" -c \
-            "INSERT INTO schema_migrations (filename) VALUES ('${filename}')"
-        echo "${filename} applied."
-    else
-        echo "${filename} already applied, skipping."
-    fi
-done
-```
- 
 ### Running the mobile app
  
 ```bash
diff --git a/docs/API_CONTRACTS.md b/docs/API_CONTRACTS.md
index ddf2c08..3cfe8ab 100644
--- a/docs/API_CONTRACTS.md
+++ b/docs/API_CONTRACTS.md
@@ -19,11 +19,23 @@
 | GET | [/api/users/me](#1-user-me) | Get the authenticated user's profile |
 | GET | [/api/users/:id](#2-search-user-by-id) | Search users by username or display name |
 | GET | [/api/users/search?q=&page=&limit=](#3-search-user-by-username-and-display-name) | Get a public user profile |
-| GET | [/ws](#websocket-endpoints) | WebSocket upgrade endpoint (JWT required) |
+| GET | [/ws](#1-connect-to-websocket) | WebSocket upgrade endpoint (JWT required) |
+| WS | [Client to Server](#2-client-to-server-messages) | Client to Server Websocket |
+| WS | [Server to Client](#3-server-to-client-messages) | Server to Client Websocket |
 | POST | [/api/messages](#1-send-message) | Send a message (REST fallback) |
 | GET | [/api/messages?with=&before=&limit=](#2-message-history) | Paginated message history |
+| GET | [/api/messages/conversations](#3-conversations) | Get user conversatiosn |
+| POST | [/api/messages/read](#4-read) | Get read mark |
+| POST | [/api/groups/](#1-create-group) | Create Group |
+| GET | [/api/groups/](#2-get-groups) | Get all groups of user |
+| GET | [/api/group/{id}](#3-get-group-by-group-id) | Get group by group id |
+| GET | [/api/groups/{id}/messages](#4-get-messages-of-group) | Get message of a group |
+| GET | [/api/groups/{id}/members](#5-group-members) | Get group members |
+| POST | [/api/groups/{id}/leave](#6-leave-group) | Leave a group |
+| PATCH | [/api/groups/{id}/](#7-update-group-details) | Update Group Details |
+| POST | [/api/groups/{id}/members](#8-add-member-to-group) | Add members to group |
+| DELETE | [/api/groups/{id}/members/{user_id}](#9-remove-user-from-group) | Remove member from group |
 
-All endpoints except `/api/health`, `/api/auth/register`, and `/api/auth/login` require a `Bearer` token in the `Authorization` header.
 
 ## Health Endpoint
 
@@ -45,7 +57,7 @@ Returned when the server runtime is healthy and can successfully execute a ping
   "success": true,
   "data": {
     "postgres": "up",
-    "timestamp": "<time>"
+    "timestamp": "<TimeStamp>"
   }
 }
 ```
@@ -59,7 +71,7 @@ Returned when the server has encountered an unexpected error (error description
   "success": false,
   "data": {
     "postgres": "down",
-    "timestamp": "<time>"
+    "timestamp": "<TimeStamp>"
   },
   "error": "Database engine unreachable"
 }
@@ -73,7 +85,7 @@ Returned when the server has encountered an unexpected error (error description
 - **Method:** `POST`
 - **Headers:** `Content-Type: application/json`
 - **Authentication Required:** `NO`
-- **curl:** `curl -X POST http://HOST:PORT/api/auth/register  -H "Content-Type: application/json" -d '{ "username": "<username>", "display_name": "Full Name", "password": "<password>" }' -s | jq .`
+- **curl:** `curl -X POST http://HOST:PORT/api/auth/register  -H "Content-Type: application/json" -d '{ "username": "<username>", "display_name": "Full Name", "password": "<password>" }' -s`
 
 #### Request Body
 
@@ -107,7 +119,7 @@ Returned when the account/user is successfully created
       "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
       "username": "<username>",
       "display_name": "Full Name",
-      "created_at": "<created_time>"
+      "created_at": "<TimeStamp>"
     }
   }
 }
@@ -130,7 +142,7 @@ Returned when the json does not contain valid payload (error description provide
 - **Method:** `POST`
 - **Headers:** `Content-Type: application/json`
 - **Authentication Required:** `NO`
-- **curl:** `curl -X POST http://HOST:PORT/api/auth/login -H "Content-Type: application/json" -d '{ "username": "<username>", "password": "<password>" }' -s | jq .`
+- **curl:** `curl -X POST http://HOST:PORT/api/auth/login -H "Content-Type: application/json" -d '{ "username": "<username>", "password": "<password>" }' -s`
 
 #### Request Body
 
@@ -159,7 +171,7 @@ Returned when User has successfully logged in
       "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
       "username": "<username>",
       "display_name": "Full Name",
-      "created_at": "<created_time>"
+      "created_at": "<Timestamp>"
     }
   }
 }
@@ -193,7 +205,7 @@ Returned when json payload structure is incorrect
 - **Method:** `POST`
 - **Headers:** `Content-Type: application/json`
 - **Authentication Required:** `NO`
-- **curl:** `curl -X POST http://HOST:PORT/api/auth/refresh -H "Content-Type: application/json -d '{ "refresh_token": "<refresh_token>" }' -s | jq .`
+- **curl:** `curl -X POST http://HOST:PORT/api/auth/refresh -H "Content-Type: application/json" -d '{ "refresh_token": "<refresh_token>" }' -s`
 
 #### Request Body
 
@@ -255,7 +267,7 @@ Returned when user data is successfully retrieved
     "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
     "username": "<username>",
     "display_name": "Full Name",
-    "created_at": "<created_time>"
+    "created_at": "<Timestamp>"
   }
 }
 ```
@@ -295,7 +307,7 @@ Returned when user is successfully found
     "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
     "username": "<username>",
     "display_name": "Full name",
-    "created_at": "<created_time>"
+    "created_at": "<Timestamp>"
   }
 }
 ```
@@ -347,13 +359,13 @@ Returned when user is successfully found
       "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
       "username": "<username>",
       "display_name": "Full Name",
-      "created_at": "<created_time>"
+      "created_at": "<Timestamp>"
     },
     {
       "id": "bbbbbbbb-bbbb-bbbb-bbbbbbbbbbbb",
       "username": "<username>",
       "display_name": "Full Name",
-      "created_at": "<created_time>"
+      "created_at": "<Timestamp>"
     }
   ]
 }
@@ -392,7 +404,7 @@ Returned when search has failed to execute
 
 ## WebSocket Endpoints
 
-Connect to websocket
+### 1. Connect to websocket
 
 - **URL:** `/api/ws?token={access_token}`
 - **Method:** `WS (websocket Upgrade)`
@@ -400,9 +412,9 @@ Connect to websocket
 - **Authentication Required:** `YES`
 - **wscat:** `wscat -c "ws://HOST:PORT/api/ws?token={access_token}"`
 
-### Expected Response
+#### Expected Response
 
-#### `101 Switching Protocols`
+##### `101 Switching Protocols`
 
 Returned when websocket is successfully connected
 
@@ -410,7 +422,7 @@ Returned when websocket is successfully connected
 connected to ws://HOST:PORT/api/ws?token={access_token}
 ```
 
-#### `Unexpected server response: 404`
+##### `Unexpected server response: 404`
 
 Returned when access token is expired or incorrect
 
@@ -418,6 +430,159 @@ Returned when access token is expired or incorrect
 WebSocket error: Unexpected server response: 404
 ```
 
+### Notes
+* If chat is done in group group_id will be used instead of receiver_id and vice versa.
+
+### 2. Client to Server Messages
+
+#### 1. Send Chat Message
+Sends a direct or group message. 
+
+##### Request Body
+No Reply
+```json
+{
+  "type":"chat",
+  "receiver_id":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
+  "content":"<content>"
+}
+```
+Reply
+```json
+{
+  "type":"chat",
+  "receiver_id":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
+  "content":"<content>",
+  "reply_to_message_id":"<message_id of message being replied to>"
+}
+```
+##### Notes
+* If chat is done in group group_id will be used instead of receiver_id and vice versa.
+
+
+#### 2. Read Recipet
+Marks messages as read.
+
+##### Request Body
+```json
+{
+  "type":"read_receipt",
+  "receiver_id":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
+}
+```
+##### Notes
+* If chat is done in group group_id will be used instead of receiver_id and vice versa.
+
+#### 3. Request Online Status
+Checks whether a specific user is currently connected.
+
+##### Request Body
+```json
+{
+  "type":"request_status",
+  "receiver_id":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
+}
+```
+##### Notes
+* If chat is done in group group_id will be used instead of receiver_id and vice versa.
+
+#### 4. Typing Indicator
+
+
+##### Request Body
+```json
+{
+  "type": "typing",
+  "receiver_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
+}
+```
+##### Notes
+* If chat is done in group group_id will be used instead of receiver_id and vice versa.
+
+### 3. Server to Client Messages
+
+#### 1. Incoming Chat Message (no reply)
+Delivered when another user sends you a direct or group message.
+
+##### Response
+```json
+{
+  "type": "chat",
+  "sender_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
+  "receiver_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
+  "content": "<content>",
+  "message_id": "<message_id>",
+  "timestamp": "<Timestamp>"
+}
+```
+##### Notes
+* If chat is done in group group_id will be used instead of receiver_id and vice versa.
+
+#### 2. Incoming Chat Message (with reply)
+Delivered when another user replies to a message. Includes the original quoted message.
+
+##### Response
+```json
+{
+  "type": "chat",
+  "sender_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
+  "receiver_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
+  "content": "<content>",
+  "message_id": "<message_id>",
+  "reply_to_message_id": "<message_id_of_message_to_be_replied>",
+  "timestamp": "<created_time>",
+  "quoted_message": {
+    "content": "<original message content>",
+    "sender_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
+  }
+}
+```
+##### Notes
+* If chat is done in group group_id will be used instead of receiver_id and vice versa.
+
+#### 3. Typing Indicator
+Delivered when another user is typing to you or in a shared group.
+
+##### Response
+```json
+{
+  "type": "typing",
+  "sender_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
+  "receiver_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
+}
+```
+##### Notes
+* If chat is done in group group_id will be used instead of receiver_id and vice versa.
+
+#### 4. Read Receipt
+Delivered when the recipient reads your message.
+
+##### Response
+```json
+{
+  "type": "read_receipt",
+  "sender_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
+  "receiver_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
+  "timestamp": "<created_time>"
+}
+```
+##### Notes
+* If chat is done in group group_id will be used instead of receiver_id and vice versa.
+
+#### 5. User Status
+Broadcast to all connected clients when a user connects or disconnects. Also sent as a direct response to request_status
+
+##### Response
+```json
+{
+  "type": "user_status",
+  "user_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
+  "online": true
+}
+```
+##### Notes
+* If chat is done in group group_id will be used instead of receiver_id and vice versa.
+
 ## Messages Endpoints
 
 ### 1. Send Message
@@ -471,7 +636,7 @@ Returned when access token is expired or incorrect
 
 To get message history with specific user using user id
 
-- **URL:** `/api/users/messages/?with={receiver_id}&before={time}&limit={limit}`
+- **URL:** `/api/messages/?with={receiver_id}&before={time}&limit={limit}`
 - **Method:** `GET`
 - **Headers:** `Content-Type: application/json`
 - **Authentication Required:** `YES`
@@ -492,7 +657,7 @@ Returned when data is successfully retrieved
       "sender_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
       "receiver_id": "bbbbbbbb-bbbb-bbbb-bbbbbbbbbbbb",
       "content": "<content>",
-      "created_at": "<created_time>"
+      "created_at": "<Timestamp>"
     }
   ]
 }
@@ -508,3 +673,508 @@ Returned when access token is expired or incorrect
   "error": "Access token missing, expired or malformed"
 }
 ```
+
+### 3. Conversations
+To retrieve user conversations
+
+- **URL:** `/api/messages/conversations`
+- **Method:** `GET`
+- **Headers:** `Content-Type: application/json`
+- **Authentication Required:** `YES`
+- **curl:** `curl -X GET "http://HOST:PORT/api/messages/conversations" -H "Authorization: Bearer <access_token>"`
+
+#### Expected Response
+
+##### `200 OK`
+Conversations is successfully retrieved.
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "<user_id of receiver>",
+      "type": "<direct or group>",
+      "name": "<username>",
+      "display_name": "<display Name>",
+      "last_message": "<content>",
+      "last_message_time": "<last message time>",
+      "sender_id": "<user_id>",
+      "is_read": (bool)"<read of coresponding user>",
+      "unread_count": (int)0"<unread_count of corresponding user>"
+    }
+  ]
+}
+```
+
+##### `401 Unauthorized`
+Access token is missing or expired.
+```json
+{
+  "success": false,
+  "error": "Access token missing, expired or malformed"
+}
+```
+
+### 4. Read
+To get read mark for a user
+
+- **URL:** `/api/messages/read`
+- **Method:** `POST`
+- **Headers:** `Content-Type: application/json`
+- **Authentication Required:** `YES`
+- **curl:** `curl -X POST "http://HOST:PORT/api/messages/read" -H "Authorization: Bearer <access_token>" -d '{ "sender_id": "<sender_id>" }'`
+
+#### Request Body
+```json
+{
+  "sender_id":"<sender_id>"
+}
+```
+
+#### Expected Responses
+
+##### `200 OK`
+```json
+{
+  "success": true,
+  "data": "Target messages marked read successfully"
+}
+```
+
+##### `401 Unauthorized`
+```json
+{
+  "success": false,
+  "error": "Access token missing, expired or malformed"
+}
+```
+
+## Group Endpoints
+
+### 1. Create Group
+- **URL:** `/api/groups/`
+- **Method:** `POST`
+- **Headers:** `Content-Type: application/json`
+- **Authentication Required:** `YES`
+- **curl:** `curl -X POST "http://HOST:PORT/api/groups/" -H "Authorization: Bearer <access_token>" -d '{ "name" : "group_name" }'`
+
+#### Request Body
+```json
+{
+  "name":"<group_name>"
+}
+```
+
+#### Expected Responses
+
+##### `201 Created`
+Returned when group is successfully created
+```json
+{
+  "success": true,
+  "data": {
+    "id": "<group_id>",
+    "name": "noobs",
+    "created_by": "<creator_id>",
+    "created_at": "<Timestamp>"
+  }
+}
+```
+
+##### `401 Unauthorized`
+Returned when access token is expried or incorrect.
+```json
+{
+  "success": false,
+  "error": "Access token missing, expired or malformed"
+}
+```
+
+### 2. Get Groups
+
+- **URL:** `/api/groups/`
+- **Method:** `GET`
+- **Headers:** `Content-Type: application/json`
+- **Authentication Required:** `YES`
+- **curl:** `curl -X GET "http://HOST:PORT/api/groups/" -H "Authorization: Bearer <access_token>"`
+
+#### Expected Response
+
+##### `200 OK`
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "<group_id>",
+      "name": "<group_name>",
+      "created_by": "<creator_id>",
+      "created_at": "<Timestamp>"
+    },
+    {
+      "id": "<group_id>",
+      "name": "<group_name>",
+      "created_by": "<creator_id>",
+      "created_at": "<Timestamp>"
+    }
+  ]
+}
+```
+
+##### `401 Unauthorized`
+```json
+{
+  "success": false,
+  "error": "Access token missing, expired or malformed"
+}
+```
+
+### 3. Get Group by Group ID
+
+- **URL:** `/api/groups/{id}`
+- **Method:** `GET`
+- **Headers:** `Content-Type: application/json`
+- **Authentication Required:** `YES`
+- **curl:** `curl -X GET "http://HOST:PORT/api/groups/{id}" -H "Authorization: Bearer <access_token>"`
+
+#### Expected Response
+
+##### `200 OK`
+Returned when group with given id is retrieved
+
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "<group_id>",
+      "name": "<group_name>",
+      "created_by": "<creator_id>",
+      "created_at": "Timestamp"
+    },
+    {
+      "id": "<group_id>",
+      "name": "<group_name>",
+      "created_by": "<creator_id>",
+      "created_at": "Timestamp"
+    }
+  ]
+}
+```
+
+##### `403 Forbidden`
+Returned when you are not a member of group with given group id or the group id is incorrect
+
+```json
+{
+  "success": false,
+  "error": "Access denied: you are not a member of this group"
+}
+```
+
+##### `401 Unauthorized`
+Returned when access token is expired or incorrect
+```json
+{
+  "success": false,
+  "error": "Access token missing, expired or malformed"
+}
+```
+
+### 4. Get messages of group
+
+- **URL:** `/api/groups/{id}/messages`
+- **Method:** `GET`
+- **Headers:** `Content-Type: application/json`
+- **Authentication Required:** `YES`
+- **curl:** `curl -X GET "http://HOST:PORT/api/groups/{id}/messages" -H "Authorization: Bearer <access_token>"`
+
+#### Expected Response
+
+##### `200 OK`
+Returned when messages is successfully retrieved
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "<message_id>",
+      "sender_id": "<sender_id>",
+      "group_id": "<group_id>",
+      "content": "<content>",
+      "created_at": "<Timestamp>",
+      "is_read": (bool)"<read_status>"
+    }
+  ]
+}
+```
+
+##### `403 Forbidden`
+Returned if user are not member of the group with given group id or group id is incorrect
+```json
+{
+  "success": false,
+  "error": "Access denied: you are not a member of this group"
+}
+```
+
+##### `401 Unauthorized`
+Returned if access token is expired or incorrect
+```json
+{
+  "success": false,
+  "error": "Access token missing, expired or malformed"
+}
+```
+
+### 5. Group members
+Get members of a group
+
+- **URL:** `/api/groups/{id}/members`
+- **Method:** `GET`
+- **Headers:** `Content-Type: application/json`
+- **Authentication Required:** `YES`
+- **curl:** `curl -X GET "http://HOST:PORT/api/groups/{id}/members" -H "Authorization: Bearer <access_token>"`
+
+#### Expected Response
+
+##### `200 OK`
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "user_id": "<user_id>",
+      "username": "<username>",
+      "display_name": "<Full Name>",
+      "role": "<role>",
+      "joined_at": "Timestamp"
+    },
+    {
+      "user_id": "<user_id>",
+      "username": "<username>",
+      "display_name": "<Full Name>",
+      "role": "<role>",
+      "joined_at": "Timestamp"
+    }
+  ]
+}
+```
+* **Note:** Role can either be admin or member. 
+
+##### `403 Forbidden`
+Returned when user is not a member of group with given group id or group id is incorrect or if user is not admin of group
+```json
+{
+  "success": false,
+  "error": "Access denied: you are not a member of this group"
+}
+```
+
+##### `401 Unauthorized`
+Returned when access token is expired or incorrect
+```json
+{
+  "success": false,
+  "error": "Access token missing, expired or malformed"
+}
+```
+
+
+### 6. Leave Group
+
+- **URL:** `/api/messages/groups/{id}/leave`
+- **Method:** `POST`
+- **Headers:** `Content-Type: application/json`
+- **Authentication Required:** `YES`
+- **curl:** `curl -X POST "http://HOST:PORT/api/groups/{id}/leave" -H "Authorization: Bearer <access_token>"`
+
+#### Expected Response
+
+##### `200 OK`
+Returned when user successfully left the group
+```json
+{
+  "success": true,
+  "data": "You have left the group"
+}
+```
+
+##### `403 Forbidden`
+Returned when user is not a member of group with given group id or group id is incorrect or if user is not admin of group
+```json
+{
+  "success": false,
+  "error": "Access denied: you are not a member of this group"
+}
+```
+
+##### `401 Unauthorized`
+Returned when access token is expired or incorrect
+```json
+{
+  "success": false,
+  "error": "Access token missing, expired or malformed"
+}
+```
+
+### 7. Update Group Details
+
+- **URL:** `/api/messages/groups/{id}/`
+- **Method:** `PATCH`
+- **Headers:** `Content-Type: application/json`
+- **Authentication Required:** `YES`
+- **Admin Access Required:** `YES`
+- **curl:** `curl -X PATCH "http://HOST:PORT/api/groups/{id}/" -H "Authorization: Bearer <access_token>" -d '{ "name":"<group_name>" }'`
+
+#### Response Body
+```json
+{
+  "name":"<new_group_name>"
+}
+```
+
+#### Expected Response
+
+##### `200 OK`
+Returned when group details are successfully updated.
+```json
+{
+  "success": true,
+  "data": "Group details updated successfully"
+}
+```
+
+##### `403 Forbidden`
+Returned when user is not a member of group with given group id or group id is incorrect or if user is not admin of group
+```json
+{
+  "success": false,
+  "error": "Access denied: you are not a member of this group"
+}
+```
+```json
+{
+  "success": false,
+  "error": "Administrative clearance privileges required"
+}
+```
+
+##### `401 Unauthorized`
+Returned when access token is expired or incorrect
+```json
+{
+  "success": false,
+  "error": "Access token missing, expired or malformed"
+}
+```
+
+### 8. Add Member to group
+- **URL:** `/api/messages/groups/{id}/members`
+- **Method:** `POST`
+- **Headers:** `Content-Type: application/json`
+- **Authentication Required:** `YES`
+- **Admin Access Required:** `YES`
+- **curl:** `curl -X POST "http://HOST:PORT/api/groups/{id}/members" -H "Authorization: Bearer <access_token>" -d '{ "user_id":"<user_id>" }'`
+
+#### Request Body
+```json
+{
+  "user_id":"<user_id>"
+}
+```
+
+#### Expected Responses
+
+##### `200 OK`
+Returned when user is successfully added to group
+```json
+{
+  "success": true,
+  "data": "User attached to channel context cleanly"
+}
+```
+
+##### `500 Internal Server Error`
+Returned when user with given user id does not exist
+```json
+{
+  "success": false,
+  "error": "Failed to add member to channel"
+}
+```
+
+##### `403 Forbidden`
+Returned when user is not a member of group with given group id or group id is incorrect or if user is not admin of group
+```json
+{
+  "success": false,
+  "error": "Access denied: you are not a member of this group"
+}
+```
+```json
+{
+  "success": false,
+  "error": "Administrative clearance privileges required"
+}
+```
+
+##### `401 Unauthorized`
+Returned when access token is expired or incorrect
+```json
+{
+  "success": false,
+  "error": "Access token missing, expired or malformed"
+}
+```
+
+### 9. Remove User from Group
+- **URL:** `/api/messages/groups/{id}/members/{user_id}`
+- **Method:** `DELETE`
+- **Headers:** `Content-Type: application/json`
+- **Authentication Required:** `YES`
+- **Admin Access Required:** `YES`
+- **curl:** `curl -X DELETE "http://HOST:PORT/api/groups/{id}/members/{user_id}" -H "Authorization: Bearer <access_token>"`
+
+#### Expected Response
+
+##### `200 OK`
+Returned when user is successfully removed from group
+```json
+{
+  "success": true,
+  "data": "Member detached from group context cleanly"
+}
+```
+##### `500 Internal Server Error`
+Returned when user with given user id does not exist
+```json
+{
+  "success": false,
+  "error": "Failed to add member to channel"
+}
+```
+
+##### `403 Forbidden`
+Returned when user is not a member of group with given group id or group id is incorrect or if user is not admin of group
+```json
+{
+  "success": false,
+  "error": "Access denied: you are not a member of this group"
+}
+```
+```json
+{
+  "success": false,
+  "error": "Administrative clearance privileges required"
+}
+```
+
+##### `401 Unauthorized`
+Returned when access token is expired or incorrect
+```json
+{
+  "success": false,
+  "error": "Access token missing, expired or malformed"
+}
+```
\ No newline at end of file

From 781ff32f46459a455ef2af47373a1af22bdd9d4a Mon Sep 17 00:00:00 2001
From: Golden_Eagle07 <challamanideepreddy@gmail.com>
Date: Wed, 8 Jul 2026 16:58:57 +0530
Subject: [PATCH 2/3] updated api

---
 docs/API_CONTRACTS.md | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/docs/API_CONTRACTS.md b/docs/API_CONTRACTS.md
index 3cfe8ab..bb8f13f 100644
--- a/docs/API_CONTRACTS.md
+++ b/docs/API_CONTRACTS.md
@@ -17,8 +17,8 @@
 | POST | [/api/auth/login](#2-login-user) | Log in and receive a token pair |
 | POST | [/api/auth/refresh](#3-refresh) | Exchange a refresh token for a new token pair |
 | GET | [/api/users/me](#1-user-me) | Get the authenticated user's profile |
-| GET | [/api/users/:id](#2-search-user-by-id) | Search users by username or display name |
-| GET | [/api/users/search?q=&page=&limit=](#3-search-user-by-username-and-display-name) | Get a public user profile |
+| GET | [/api/users/:id](#2-search-user-by-id) | Search users by User id |
+| GET | [/api/users/search?q=&page=&limit=](#3-search-user-by-username-and-display-name) | Search user by username and display name |
 | GET | [/ws](#1-connect-to-websocket) | WebSocket upgrade endpoint (JWT required) |
 | WS | [Client to Server](#2-client-to-server-messages) | Client to Server Websocket |
 | WS | [Server to Client](#3-server-to-client-messages) | Server to Client Websocket |
@@ -697,10 +697,10 @@ Conversations is successfully retrieved.
       "name": "<username>",
       "display_name": "<display Name>",
       "last_message": "<content>",
-      "last_message_time": "<last message time>",
+      "last_message_time": "<Timestamp",
       "sender_id": "<user_id>",
-      "is_read": (bool)"<read of coresponding user>",
-      "unread_count": (int)0"<unread_count of corresponding user>"
+      "is_read": false/true"<read_status>",
+      "unread_count": 0"<unread_count of corresponding user>"
     }
   ]
 }
@@ -782,7 +782,7 @@ Returned when group is successfully created
 ```
 
 ##### `401 Unauthorized`
-Returned when access token is expried or incorrect.
+Returned when access token is expired or incorrect.
 ```json
 {
   "success": false,
@@ -983,7 +983,7 @@ Returned when access token is expired or incorrect
 
 ### 6. Leave Group
 
-- **URL:** `/api/messages/groups/{id}/leave`
+- **URL:** `/api/groups/{id}/leave`
 - **Method:** `POST`
 - **Headers:** `Content-Type: application/json`
 - **Authentication Required:** `YES`
@@ -1020,14 +1020,14 @@ Returned when access token is expired or incorrect
 
 ### 7. Update Group Details
 
-- **URL:** `/api/messages/groups/{id}/`
+- **URL:** `/api/groups/{id}/`
 - **Method:** `PATCH`
 - **Headers:** `Content-Type: application/json`
 - **Authentication Required:** `YES`
 - **Admin Access Required:** `YES`
 - **curl:** `curl -X PATCH "http://HOST:PORT/api/groups/{id}/" -H "Authorization: Bearer <access_token>" -d '{ "name":"<group_name>" }'`
 
-#### Response Body
+#### Request Body
 ```json
 {
   "name":"<new_group_name>"
@@ -1070,7 +1070,7 @@ Returned when access token is expired or incorrect
 ```
 
 ### 8. Add Member to group
-- **URL:** `/api/messages/groups/{id}/members`
+- **URL:** `/api/groups/{id}/members`
 - **Method:** `POST`
 - **Headers:** `Content-Type: application/json`
 - **Authentication Required:** `YES`
@@ -1129,7 +1129,7 @@ Returned when access token is expired or incorrect
 ```
 
 ### 9. Remove User from Group
-- **URL:** `/api/messages/groups/{id}/members/{user_id}`
+- **URL:** `/api/groups/{id}/members/{user_id}`
 - **Method:** `DELETE`
 - **Headers:** `Content-Type: application/json`
 - **Authentication Required:** `YES`

From 3791cf4e2ba3790d77b81627bab0e855b9862856 Mon Sep 17 00:00:00 2001
From: Golden_Eagle07 <challamanideepreddy@gmail.com>
Date: Wed, 8 Jul 2026 19:15:23 +0530
Subject: [PATCH 3/3] Corrected readme

---
 README.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/README.md b/README.md
index c06ad3f..b823835 100644
--- a/README.md
+++ b/README.md
@@ -125,6 +125,13 @@ flutter run
 | `ARGON_MEMORY` | Argon2id memory cost (KB) | `65536` |
 | `ARGON_ITERATIONS` | Argon2id iteration count | `3` |
 | `ARGON_PARALLELISM` | Argon2id parallelism degree | `2` |
+|`GOOGLE_CLIENT_ID`| Google OAuth client ID| — |
+| `GOOGLE_CLIENT_SECRET` | Google OAuth client secrett | — |
+| `GOOGLE_REDIRECT_URL` | Google OAuth redirect callback URL | `http://HOST:PORT/api/auth/google/callback` |
+| `GITHUB_CLIENT_ID` | GitHub OAuth client ID | — |
+| `GITHUB_CLIENT_SECRET` | GitHub OAuth client secret | — |
+| `GITHUB_REDIRECT_URL` | GitHub OAuth redirect callback URL | `http://HOST:PORT/api/auth/github/callback` |
+
  
 See `.env.example` for a starting template.