docs/project-specs.md

Project Technical Specifications

This document outlines the technical details of the project's database structure and data objects, as required for developing server-side functions like push notifications.

1. Database Structure (JSON Structure)

Firestore (For User Information)

User profiles, including their FCM token for notifications, are stored in Firestore.

• Path to Users: /users/{userId}
• Example User Object in Firestore:

  {
    "uid": "user_abc_123",
    "displayName": "Ahmed",
    "publicId": "ahmed123",
    "photoURL": "https://.../avatar.png",
    "fcmToken": "c3p...very_long_and_unique_token...w9G"
  }
  

Realtime Database (For Chat Messages)

Real-time messaging is handled by the Realtime Database for speed.

• Path to Chats: /chats/{chatId}/messages/{messageId}
  • The chatId for private chats is generated by combining the UIDs of the two users, sorted alphabetically (e.g., private_user1_user2).
  • The chatId for group chats is the unique ID of the group.
• Example JSON structure in Realtime Database:

  {
    "chats": {
      "private_user1_user2": {
        "messages": {
          "msg_xyz_789": {
            "sender": "user1",
            "senderDisplayName": "Alice",
            "text": "Hello Bob!",
            "timestamp": 1678886400000,
            "deliveredTo": {
              "user1": 1678886400000
            }
          }
        },
        "participants": {
           "user1": true,
           "user2": true
        }
      }
    }
  }
  

---

2. Message Object Details

This is the structure of the message object saved under /chats/{chatId}/messages/{messageId}.

• Is there a receiverId field? No. The recipient is inferred from the chatId. In a private chat like private_user1_user2, if the sender is user1, the recipient is user2.

• Is there a senderName field? Yes, the field is named senderDisplayName.

• Example Message Object:

  {
    "sender": "user_abc_123",
    "senderDisplayName": "Ahmed",
    "senderPhotoUrl": "https://.../avatar.png",
    "text": "Hello, how are you?",
    "timestamp": { ".sv": "timestamp" },
    "deliveredTo": {
      "user_abc_123": { ".sv": "timestamp" }
    }
  }
  

---

3. Multiple Devices

• Currently, the system saves only one FCM token per user as a String in their Firestore document.
• This means that notifications are sent to the last device that registered its token. The system does not support sending notifications to multiple devices for the same user simultaneously.

---

4. Tech Stack

• Backend Logic (Cloud Functions): We are using TypeScript within Next.js API Routes (e.g., src/app/api/.../route.ts). This serves as the server-side environment instead of traditional Cloud Functions.

• Frontend Firebase SDK: The project uses the modern Firebase SDK v9 (Modular). Imports follow the pattern: import { ... } from 'firebase/database';.