Documentation Index
Fetch the complete documentation index at: https://grantmaster.dev/llms.txt
Use this file to discover all available pages before exploring further.
Engineering reference: For service contracts, EventBus events, and data-layer details see src/features/mission/mission.md.
last_updated: 2026-03-08
Mission & Referral Program
Overview
The Mission & Referral system is a two-part feature: a Mission Impact dashboard for strategic impact alignment, and a Referral Credit program that rewards users for bringing new organizations to GrantMaster.
Architecture
The feature spans frontend components under src/features/mission/, shared services in src/shared/partnerships/ and src/shared/referrals/, and a Firebase Cloud Function trigger in functions/src/referralCreditHandler.ts.
Pages & Tabs
| Page Component | Route | Tabs |
|---|
MissionPage | /mission/:tab | Strategic Pillars, Targets, Impact Tracking |
ReferralDashboard | /referral/:tab | Overview, Refer Peers, Redeem Credits, Achievements, Activity |
PageLayout → PageHeader → PageTabs with external tab content rendering.
Referral Program
How It Works
- User shares a referral link (copy, email, QR code, WhatsApp, LinkedIn).
- A new organization signs up via the referral link.
- If the referred organization subscribes to Growth Tier or higher, the referrer earns €100 Mission Credits.
- The referred organization receives a 20% discount for one year.
- Credits can be redeemed for organization invoice discounts or gift cards (Visa, Mastercard, Amazon).
Constants
| Setting | Value |
|---|
| Default reward | €100 per Growth Tier referral |
| Minimum redemption | €50 |
| Eligible tiers | Growth, Professional, Ultimate |
| Referred org discount | 20% (expires 1 year) |
Credit Types
Mission Credits and Agent Credits are separate systems:
| Aspect | Mission Credits | Agent Credits |
|---|
| Currency | EUR (€) | Units |
| Scope | Per user | Per organization |
| Source | Referral rewards | Subscription allocation + top-ups |
| Use | Invoice discounts, gift cards | AI agent execution |
| Service | ReferralCreditService | creditService |
Tab Components
| Tab | Component | Page | Purpose |
|---|
| Overview | ReferralOverviewTab | ReferralDashboard | Credit balance, stats, impact metrics |
| Refer Peers | ReferPeersTab | ReferralDashboard | Sharing tools (link, email, QR, social) |
| Redeem Credits | RedeemCreditsTab | ReferralDashboard | Org discount or gift card redemption |
| Achievements | GamificationTab | ReferralDashboard | Badges and milestone tracking |
| Activity | ActivityHistoryTab | ReferralDashboard | Transaction and redemption log |
Backend Trigger
onEmployeeCreated (Firestore trigger in functions/src/referralCreditHandler.ts):
- Detects new employee with a pending referral-code signup.
- Validates the referred organization’s subscription tier.
- Awards €100 credit to the referrer via
awardCredit().
- Creates a referral record with status
Converted.
- Applies 20% discount to the referred organization.
- Sends Postmark emails: “Mission Credit Awarded” to referrer, “Mission Launch Welcome” to referred org admin.
SuperAdmins can also trigger manual awards via manuallyAwardReferralCredit().
Firestore Collections
| Collection | Purpose |
|---|
missionCredits | User credit wallets (keyed by userId) |
creditTransactions | Transaction log (earned / redeemed) |
creditRedemptions | Redemption records (org_discount, gift_card) |
referrals | Referral records (referrer → referred org) |
referralConfig | Program configuration (config/referralProgram) |
campaigns | Active promotional campaigns with multipliers |
Key Services
| Service | Location | Purpose |
|---|
ReferralCreditService | src/shared/partnerships/ | Wallet CRUD, award, redeem, stats |
referralDataAccess | src/shared/referrals/ | Referral record CRUD |
referralCreditHandler | functions/src/ | Cloud Function triggers and email |
Phase 2 (Planned)
ReferralCreditService includes stubs for:
transferCredits() — user-to-user credit transfercheckTieredBonuses() — escalating rewards for high-volume referrersapplyCampaignMultiplier() — promotional credit multipliersgetActiveCampaign() — retrieve current campaign configuration
