Firestore Schemas

Status	Updated	Covered Files
Complete	2026-03-14	`src/core/firestore/` (modular), `src/core/firestoreCollections.ts` (legacy re-export)

Source of truth: Collection references, typed queries, and validation helpers are now defined in the modular Firestore layer at src/core/firestore/. The legacy entry point src/core/firestoreCollections.ts re-exports from the new modules for backward compatibility.

Modular Firestore Architecture (March 2026)

The formerly monolithic firestoreCollections.ts has been decomposed into a domain-driven module structure:

src/core/firestore/
├── index.ts                       # Public API barrel export
├── references.ts                  # Re-exports from full/references.ts
├── queries.ts                     # Re-exports from full/queries.ts
├── validation.ts                  # Re-exports from full/validation.ts
├── firestoreCollections.full.ts   # Aggregates full/* modules
└── full/
    ├── references.ts              # 80+ typed collection and document reference factories
    ├── validation.ts              # getValidatedDoc(s), transformDocSnapshot, transformQuerySnapshot
    ├── queries.ts                 # Query registry aggregator (merges all domain queries)
    ├── queriesCore.ts             # Core domain: projects, users, journals, expenses, notifications, milestones
    ├── queriesImpact.ts           # M&E domain: indicators, targets, data points, dashboards, Kobo connections
    ├── queriesPlatform.ts         # Platform-level: module installations
    ├── queriesPolicy.ts           # Compliance domain: rules, templates, violations, platform rules
    └── queriesRelations.ts        # Relations domain: contacts, interactions, grantor interactions, deadlines

Import Patterns

// Recommended (new modular import):
import { collections, queries } from '@/core/firestore';

// Domain-specific (when only one domain is needed):
import { coreQueries } from '@/core/firestore/full/queriesCore';
import { impactQueries } from '@/core/firestore/full/queriesImpact';

// Legacy (still works via re-export):
import { collections, queries } from '@/core/firestoreCollections';

Key Design Characteristics

Type-safe references: collections.projects() returns CollectionReference<Project> with IDE autocomplete.
Lazy initialization: All collection factories use getDbOrThrow() to defer Firebase initialization.
Domain-split queries: 5 query modules (Core, Impact, Platform, Policy, Relations) merged into one queries object.
Runtime validation: getValidatedDoc<T>() and getValidatedDocs<T>() provide type-safe document retrieval with transformation.
Runtime architecture guards: src/core/architecture/runtimeGuards.ts can enforce import boundaries when ENFORCE_RUNTIME_ARCH_GUARDS=true.

Collection Summary Table

Root Collections (Tenant-Scoped)

All documents contain an organizationId field unless otherwise noted.

#	Collection Name	Code Alias	Firestore Path	TypeScript Type	Scope
1	Users	`users`	`employees`	`User`	Tenant
2	Projects	`projects`	`projects`	`Project`	Tenant
3	Journals	`journals`	`journals`	`JournalEntry`	Tenant
4	Expenses	`expenses`	`expenses`	`Expense`	Tenant
5	Journal Submissions	`journalSubmissions`	`journalSubmissions`	`JournalSubmission`	Tenant
6	Notifications	`notifications`	`notifications`	`Notification`	Tenant
7	Referrals	`referrals`	`referrals`	`Referral`	Tenant
8	Invitations	`invitations`	`invitations`	`Invitation`	Tenant
9	Grant Applications	`grantApplications`	`grantApplications`	`GrantApplication`	Tenant
10	Grant Pipeline	`grantPipeline`	`grantPipeline`	`GrantPipelineEntry`	Tenant
11	Active Grants	`activeGrants`	`activeGrants`	`ActiveGrant`	Tenant
12	Expense Allocations	`expenseAllocations`	`expenseAllocations`	`ExpenseAllocation`	Tenant
13	Audit Logs	`auditLogs`	`auditLogs`	`AuditLogEntry`	Tenant
14	Security Events	`securityEvents`	`securityEvents`	`SecurityEvent`	Tenant
15	System Events	`systemEvents`	`systemEvents`	`Record<string, unknown>`	Tenant
16	Deadlines	`deadlines`	`deadlines`	`Deadline`	Tenant
17	Compliance Summaries	`complianceSummaries`	`complianceSummaries`	`ComplianceSummary`	Tenant
18	Compliance Alerts	`complianceAlerts`	`complianceAlerts`	`ComplianceAlert`	Tenant

Rule Engine Collections

#	Collection Name	Code Alias	Firestore Path	TypeScript Type	Scope
19	Compliance Rules	`complianceRules` / `compliancePolicies`	`compliance_rules`	`CompliancePolicy`	Tenant
20	Rule Templates	`ruleTemplates`	`rule_templates`	`RuleTemplate`	Platform
21	Grant Rules (junction)	`grantRules`	`grant_rules`	`GrantRule`	Tenant
22	Rule Violations	`ruleViolations`	`rule_violations`	`RuleViolation`	Tenant
23	Rule Analytics	`ruleAnalytics`	`rule_analytics`	`RulePerformanceMetrics`	Tenant
24	Platform Rules	`platformRules`	`platform_rules`	`PlatformPolicy`	Platform (SuperAdmin)
25	Tenant Donor Configs	`tenantDonorConfigs`	`tenant_donor_configs`	`TenantDonorConfig`	Tenant

Relations Module Collections

