Data Dictionary

Overview

This document describes the complete data structure used in TalaTalk’s Firebase Firestore database. All data is stored as NoSQL documents organized in collections with proper security rules and relationships.

User Management

`users` Collection

Purpose: Stores authentication and profile data for all users (teachers and parents)

User Fields

Field	Type	Required	Description
`uid`	string	✅	Firebase Auth UID (document ID)
`email`	string	✅	User’s email address
`fullName`	string	✅	User’s full name
`role`	string	✅	User role: “teacher” or “parent”
`phoneNumber`	string	❌	User’s phone number
`profilePictureUrl`	string	❌	URL to profile picture
`createdAt`	Timestamp	✅	Account creation time
`updatedAt`	Timestamp	✅	Last profile update
`verified`	boolean	❌	Whether user is verified
`classroomCode`	string	❌	Classroom code for teachers

Security Rule: allow read, write: if request.auth != null && request.auth.uid == userId

Classroom Management

`classrooms` Collection

Purpose: Stores classroom information created by teachers

Classroom Fields

Field	Type	Required	Description
`id`	string	✅	Document ID (auto-generated)
`school_id`	string	✅	School identifier
`classroom_code`	string	✅	Unique classroom code
`room_number`	string	❌	Physical room number
`grade_level`	string	❌	Grade level (e.g., “Grade 1”)
`section`	string	❌	Section (e.g., “A”, “B”)
`capacity`	number	✅	Maximum students allowed
`teacher_id`	string	✅	Teacher’s UID
`subject_area`	string	❌	Subject taught
`academic_year`	string	❌	Academic year
`created_at`	Timestamp	✅	Creation timestamp
`qr_code_data`	string	❌	QR code for easy access

`classroom_parents` Collection

Purpose: Links parents to classrooms for access control

Classroom Parents Fields

Field	Type	Required	Description
`parent_id`	string	✅	Parent’s UID
`classroom_id`	string	✅	Classroom ID
`joined_at`	Timestamp	✅	When parent joined

Student Management

`students` Collection

Purpose: Stores student information

Student Fields

Field	Type	Required	Description
`id`	string	✅	Document ID (auto-generated)
`student_number`	string	✅	Unique student number
`first_name`	string	✅	Student’s first name
`last_name`	string	✅	Student’s last name
`date_of_birth`	string/Date	✅	Date of birth
`gender`	string	✅	Gender: “male”, “female”, “other”
`grade_level`	string	✅	Current grade level
`address`	string	❌	Home address
`emergency_contact`	string	❌	Emergency contact details
`enrollment_date`	Timestamp	✅	When enrolled
`status`	string	✅	Status: “active”, “inactive”, “graduated”
`parent_ids`	array	❌	Array of parent UIDs

`student_classrooms` Collection

Purpose: Tracks student enrollment in classrooms

Student Classrooms Fields

Field	Type	Required	Description
`student_id`	string	✅	Student’s document ID
`classroom_id`	string	✅	Classroom ID
`enrolled_at`	Timestamp	✅	Enrollment timestamp
`status`	string	✅	Status: “active”, “dropped”, “completed”
`final_grade`	number	❌	Final grade if completed

`parent_students` Collection

Purpose: Links parents to their children

Parent Students Fields

Field	Type	Required	Description
`parent_id`	string	✅	Parent’s UID
`student_id`	string	✅	Student’s document ID
`relationship_type`	string	✅	“father”, “mother”, “guardian”, “sibling”
`is_primary_contact`	boolean	✅	Whether primary contact
`created_at`	Timestamp	✅	Relationship creation time

Communication System

`messages` Collection

Purpose: Stores direct messages between users

Message Fields

Field	Type	Required	Description
`id`	string	✅	Document ID (auto-generated)
`sender_id`	string	✅	Sender’s UID
`receiver_id`	string	✅	Receiver’s UID
`classroom_id`	string	❌	Associated classroom
`subject`	string	❌	Message subject
`message_content`	string	✅	Message text content
`sent_at`	Timestamp	✅	When message was sent
`read_at`	Timestamp	❌	When message was read
`priority_level`	string	✅	“low”, “medium”, “high”, “urgent”
`message_type`	string	✅	“direct”, “announcement”, “alert”
`is_read`	boolean	✅	Whether message has been read
`parent_message_id`	string	❌	For reply threading
`attachment_url`	string	❌	URL to attached file
`conversation_id`	string	❌	For conversation grouping

`conversations` Collection

Purpose: Groups messages into conversations for better organization

Conversation Fields

Field	Type	Required	Description
`id`	string	✅	Document ID (auto-generated)
`participants`	array	✅	Array of user UIDs (always 2 for direct)
`conversation_type`	string	✅	“direct”
`last_message`	string	❌	Last message content
`last_message_at`	Timestamp	❌	When last message was sent
`last_message_sender`	string	❌	UID of last message sender
`created_at`	Timestamp	✅	Conversation creation time
`updated_at`	Timestamp	✅	Last update time
`unread_count`	object	❌	`{userId: count}` for each participant

`announcements` Collection

Purpose: Stores announcements made by teachers

Announcement Fields

Field	Type	Required	Description
`id`	string	✅	Document ID (auto-generated)
`teacher_id`	string	✅	Teacher’s UID
`classroom_id`	string	❌	Associated classroom
`title`	string	✅	Announcement title
`content`	string	✅	Announcement content
`posted_at`	Timestamp	✅	When posted
`expires_at`	Timestamp	❌	When announcement expires
`priority_level`	string	✅	“low”, “medium”, “high”, “urgent”
`announcement_type`	string	✅	“general”, “academic”, “event”, “emergency”
`is_active`	boolean	✅	Whether currently active
`attachment_url`	string	❌	URL to attached file
`attachments`	array	❌	Array of `AnnouncementAttachment` objects

