Firestore Schema Documentation

This document provides a comprehensive reference for all Firestore collections, their paths, types, and field descriptions.

Note: This is generated from the schema file. For the source of truth, see src/schema/firestoreSchema.ts

Table of Contents

• Root Collections
• Organization Subcollections
• User Subcollections
• Type Definitions

---

Root Collections

orgsPub - Public Organizations

Path: orgsPub/{orgId}
Type: OrganizationPublic
Description: Public-facing organization data visible to all users

Subcollections:

• vacancies - Public job postings
• docs - Public documents
• members - Public member list

orgs - Private Organizations

Path: orgs/{orgId}
Type: OrganizationPrivate
Description: Private organization data accessible only to members

See Organization Subcollections below.

usersPub - Public Users

Path: usersPub/{userId}
Type: User
Description: Public user profile data

Subcollections:

• orgMemberships - Organizations the user is a member of

users - Private Users

Path: users/{userId}
Type: User
Description: Private user data (admin only)

contracts - Contracts

Path: contracts/{contractId}
Type: Contract
Description: Global contract templates

---

Organization Subcollections

All subcollections are under orgs/{orgId}/

Members

Path: orgs/{orgId}/members/{userId}
Type: Member

Fields:

• userId (string) - User ID
• role (string) - Member role (admin, member, etc.)
• addedAt (Date | Timestamp) - When member joined
• position (string?) - Job position/title
• isMember (boolean?) - Active member flag
• meetingCount (number?) - Total meetings attended
• attendanceRate (number?) - Attendance percentage (0-100)
• lastAttendanceCalculatedAt (Date | Timestamp?) - Last attendance calculation

Tasks

Path: orgs/{orgId}/tasks/{taskId}
Type: Task

Subcollections:

• votes - User votes on tasks

Meetings

Path: orgs/{orgId}/meetings/{meetingId}
Type: Meeting

Subcollections:

• attendance - Meeting attendance records

Daily Meetings

Path: orgs/{orgId}/dailyMeetings/{meetingId}
Type: DailyMeeting

Visitors

Path: orgs/{orgId}/visitors/{userId}
Type: Visitor

Subcollections:

• messages - Messages from visitors

Warnings

Path: orgs/{orgId}/warnings/{warningId}
Type: Warning

Teams

Path: orgs/{orgId}/teams/{teamId}
Type: Team

Achievements

Path: orgs/{orgId}/achievements/{achievementId}
Type: Achievement

Fields:

• id (string?) - Achievement ID
• orgId (string) - Organization ID
• userId (string) - User who earned achievement
• userName (string) - User display name
• userPhotoURL (string?) - User photo URL
• title (string) - Achievement title
• description (string) - Achievement description
• imageUrls (string[]?) - Achievement images
• videoUrl (string?) - Achievement video
• category (AchievementCategory) - Category type
• createdAt (Date | Timestamp) - Creation date
• updatedAt (Date | Timestamp) - Last update
• votesCount (number) - Number of votes
• status (AchievementStatus) - 'pending' | 'approved' | 'rejected'

Achievement Votes

Path: orgs/{orgId}/achievement-votes/{voteId}
Type: AchievementVote

Nomination Periods

Path: orgs/{orgId}/nomination-periods/{periodId}
Type: NominationPeriod

Nomination Votes

Path: orgs/{orgId}/nomination-votes/{voteId}
Type: NominationVote

Contract Signatures

Path: orgs/{orgId}/contract-signatures/{userId}
Type: ContractSignature

Applications

Path: orgs/{orgId}/applications/{applicationId}
Type: Application

Commitments

Path: orgs/{orgId}/commitments/{commitmentId}
Type: WeeklyCommitment

Fields:

• id (string?) - Commitment ID
• orgId (string) - Organization ID
• userId (string) - User who made commitment
• teamId (string?) - Team ID if team-specific
• weekStartDate (Date | Timestamp) - Monday of the week (ISO week)
• title (string) - What they commit to do
• description (string?) - Optional details
• confidenceScore (number?) - 0-100 confidence level
• project (string?) - Related project/priority
• createdAt (Date | Timestamp) - Creation date
• updatedAt (Date | Timestamp) - Last update
• status (CommitmentStatus?) - 'pending' | 'done' | 'not-done' | 'partial'
• checkInDate (Date | Timestamp?) - When checked in
• reason (string?) - Reason if not done
• nextAction (string?) - Next action if not done
• evidenceLink (string?) - Link to PR, doc, etc.
• notes (string?) - Additional notes