#	Collection Name	Code Alias	Firestore Path	TypeScript Type	Scope
26	Contacts	`contacts`	`contacts`	`Contact`	Tenant
27	Interactions	`interactions`	`interactions`	`Interaction`	Tenant
28	Contact Views	`contactViews`	`contactViews`	`ContactView`	Tenant

Grantor Relationship Management Collections

#	Collection Name	Code Alias	Firestore Path	TypeScript Type	Scope
29	Foundations	`foundations`	`foundations`	`TaxonomyItem`	Platform
30	Grantor Interactions	`grantorInteractions`	`grantorInteractions`	`GrantorInteraction`	Tenant
31	Reporting Deadlines	`reportingDeadlines`	`reportingDeadlines`	`ReportingDeadline`	Tenant
32	Grantor Rule Conflicts	`grantorRuleConflicts`	`grantorRuleConflicts`	`GrantorRuleConflict`	Tenant

HubSpot Integration Collections

#	Collection Name	Code Alias	Firestore Path	TypeScript Type	Scope
33	HubSpot Configs	`hubspotConfigs`	`hubspotConfigs`	`HubSpotConfig`	Tenant
34	HubSpot Sync Logs	`hubspotSyncLogs`	`hubspotSyncLogs`	`HubSpotSyncLog`	Tenant

Stakeholder Portal Collections

#	Collection Name	Code Alias	Firestore Path	TypeScript Type	Scope
35	Portal Tokens	`portalTokens`	`portalTokens`	`PortalToken`	Tenant
36	Portal Sessions	`portalSessions`	`portalSessions`	`PortalSession`	Tenant
37	Portal Comments	`portalComments`	`portalComments`	`PortalComment`	Tenant
38	Portal Report Acks	`portalReportAcknowledgments`	`portalReportAcknowledgments`	`PortalReportAcknowledgment`	Tenant

Mission Credits & Gamification Collections

#	Collection Name	Code Alias	Firestore Path	TypeScript Type	Scope
39	Mission Credits	`missionCredits`	`missionCredits`	`MissionCredit`	Per-user wallet
40	Credit Transactions	`creditTransactions`	`creditTransactions`	`CreditTransaction`	Tenant
41	Credit Redemptions	`creditRedemptions`	`creditRedemptions`	`CreditRedemption`	Tenant
42	Badges	`badges`	`badges`	`Badge`	Tenant
43	Gamification Prefs	`gamificationPreferences`	`gamificationPreferences`	`GamificationPreferences`	Per-user
44	Campaigns	`campaigns`	`campaigns`	`Campaign`	Platform / Tenant

Impact / Monitoring & Evaluation Collections

#	Collection Name	Code Alias	Firestore Path	TypeScript Type	Scope
45	ME Indicators	`meIndicators`	`meIndicators`	`MEIndicator`	Tenant + Project
46	ME Indicator Targets	`meIndicatorTargets`	`meIndicatorTargets`	`MEIndicatorTarget`	Tenant + Project
47	ME Data Points	`meDataPoints`	`meDataPoints`	`MEIndicatorDataPoint`	Tenant + Project
48	ME Dashboard Configs	`meDashboardConfigs`	`meDashboardConfigs`	`MEDashboardConfig`	Tenant + Project
49	ME Kobo Connections	`meKoboConnections`	`meKoboConnections`	`MEKoboConnection`	Tenant
50	ME Kobo Form Links	`meKoboFormLinks`	`meKoboFormLinks`	`MEKoboFormLink`	Tenant + Project
51	ME Indicator Summaries	`meIndicatorSummaries`	`meIndicatorSummaries`	`MEIndicatorSummary`	Tenant (read-only)
52	ME Grant Indicator Configs	`meGrantIndicatorConfigs`	`meGrantIndicatorConfigs`	`MEGrantIndicatorConfig`	Tenant
53	ME AI Suggestions	`meAISuggestions`	`meAISuggestions`	`AIIndicatorSuggestion`	Tenant + Project
54	ME Workflow Rules	`meWorkflowRules`	`meWorkflowRules`	`MEWorkflowRule`	Tenant
55	ME Workflow Exec Logs	`meWorkflowExecutionLogs`	`meWorkflowExecutionLogs`	`MEWorkflowExecutionLog`	Tenant
56	ME Org Settings	`meSettings`	`meSettings`	`MEOrgSettings`	Tenant (1 doc/org)

Taxonomy Collections

#	Collection Name	Code Alias	Firestore Path	TypeScript Type	Scope
57	Budget Categories	`budgetCategories`	`budgetCategories`	`BudgetCategory`	Tenant
58	Mission Pillars	`missionPillars`	`missionPillars`	`MissionPillar`	Tenant
59	Donors	`donors`	`donors`	`TaxonomyItem`	Tenant

Platform Management Collections (SuperAdmin)

#	Collection Name	Code Alias	Firestore Path	TypeScript Type	Scope
60	Imuseration Sessions	`imuserationSessions`	`imuserationSessions`	`ImuserationSession`	Platform
61	Auditor Access Grants	`auditorAccessGrants`	`auditorAccessGrants`	`AuditorAccessGrant`	Tenant
62	Config Snapshots	`configSnapshots`	`configSnapshots`	`ConfigurationSnapshot`	Tenant
63	Audit Export Jobs	`auditExportJobs`	`auditExportJobs`	`AuditExportJob`	Tenant
64	Platform Metrics	`platformMetrics`	`platformMetrics`	`PlatformMetrics`	Platform
65	User Growth Metrics	`userGrowthMetrics`	`userGrowthMetrics`	`UserGrowthMetrics`	Platform
66	Retention Cohorts	`retentionCohorts`	`retentionCohorts`	`RetentionCohort`	Platform
67	Organization Metrics	`organizationMetrics`	`organizationMetrics`	`OrganizationMetrics`	Platform
68	Auditor Reports	`auditorReports`	`auditorReports`	`AuditorReport`	Tenant