Document Management

`documents` Collection

Purpose: Stores metadata for uploaded documents

Document Fields

Field	Type	Required	Description
`id`	string	✅	Document ID (auto-generated)
`teacher_id`	string	✅	Teacher who uploaded
`classroom_id`	string	❌	Associated classroom
`file_name`	string	✅	Original filename
`file_url`	string	✅	Firebase Storage URL
`file_size`	number	✅	File size in bytes
`file_type`	string	✅	MIME type
`uploaded_by`	string	✅	Teacher’s name
`uploaded_at`	Timestamp	✅	Upload timestamp

Event Management

`events` Collection

Purpose: Stores calendar events and activities

Event Fields

Field	Type	Required	Description
`id`	string	✅	Document ID (auto-generated)
`created_by`	string	✅	Creator’s UID
`classroom_id`	string	❌	Associated classroom
`event_title`	string	✅	Event title
`description`	string	❌	Event description
`start_datetime`	Date/Timestamp	✅	Event start time
`end_datetime`	Date/Timestamp	✅	Event end time
`location`	string	❌	Event location
`event_type`	string	✅	“meeting”, “conference”, “activity”, “exam”, “holiday”
`status`	string	✅	“scheduled”, “ongoing”, “completed”, “cancelled”
`is_recurring`	boolean	✅	Whether event repeats
`recurrence_pattern`	string	❌	Recurrence pattern if applicable

Notification System

`notifications` Collection

Purpose: Stores system notifications for users

Notification Fields

Field	Type	Required	Description
`id`	string	✅	Document ID (auto-generated)
`user_id`	string	✅	Recipient’s UID
`title`	string	✅	Notification title
`content`	string	✅	Notification content
`notification_type`	string	✅	“message”, “announcement”, “event”, “grade”, “attendance”
`conversation_id`	string	❌	Related conversation ID
`is_read`	boolean	✅	Whether notification has been read
`is_push_sent`	boolean	✅	Whether push notification was sent
`created_at`	Timestamp	✅	Creation timestamp
`sent_at`	Timestamp	❌	When notification was sent

`user_device_tokens` Collection

Purpose: Stores FCM tokens for push notifications

Device Token Fields

Field	Type	Required	Description
`id`	string	✅	Document ID (auto-generated)
`user_id`	string	✅	User’s UID
`fcm_token`	string	✅	Firebase Cloud Messaging token
`device_type`	string	✅	“android”, “web”
`created_at`	Timestamp	✅	Token creation time
`updated_at`	Timestamp	✅	Last update time

Data Relationships

Key Relationships

Users → Classrooms (One-to-Many via teacher_id)
Classrooms → Students (Many-to-Many via student_classrooms)
Parents → Students (Many-to-Many via parent_students)
Users → Messages (One-to-Many via sender_id/receiver_id)
Classrooms → Announcements (One-to-Many via classroom_id)
Users → Notifications (One-to-Many via user_id)

Security Rules

Firestore Security Rules

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Users collection
    match /users/{userId} {
      allow read, write: if request.auth != null && 
        (request.auth.uid == userId || request.auth.uid in resource.data.participants);
    }
    
    // Students collection
    match /students/{studentId} {
      allow read, write: if request.auth != null;
    }
    
    // Student classrooms collection
    match /student_classrooms/{enrollmentId} {
      allow read, write: if request.auth != null;
    }
    
    // Classrooms collection
    match /classrooms/{classroomId} {
      allow read, write: if request.auth != null;
    }
    
    // Messages collection
    match /messages/{messageId} {
      allow read, write: if request.auth != null && 
        (resource.data.sender_id == request.auth.uid || 
         resource.data.receiver_id == request.auth.uid);
    }
    
    // Conversations collection
    match /conversations/{conversationId} {
      allow read, write: if request.auth != null && 
        request.auth.uid in resource.data.participants;
    }
    
    // Notifications collection
    match /notifications/{notificationId} {
      allow read, write: if request.auth != null && 
        resource.data.user_id == request.auth.uid;
    }
    
    // Device tokens collection
    match /user_device_tokens/{userId} {
      allow read, write: if request.auth != null && 
        resource.data.user_id == request.auth.uid;
    }
  }
}

Usage Patterns

Common Queries

Get user’s classrooms: classrooms where teacher_id == user.uid
Get classroom students: students where classroom_id == classroom.id
Get user messages: messages where receiver_id == user.uid
Get classroom announcements: announcements where classroom_id == classroom.id
Get user notifications: notifications where user_id == user.uid

Data Flow

Teacher creates classroom → classrooms collection
Teacher adds students → students + student_classrooms collections
Parent joins classroom → classroom_parents collection
Teacher creates announcement → announcements collection
User sends message → messages + conversations collections
System creates notification → notifications collection

Notes

Important Notes

All timestamps use Firebase Timestamp type
Document IDs are auto-generated unless specified
Arrays are used for multi-value fields (e.g., participants, parent_ids)
Optional fields are marked with ❌ in the Required column
All collections require authentication (request.auth != null)
Storage paths follow the pattern: ///

Get Started

Technical Overview

Communication

Authentication

​Data Dictionary

Overview

​User Management

​users Collection

User Fields

​Classroom Management

​classrooms Collection

Classroom Fields

​classroom_parents Collection

Classroom Parents Fields

​Student Management

​students Collection