Time Off

Path: orgs/{orgId}/time-off/{timeOffId}
Type: TimeOff

Fields:

• id (string?) - Time off ID
• userId (string) - User ID
• userName (string) - User display name
• orgId (string) - Organization ID
• weekStartDate (Date | Timestamp) - Monday of the week
• weekEndDate (Date | Timestamp) - Sunday of the week
• reason (string?) - Reason for time off
• createdAt (Date | Timestamp) - Creation date
• createdBy (string) - User ID who created

Scores

Path: orgs/{orgId}/scores/{userId}
Type: ScoreBreakdown

Fields:

• meetingsAttended (number) - Count of meetings attended
• achievementsEarned (number) - Count of approved achievements
• commitmentsCompleted (number) - Count of completed commitments
• meetingPoints (number) - Points from meetings (meetingsAttended * 1)
• achievementsPoints (number) - Points from achievements (achievementsEarned * 10)
• commitmentPoints (number) - Points from commitments (commitmentsCompleted * 5)
• totalScore (number) - Total score (sum of all points)
• lastCalculatedAt (Date | Timestamp) - Last calculation time

Scoring Rules:

• Each meeting attended: 1 point
• Each approved achievement: 10 points
• Each completed commitment (status='done'): 5 points

Attendance

Path: orgs/{orgId}/attendance/{userId}
Type: AttendanceStats

Fields:

• totalMeetings (number) - Total meetings in organization
• meetingsAttended (number) - Meetings member attended
• attendanceRate (number) - Attendance percentage (0-100)
• lastCalculatedAt (Date | Timestamp) - Last calculation time

Note: This is calculated hourly by the hourlyTasks cloud function.

Activity Logs

Path: orgs/{orgId}/activityLogs/{logId}
Type: OrgActivityLog

---

User Subcollections

Org Memberships

Path: usersPub/{userId}/orgMemberships/{orgId}
Type: OrgMembership

Fields:

• orgId (string) - Organization ID
• role (string) - User role in organization
• joinedAt (Date) - When user joined

---

Type Definitions

All type definitions are located in src/types/:

• src/types/organization.ts - OrganizationPrivate, OrganizationPublic, OrgActivityLog
• src/types/user.ts - User
• src/types/member.ts - Member, OrgMembership
• src/types/achievement.ts - Achievement, AchievementVote
• src/types/nomination.ts - NominationPeriod, NominationVote
• src/types/contract.ts - Contract, ContractSignature
• src/types/application.ts - Application
• src/types/commitment.ts - WeeklyCommitment
• src/types/timeOff.ts - TimeOff
• src/types/score.ts - ScoreBreakdown, MemberScore
• src/types/attendance.ts - AttendanceStats
• src/types/task.ts - Task
• src/types/team.ts - Team
• src/types/warning.ts - Warning
• src/types/vacancy.ts - Vacancy

---

Reference Functions

All Firestore reference functions are centralized in src/services/firestoreRefs.ts.

Example usage:

import { orgScoresRef, orgScoreDocRef } from '../services/firestoreRefs';

// Get collection reference
const scoresRef = orgScoresRef(orgId);

// Get document reference
const scoreRef = orgScoreDocRef(orgId, userId);

---

Best Practices

1. Always use centralized refs - Import from firestoreRefs.ts instead of hardcoding paths
2. Keep types in sync - Update types in src/types/ when adding new fields
3. Update schema - Keep firestoreSchema.ts updated when adding collections
4. Document fields - Add field descriptions in the schema file
5. Use TypeScript - Leverage type safety from the reference functions

---

Maintenance

When adding a new collection:

1. Add the type definition to src/types/
2. Add reference functions to src/services/firestoreRefs.ts
3. Update src/schema/firestoreSchema.ts with path, type, and description
4. Update this documentation file
5. Update Firestore security rules if needed