Platform-Wide & Config Collections

#	Collection Name	Code Alias	Firestore Path	TypeScript Type	Scope
69	Grant Opportunities	`grantOpportunities`	`grantOpportunities`	`GrantOpportunity`	Platform
70	Organizations	`organizations`	`organizations`	`Organization`	Platform
71	Config	`config`	`config`	mixed	Platform

Visual Collection Hierarchy

Root Collections (Tenant-Scoped) — Detail

All documents in these collections MUST contain an organizationId field for security-rule scoping.

1. Users (`employees`)

Field	Type	Description
`id`	string	Firebase Auth UID
`organizationId`	string	Tenant FK
`status`	`UserStatus`	ACTIVE, INACTIVE, etc.
`firstName`, `lastName`	string	Display name parts
`email`	string	Login email
`role`	string	Primary RBAC role

Name-mapping gotcha: The Firestore collection is employees but stores User documents.

2. Projects (`projects`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`phase`	`ProjectPhase`	Current lifecycle phase
`isArchived`	boolean	Soft-delete flag

3. Journals (`journals`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`userId`	string	Author
`projectId`	string	Linked project

Name-mapping gotcha: The Firestore collection is journals but stores JournalEntry documents.

4. Expenses (`expenses`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`userId`	string	Submitter
`projectId`	string	Linked project

5. Journal Submissions (`journalSubmissions`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`userId`	string	Author

Name-mapping gotcha: journalSubmissions is the canonical collection for JournalSubmission documents.

6. Notifications (`notifications`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`recipientId`	string	Target user
`isRead`	boolean	Read state

7. Referrals (`referrals`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`referrerId`	string	User who referred
`refereeEmail`	string	Invitee email
`status`	`ReferralStatus`	pending / converted / etc.
`creditAwarded`	boolean?	Mission Credit tracking

8. Invitations (`invitations`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`token`	string	Unique invite token
`email`	string	Invitee email
`status`	`InvitationStatus`	pending / accepted / expired
`expiresAt`	string	ISO timestamp

9. Grant Applications (`grantApplications`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK

10. Grant Pipeline (`grantPipeline`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK

11. Active Grants (`activeGrants`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK

12. Expense Allocations (`expenseAllocations`)

Field	Type	Description
`id`	string	Auto-generated
`grantId`	string	FK to `activeGrants`
`expenseId`	string	FK to `expenses`
`budgetLineId`	string	FK to budget line item
`amount`	number	Allocated amount
`allocatedBy`	string	User ID

13. Audit Logs (`auditLogs`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK

14. Security Events (`securityEvents`)

Field	Type	Description
`id`	string	Auto-generated
`type`	string	`failed_login`, `suspicious_login`, `unusual_access`, etc.
`userId`	string?	Affected user
`severity`	string	`info` / `warning` / `critical`
`ipAddress`	string	Source IP
`resolved`	boolean	Resolution state

15. System Events (`systemEvents`)

Generic event collection for Novu notification triggers. No fixed schema (Record<string, unknown>).

16. Deadlines (`deadlines`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`type`	`DeadlineType`	project_end, report_due, etc.
`title`	string	Human-readable title
`dueDate`	string	ISO date
`projectId`	string?	Optional project link
`assignedTo`	string[]?	User IDs
`priority`	`DeadlinePriority`	low / medium / high / critical
`status`	`DeadlineStatus`	upcoming / due_soon / overdue / completed / cancelled

17. Compliance Summaries (`complianceSummaries`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`periodStart`	string	Start of reporting period
`periodEnd`	string	End of reporting period
`overall.status`	`ComplianceStatus`	Aggregated status
`overall.score`	number	0-100 score
`overall.riskLevel`	`RiskLevel`	low / medium / high

18. Compliance Alerts (`complianceAlerts`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`type`	string	`journal` / `expense` / `report` / `budget`
`severity`	`RiskLevel`	low / medium / high
`status`	string	`active` / `acknowledged` / `resolved`
`title`	string	Alert title
`resourceId`	string	FK to triggering entity

Hierarchical Collections (Subcollections)

Organization Sub-structure

Path: organizations/{orgId}/

Subcollection	Firestore Path	TypeScript Type	Purpose
Config	`config`	`AppSettings`	App settings & secrets
API Keys	`apiKeys`	`ApiKey`	External integration keys
Webhooks	`webhooks`	`WebhookConfig`	Outgoing event configs
Integrations	`integrations`	`IntegrationRecord`	Sync state with external apps
Compliance Summaries	`complianceSummaries`	`ComplianceSummary`	Org-level compliance rollups
Compliance Alerts	`complianceAlerts`	`ComplianceAlert`	Org-level compliance alerts
Submission Metrics	`submissionMetrics`	`SubmissionMetrics`	Aggregated submission stats
Onboarding	`onboarding`	`OrganizationOnboardingChecklist`	Org setup wizard state

Project Sub-structure

Path: projects/{projectId}/

Subcollection	Firestore Path	TypeScript Type	Purpose
Document Chunks	`documentChunks`	`DocumentChunk`	RAG system text chunks
Processed Documents	`processedDocuments`	`ProcessedDocument`	File processing metadata
Compliance Rules	`complianceRules`	`CompliancePolicy`	Project-specific constraints
AI Processing Logs	`aiProcessingLogs`	`AIProcessingLog`	Genkit processing audit trail
Budget Forecasts	`budgetForecasts`	`BudgetForecast`	Financial projections
Budget Alerts	`budgetAlerts`	`BudgetAlert`	Budget threshold warnings

Grant Pipeline Sub-structure

Path: grantPipeline/{pipelineId}/

Subcollection	Firestore Path	TypeScript Type	Purpose
Tasks	`tasks`	`PipelineTask`	To-dos for a proposal
Documents	`documents`	`PipelineDocument`	Supporting files/drafts
Activities	`activities`	`PipelineActivity`	Timeline/Comment log

Rule Engine Collections

The Rule Engine supports a two-tier compliance system: platform-wide rules managed by SuperAdmins, and tenant-level rules that organizations can customize.

19. Compliance Rules / Policies (`compliance_rules`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK (`platform_default` for built-in rules)
`projectId`	string?	Optional project scope
`code`	string?	Rule code (e.g., `F-01`)
`title`	string?	Short name
`category`	`CompliancePolicyCategory`	financial, reporting, procurement, etc.
`policy`	string	Natural language description
`severity`	`CompliancePolicySeverity`	Severity level
`policyStatus`	string	`active` / `draft` / `archived`
`isCustom`	boolean	Whether custom or adopted from platform
`donorTypes`	`GrantorType[]`	Applicable donor types

The code aliases complianceRules and compliancePolicies both point to the same compliance_rules Firestore path.

20. Rule Templates (`rule_templates`)

Field	Type	Description
`id`	string	Auto-generated
`donorType`	`GrantorType`	Target donor type
`isPublic`	boolean	Whether visible to tenants

Platform-wide donor profile templates that organizations can adopt.

21. Grant Rules — Junction Table (`grant_rules`)

Field	Type	Description
`id`	string	Auto-generated
`projectId`	string	FK to `projects`
`isActive`	boolean	Whether the rule-grant link is active

Tracks which compliance rules apply to which grants/projects.

22. Rule Violations (`rule_violations`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`projectId`	string	FK to `projects`
`status`	string	`active` / `resolved`

Detected violations of compliance rules.

23. Rule Analytics (`rule_analytics`)

Field	Type	Description
`id`	string	Auto-generated

Performance metrics for rule evaluation (execution time, violation rates, etc.).

24. Platform Rules (`platform_rules`)

Field	Type	Description
`id`	string	Auto-generated
`code`	string?	Rule code
`title`	string?	Short name
`policy`	string	Natural language description
`category`	`CompliancePolicyCategory`	Category
`severity`	`CompliancePolicySeverity`	Severity
`policyStatus`	`PolicyStatus`	ACTIVE / DRAFT / ARCHIVED
`isPublic`	boolean	Whether visible to tenants
`donorTypes`	`GrantorType[]`	Applicable donor types
`frequency`	`PolicyFrequency`	How often to evaluate
`automationPotential`	`PolicyAutomationPotential`	Automation level

No organizationId — these are SuperAdmin-managed, platform-wide.

25. Tenant Donor Configs (`tenant_donor_configs`)

Field	Type	Description
`id`	string	Same as `organizationId`

Tracks donor types an organization works with and rule recommendations. One document per organization.

Relations Module Collections

26. Contacts (`contacts`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`recordType`	`ContactRecordType`	PERSON / ORGANIZATION
`displayName`	string	Primary display name
`email`	string?	Email address
`relationshipGroups`	`RelationshipGroup[]`	Tags: donor, partner, etc.
`owner`	string?	Assigned user ID

27. Interactions (`interactions`)

Field	Type	Description
`id`	string	Auto-generated
`contactId`	string	FK to `contacts`
`organizationId`	string	Tenant FK
`type`	`InteractionType`	call, email, meeting, note, etc.
`title`	string	Summary
`timestamp`	string	ISO timestamp
`createdBy`	string	User ID
`hubspotSyncStatus`	object?	HubSpot engagement sync state

28. Contact Views (`contactViews`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`name`	string	View name
`createdBy`	string	Owner user ID
`isDefault`	boolean	Default view flag
`filters`	object	Saved filter criteria

Grantor Relationship Management Collections

29. Foundations (`foundations`)

Field	Type	Description
`id`	string	Auto-generated

Global registry of grant-making bodies. Typed as TaxonomyItem. Shared across tenants.

30. Grantor Interactions (`grantorInteractions`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`grantorId`	string	FK to `foundations`
`grantorName`	string	Denormalized name
`contactId`	string?	Optional FK to `contacts`
`type`	`InteractionType`	call, email, meeting, etc.
`direction`	string	`inbound` / `outbound`
`subject`	string	Interaction subject
`summary`	string	Description
`sentiment`	`InteractionSentiment`?	positive / neutral / negative
`followUpDate`	string?	Next follow-up ISO date
`followUpCompleted`	boolean	Follow-up tracking

31. Reporting Deadlines (`reportingDeadlines`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`grantorId`	string	FK to `foundations`
`grantorName`	string	Denormalized name
`projectId`	string?	Optional project scope
`title`	string	Deadline title
`dueDate`	string	ISO date
`status`	`ReportingDeadlineStatus`	upcoming / due-soon / overdue / completed / cancelled

32. Grantor Rule Conflicts (`grantorRuleConflicts`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`projectId`	string	FK to `projects`
`projectName`	string	Denormalized
`ruleCategory`	`ComplianceMatrixCategory`	Category of conflicting rule
`ruleName`	string	Rule name
`status`	string	`active` / `resolved`
`grantors`	array	List of conflicting grantors with their values

HubSpot Integration Collections

33. HubSpot Configs (`hubspotConfigs`)

Field	Type	Description
`id`	string	Same as `organizationId`
`organizationId`	string	Tenant FK
`accessToken`	string	OAuth access token (encrypted at rest)
`refreshToken`	string	OAuth refresh token
`expiresAt`	string	Token expiry ISO timestamp
`portalId`	string	HubSpot account ID
`connectedBy`	string	User who connected

One document per organization.

34. HubSpot Sync Logs (`hubspotSyncLogs`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`syncType`	`HubSpotSyncType`	Type of sync operation
`direction`	string	`to_hubspot` / `from_hubspot`
`triggeredBy`	`HubSpotSyncTrigger`	manual / webhook / scheduled
`startedAt`	string	ISO timestamp
`status`	`HubSpotSyncStatus`	Status of the sync
`totalRecords`	number	Records processed
`successCount`	number	Successful records

Stakeholder Portal Collections

35. Portal Tokens (`portalTokens`)

Field	Type	Description
`id`	string	Crypto-random 32-char token (also document ID)
`organizationId`	string	Tenant FK
`projectId`	string	Project being shared
`createdBy`	string	User who created the link
`stakeholderName`	string	Display name for the stakeholder
`expiresAt`	string?	Optional expiry
`permissions`	object	Granular access flags

36. Portal Sessions (`portalSessions`)

Field	Type	Description
`id`	string	Auto-generated
`tokenId`	string	FK to `portalTokens`
`organizationId`	string	Tenant FK
`projectId`	string	Project being viewed
`startedAt`	string	Session start ISO timestamp
`ipAddress`	string	Accessor IP

Audit trail for stakeholder access events.

37. Portal Comments (`portalComments`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`projectId`	string	Project being discussed
`tokenId`	string?	Token ID if posted by stakeholder
`authorType`	string	`organization` / `stakeholder`
`authorName`	string	Display name

38. Portal Report Acknowledgments (`portalReportAcknowledgments`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`projectId`	string	Project the report belongs to
`reportId`	string	FK to generated report
`tokenId`	string	Token used to acknowledge
`status`	`ReportAcknowledgmentStatus`	Acknowledgment status
`stakeholderName`	string	Who acknowledged

Mission Credits & Gamification Collections

39. Mission Credits (`missionCredits`)

Field	Type	Description
`id`	string	Same as `userId` (one wallet per user)
`userId`	string	FK to `employees`
`organizationId`	string	Tenant FK
`balance`	number	Current credit balance (EUR)
`totalEarned`	number	Lifetime total earned
`totalRedeemed`	number	Lifetime total redeemed
`referralCount`	number	Successful referrals count

40. Credit Transactions (`creditTransactions`)

Field	Type	Description
`id`	string	Auto-generated
`userId`	string	FK to `employees`
`organizationId`	string	Tenant FK
`type`	`CreditTransactionType`	earn / redeem / adjustment
`amount`	number	Positive for earn, negative for redeem
`balanceBefore`	number	Balance before transaction
`balanceAfter`	number	Balance after transaction
`referralId`	string?	If earned via referral
`redemptionId`	string?	If redeemed

41. Credit Redemptions (`creditRedemptions`)

Field	Type	Description
`id`	string	Auto-generated
`userId`	string	FK to `employees`
`organizationId`	string	Tenant FK
`redemptionType`	`RedemptionType`	gift_card / org_discount / etc.
`amount`	number	Credits spent
`status`	`RedemptionStatus`	pending / processing / completed / failed
`giftCardType`	`GiftCardType`?	If gift card redemption

42. Badges (`badges`)

Field	Type	Description
`id`	string	Auto-generated
`userId`	string	FK to `employees`
`organizationId`	string	Tenant FK
`achievementType`	`AchievementType`	Badge category
`name`	string	Badge display name
`icon`	string	Emoji or icon identifier
`earnedAt`	string	ISO timestamp

43. Gamification Preferences (`gamificationPreferences`)

Field	Type	Description
`id`	string	Same as `userId` (one doc per user)

User opt-in/out preferences for gamification features.

44. Campaigns (`campaigns`)

Field	Type	Description
`id`	string	Auto-generated
`name`	string	Campaign name
`multiplier`	number	Credit multiplier (e.g., 2 for double)
`startDate`	string	ISO date
`endDate`	string	ISO date
`active`	boolean	Active flag
`organizationId`	string?	If org-specific; omit for platform-wide
`createdBy`	string	User ID

Impact / Monitoring & Evaluation Collections

45. ME Indicators (`meIndicators`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`projectId`	string \| null	`null` = org-level library template
`code`	string	Short code (e.g., `OUT-1`)
`name`	string	Indicator name
`type`	`IndicatorType`	output / outcome / impact
`unit`	string	Measurement unit
`direction`	`IndicatorDirection`	increase / decrease / maintain
`frequency`	`ReportingFrequency`	monthly / quarterly / annual
`dataSource`	string	Where data comes from
`isArchived`	boolean	Soft-delete flag
`disaggregations`	`DisaggregationDimension[]`	Gender, age, etc.
`tags`	string[]	Classification tags

46. ME Indicator Targets (`meIndicatorTargets`)

Field	Type	Description
`id`	string	Auto-generated
`indicatorId`	string	FK to `meIndicators`
`organizationId`	string	Tenant FK
`projectId`	string	FK to `projects`
`periodLabel`	string	Human-readable period name
`periodStart`	string	ISO date
`periodEnd`	string	ISO date
`targetValue`	number	Target value for the period

47. ME Data Points (`meDataPoints`)

Field	Type	Description
`id`	string	Auto-generated
`indicatorId`	string	FK to `meIndicators`
`organizationId`	string	Tenant FK
`projectId`	string	FK to `projects`
`periodStart`	string	ISO date
`periodEnd`	string	ISO date
`value`	number	Reported value
`disaggregationValues`	object	Breakdown by dimension
`source`	`DataPointSource`	manual / kobo / import
`approvalStatus`	`DataPointApprovalStatus`	draft / submitted / approved / rejected
`submittedBy`	string?	User ID
`approvedBy`	string?	User ID

48. ME Dashboard Configs (`meDashboardConfigs`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`projectId`	string	FK to `projects`
`keyIndicatorIds`	string[]	Pinned indicators
`narrative`	string	Dashboard narrative text

One document per project.

49. ME Kobo Connections (`meKoboConnections`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`label`	string	Connection label
`serverUrl`	string	KoboToolbox server URL
`apiToken`	string	API token (encrypted at rest)
`isActive`	boolean	Active flag
`lastSyncAt`	string?	Last successful sync

50. ME Kobo Form Links (`meKoboFormLinks`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`projectId`	string	FK to `projects`
`connectionId`	string	FK to `meKoboConnections`
`koboFormId`	string	KoboToolbox form ID
`koboFormName`	string	Form display name
`indicatorMappings`	array	Maps Kobo questions to indicators
`syncEnabled`	boolean	Auto-sync toggle

51. ME Indicator Summaries (`meIndicatorSummaries`)

Field	Type	Description
`id`	string	Deterministic: `${indicatorId}_${periodStart}`
`organizationId`	string	Tenant FK
`projectId`	string	FK to `projects`
`indicatorId`	string	FK to `meIndicators`
`approvedValue`	number?	Aggregated approved value
`targetValue`	number?	Denormalized target
`totalDataPoints`	number	Count of data points

Read-only on client — written by Cloud Functions aggregation pipeline.

52. ME Grant Indicator Configs (`meGrantIndicatorConfigs`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`projectId`	string	FK to `projects`
`grantId`	string	FK to `activeGrants`
`indicatorId`	string	FK to `meIndicators`
`grantTargetValue`	number?	Per-grant target
`weight`	number	0-1 for weighted scoring
`reportingRequired`	boolean	Whether donor requires reporting
`donorIndicatorCode`	string?	Donor’s own code
`sdgAlignments`	`SDGAlignment[]`	SDG mapping

53. ME AI Suggestions (`meAISuggestions`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`projectId`	string	FK to `projects`
`grantId`	string?	Optional grant context
`suggestedName`	string	AI-suggested indicator name
`suggestedCode`	string	AI-suggested code
`rationale`	string	AI explanation
`status`	`AIIndicatorSuggestionStatus`	pending / accepted / dismissed
`acceptedIndicatorId`	string?	FK to created indicator

54. ME Workflow Rules (`meWorkflowRules`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`name`	string	Rule name
`isActive`	boolean	Active toggle
`triggerType`	`WorkflowTriggerType`	event / schedule / threshold
`triggerSchedule`	string?	Cron expression
`conditions`	`WorkflowCondition[]`	AND conditions
`actions`	`WorkflowAction[]`	Executed in order
`triggerCount`	number	Lifetime trigger count

55. ME Workflow Execution Logs (`meWorkflowExecutionLogs`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`ruleId`	string	FK to `meWorkflowRules`
`ruleName`	string	Denormalized rule name
`triggerType`	string	What triggered execution
`conditionsMatched`	boolean	Whether conditions passed
`actionsExecuted`	array	Actions that ran
`actionResults`	array	Success/failure per action
`executedAt`	string	ISO timestamp

56. ME Org Settings (`meSettings`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`defaultReportingFrequency`	`ReportingFrequency`	Default for new indicators
`requireDataApproval`	boolean	Enable approval workflow
`notifyOnSubmission`	boolean	Notification preference
`notifyOnAnomaly`	boolean	Anomaly alert toggle
`koboAutoSyncFrequency`	string	`hourly` / `daily` / `weekly`

One document per organization.

Taxonomy Collections

57. Budget Categories (`budgetCategories`)

Global taxonomy collection typed as BudgetCategory.

58. Mission Pillars (`missionPillars`)

Global taxonomy collection typed as MissionPillar.

59. Donors (`donors`)

Legacy taxonomy collection typed as TaxonomyItem. May overlap with settings-based donor configuration.

Platform Management Collections (SuperAdmin)

60. Imuseration Sessions (`imuserationSessions`)

Field	Type	Description
`id`	string	Auto-generated
`superAdminId`	string	The SuperAdmin user ID
`targetOrganizationId`	string	Org being imuserated into
`reason`	string	Required justification
`startedAt`	string	ISO timestamp
`isActive`	boolean	Active session flag
`ipAddress`	string	Source IP

61. Auditor Access Grants (`auditorAccessGrants`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`auditorId`	string	User ID with AUDITOR role
`grantedBy`	string	Admin who granted access
`grantedAt`	string	ISO timestamp
`expiresAt`	string	Access expiry
`scope`	string	`full` / `limited`
`limitedToProjectIds`	string[]?	If limited scope

62. Config Snapshots (`configSnapshots`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`createdBy`	string	Auditor ID
`snapshotType`	string	`manual` / `scheduled` / `pre_audit`
`snapshot`	object	Captured configuration state

63. Audit Export Jobs (`auditExportJobs`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`requestedBy`	string	Auditor or Admin ID
`status`	string	`pending` / `processing` / `completed` / `failed`
`format`	string	`csv` / `json` / `pdf`
`filters`	object	Date range, user IDs, actions, etc.

64. Platform Metrics (`platformMetrics`)

Field	Type	Description
`timestamp`	string	Snapshot timestamp
`totalUsers`	number	Platform-wide total
`activeUsers`	number	Active in last 30 days
`totalOrganizations`	number	Total tenants
`totalProjects`	number	Total across all tenants

65. User Growth Metrics (`userGrowthMetrics`)

Field	Type	Description
`period`	string	YYYY-MM format
`newUsers`	number	New signups
`activeUsers`	number	Active during period
`churnedUsers`	number	Lost users
`retentionRate`	number	Percentage
`growthRate`	number	% change from previous period

66. Retention Cohorts (`retentionCohorts`)

Field	Type	Description
`cohortMonth`	string	YYYY-MM when users joined
`totalUsers`	number	Cohort size
`retentionByMonth`	object	Retention at month 1, 2, 3, 6, 12

67. Organization Metrics (`organizationMetrics`)

Field	Type	Description
`organizationId`	string	Tenant FK
`organizationName`	string	Display name
`subscriptionTier`	`SubscriptionTier`	Current plan
`totalUsers`	number	User count
`healthScore`	number	0-100
`riskLevel`	string	Churn risk: low / medium / high

68. Auditor Reports (`auditorReports`)

Field	Type	Description
`id`	string	Auto-generated
`organizationId`	string	Tenant FK
`projectId`	string?	Optional project scope
`generatedBy`	string	User ID
`reportType`	string	`activity_eligibility`, `category_compliance`, `staff_allocation`, `objective_alignment`

Platform-Wide & Config Collections

69. Grant Opportunities (`grantOpportunities`)

Field	Type	Description
`id`	string	Auto-generated

Platform-wide marketplace / external grant library. No organizationId.

70. Organizations (`organizations`)

Field	Type	Description
`id`	string	Auto-generated (tenant ID)

Root-level tenant documents. Parent for organization subcollections.

71. Config (`config`)

Global platform settings. Contains singleton documents:

Document ID	Type	Purpose
`referralProgram`	`ReferralProgramConfig`	Referral program settings
`roles`	`{ defaultRoles: Role[] }`	Default RBAC roles

Subcollection: config/security/policies — SecurityPolicy documents.

Name-Mapping Gotchas

These collections have Firestore path names that differ from their logical domain:

Logical Domain	Code Alias	Actual Firestore Path	TypeScript Type
Users	`users`	`employees`	`User`
Journals (time tracking)	`journals`	`journals`	`JournalEntry`
Journal Submissions	`journalSubmissions`	`journalSubmissions`	`JournalSubmission`

Storage Structure (Cloud Storage)

Standardized folder structure for binary files:

tenants/{orgId}/users/{userId}/avatar: Profile pictures.
tenants/{orgId}/projects/{projectId}/docs: Project-specific files.
tenants/{orgId}/grants/{grantId}/contracts: Legal documentation.
tenants/{orgId}/expenses/{expenseId}/receipts: Proof of spend.

Maintenance

Update this document when:

Creating a new directory in src/features.
Adding a new collection() call in src/core/firestoreCollections.ts.
Changing the Firestore Security Rules (firestore.rules).

Update Checklist

Add collection to src/core/firestoreCollections.ts.
Update this Markdown file with the new entry.
Verify organizationId is present in the document type definition.

Get Started

Product — Domain Model

Product — Workflows

Product — Features

Product — Extensions

Product — User Guides

Product — Launch & Pricing

Engineering — Architecture

Engineering — Data

Engineering — Frontend

Engineering — Security

Engineering — Testing

Engineering — Guides

Contributing

Marketing

Documentation Index

​Firestore Schemas

​Modular Firestore Architecture (March 2026)

​Import Patterns

​Key Design Characteristics

​Collection Summary Table

​Root Collections (Tenant-Scoped)

​Rule Engine Collections

​Relations Module Collections

​Grantor Relationship Management Collections

​HubSpot Integration Collections

​Stakeholder Portal Collections

​Mission Credits & Gamification Collections

​Impact / Monitoring & Evaluation Collections

​Taxonomy Collections

​Platform Management Collections (SuperAdmin)

​Platform-Wide & Config Collections

​Visual Collection Hierarchy

​Root Collections (Tenant-Scoped) — Detail

​1. Users (employees)

​2. Projects (projects)

​3. Journals (journals)

​4. Expenses (expenses)

​5. Journal Submissions (journalSubmissions)

​6. Notifications (notifications)

​7. Referrals (referrals)

​8. Invitations (invitations)

​9. Grant Applications (grantApplications)

​10. Grant Pipeline (grantPipeline)

​11. Active Grants (activeGrants)

​12. Expense Allocations (expenseAllocations)

​13. Audit Logs (auditLogs)

​14. Security Events (securityEvents)

​15. System Events (systemEvents)

​16. Deadlines (deadlines)

​17. Compliance Summaries (complianceSummaries)

​18. Compliance Alerts (complianceAlerts)

​Hierarchical Collections (Subcollections)

​Organization Sub-structure

​Project Sub-structure

​Grant Pipeline Sub-structure

​Rule Engine Collections

​19. Compliance Rules / Policies (compliance_rules)

​20. Rule Templates (rule_templates)

​21. Grant Rules — Junction Table (grant_rules)

​22. Rule Violations (rule_violations)

​23. Rule Analytics (rule_analytics)

​24. Platform Rules (platform_rules)

​25. Tenant Donor Configs (tenant_donor_configs)

​Relations Module Collections

​26. Contacts (contacts)

​27. Interactions (interactions)

​28. Contact Views (contactViews)

​Grantor Relationship Management Collections

​29. Foundations (foundations)

​30. Grantor Interactions (grantorInteractions)

​31. Reporting Deadlines (reportingDeadlines)

​32. Grantor Rule Conflicts (grantorRuleConflicts)

​HubSpot Integration Collections

​33. HubSpot Configs (hubspotConfigs)

​34. HubSpot Sync Logs (hubspotSyncLogs)

​Stakeholder Portal Collections

​35. Portal Tokens (portalTokens)

​36. Portal Sessions (portalSessions)

​37. Portal Comments (portalComments)

Firestore Schemas

Modular Firestore Architecture (March 2026)

Import Patterns

Key Design Characteristics

Collection Summary Table

Root Collections (Tenant-Scoped)

Rule Engine Collections

Relations Module Collections

Grantor Relationship Management Collections

HubSpot Integration Collections

Stakeholder Portal Collections

Mission Credits & Gamification Collections

Impact / Monitoring & Evaluation Collections

Taxonomy Collections

Platform Management Collections (SuperAdmin)

Platform-Wide & Config Collections

Visual Collection Hierarchy

Root Collections (Tenant-Scoped) — Detail

1. Users (`employees`)

2. Projects (`projects`)

3. Journals (`journals`)

4. Expenses (`expenses`)

5. Journal Submissions (`journalSubmissions`)

6. Notifications (`notifications`)

7. Referrals (`referrals`)

8. Invitations (`invitations`)

9. Grant Applications (`grantApplications`)

10. Grant Pipeline (`grantPipeline`)

11. Active Grants (`activeGrants`)

12. Expense Allocations (`expenseAllocations`)

13. Audit Logs (`auditLogs`)

14. Security Events (`securityEvents`)

15. System Events (`systemEvents`)

16. Deadlines (`deadlines`)

17. Compliance Summaries (`complianceSummaries`)

18. Compliance Alerts (`complianceAlerts`)

Hierarchical Collections (Subcollections)

Organization Sub-structure

Project Sub-structure

Grant Pipeline Sub-structure

Rule Engine Collections

19. Compliance Rules / Policies (`compliance_rules`)

20. Rule Templates (`rule_templates`)

21. Grant Rules — Junction Table (`grant_rules`)

22. Rule Violations (`rule_violations`)

23. Rule Analytics (`rule_analytics`)

24. Platform Rules (`platform_rules`)

25. Tenant Donor Configs (`tenant_donor_configs`)

Relations Module Collections

26. Contacts (`contacts`)

27. Interactions (`interactions`)

28. Contact Views (`contactViews`)

Grantor Relationship Management Collections

29. Foundations (`foundations`)

30. Grantor Interactions (`grantorInteractions`)

31. Reporting Deadlines (`reportingDeadlines`)

32. Grantor Rule Conflicts (`grantorRuleConflicts`)

HubSpot Integration Collections

33. HubSpot Configs (`hubspotConfigs`)

34. HubSpot Sync Logs (`hubspotSyncLogs`)

Stakeholder Portal Collections

35. Portal Tokens (`portalTokens`)

36. Portal Sessions (`portalSessions`)

37. Portal Comments (`portalComments`)

38. Portal Report Acknowledgments (`portalReportAcknowledgments`)

Mission Credits & Gamification Collections

39. Mission Credits (`missionCredits`)

40. Credit Transactions (`creditTransactions`)

41. Credit Redemptions (`creditRedemptions`)

42. Badges (`badges`)

43. Gamification Preferences (`gamificationPreferences`)

44. Campaigns (`campaigns`)

Impact / Monitoring & Evaluation Collections

45. ME Indicators (`meIndicators`)

46. ME Indicator Targets (`meIndicatorTargets`)

47. ME Data Points (`meDataPoints`)

48. ME Dashboard Configs (`meDashboardConfigs`)

49. ME Kobo Connections (`meKoboConnections`)

50. ME Kobo Form Links (`meKoboFormLinks`)

51. ME Indicator Summaries (`meIndicatorSummaries`)