Documentation Index
Fetch the complete documentation index at: https://grantmaster.dev/llms.txt
Use this file to discover all available pages before exploring further.
Credit & Entitlement Model
| Status | Updated | Covered Files |
|---|
| 🟢 Stable | 2026-02-21 | config/entitlements.ts, types/usageTracking.ts, features/billing/services/creditService.ts, shared/billing/QuotaService.ts |
Overview
The credit and entitlement model controls what organizations can do and how much they can consume. It has two layers:
- Entitlements — Feature gates and tier limits (what you can do)
- Credits — Consumable units for agent operations (how much you can do)
Subscription Tiers
GrantMaster has three subscription tiers, each cascading all features from the tier below:
POTENTIAL ──▶ PROFESSIONAL ──▶ ULTIMATE
(base) (+ advanced) (+ enterprise)
SubscriptionTier enum and stored on each organization’s subscription.tier field.
Feature Enum
File: src/config/entitlements.ts
The Feature enum defines all gated capabilities. Features are grouped by category:
Basic Features (Potential tier)
| Feature | Description |
|---|
BASIC_JOURNALS | Track time on projects and activities |
BASIC_REPORTS | Generate standard reports |
BASIC_PROJECTS | Manage projects and budgets |
TEAM_COLLABORATION | Collaborate with your team |
DOCUMENT_UPLOADS | Upload and manage documents |
Professional Features
| Feature | Description |
|---|
AI_GENERATION | AI-powered content generation |
AI_JOURNAL_SUBMISSION | Generate journal entries from natural language |
AI_REPORT_GENERATION | Generate reports with AI assistance |
API_ACCESS | Programmatic access to your data |
ADVANCED_REPORTS | Create custom reports with advanced filters |
CUSTOM_EXPORTS | Export data in multiple formats |
BUDGET_FORECASTING | Predict budget utilization |
EXPENSE_MANAGEMENT | Track and approve expenses |
GRANT_DISCOVERY | Discover relevant grant opportunities |
ADVANCED_STORAGE | Increased storage capacity |
RAG_DOCUMENT_SEARCH | AI-powered document search |
ADVANCED_ANALYTICS | Deep insights and analytics |
AGENT_BASIC | Run single-step AI agent tasks |
AGENT_MULTI_STEP | Run multi-step AI agent workflows |
IMPACT_MODULE | Monitor & evaluate program outcomes |
Ultimate Features
| Feature | Description |
|---|
SSO | Single Sign-On authentication |
ADVANCED_SSO | Advanced SSO with multiple providers |
SAML_SSO | SAML-based Single Sign-On |
AUDIT_LOGS | Complete audit trail of all actions |
CUSTOM_INTEGRATIONS | Build custom integrations |
CUSTOM_BRANDING | Customize the app with your branding |
PRIORITY_SUPPORT | 24/7 priority customer support |
DEDICATED_ACCOUNT_MANAGER | Dedicated account manager |
MULTI_CURRENCY | Support for multiple currencies |
ADVANCED_SECURITY | Enhanced security features |
COMPLIANCE_MONITORING | Real-time compliance monitoring |
WHITE_LABEL | Remove GrantControl branding |
AI_AUDIT_DEFENSE | AI-powered audit defense memos |
AI_GRANT_ASSISTANT | Context-aware AI chat assistant for grants |
SEMANTIC_SEARCH | Search using natural language |
CUSTOM_DASHBOARDS | Build custom dashboards |
AGENT_AUTONOMOUS | Autonomous AI agent execution with human oversight |
AGENT_ORCHESTRATION | Coordinate multiple AI agents for complex workflows |
Module-Gated Features
Some features are tied to marketplace extensions rather than the base tier. The FEATURE_MODULE_MAP maps these:
| Feature | Module ID |
|---|
IMPACT_MODULE | impact |
Tier Limits (TierLimits)
File: src/config/entitlements.ts
Each tier defines numeric limits for resources and rate limiting:
General Limits
| Limit | Potential | Professional | Ultimate |
|---|
maxUsers | 3 | 15 | 25 |
maxProjects | 10 | 50 | Unlimited |
maxStorage (MB) | 5,120 | 51,200 | Unlimited |
maxApiCallsPerMonth | 0 | 10,000 | Unlimited |
maxAiGenerationsPerMonth | 50 | 200 | Unlimited |
maxExportsPerMonth | 50 | Unlimited | Unlimited |
maxReportsPerMonth | 20 | Unlimited | Unlimited |
Rate Limits (per hour)
| Limit | Potential | Professional | Ultimate |
|---|
apiCallsPerHour | 0 | 1,000 | 10,000 |
aiGenerationsPerHour | 10 | 50 | Unlimited |
exportsPerHour | 5 | 50 | Unlimited |
Agent Limits
| Limit | Potential | Professional | Ultimate |
|---|
maxAgentCreditsPerMonth | 100 | 1,000 | 10,000 |
maxConcurrentAgents | 1 | 3 | 10 |
maxAgentStepsPerRun | 5 | 20 | Unlimited (-1) |
maxAgentTokenBudgetPerRun | 50,000 | 200,000 | Unlimited (-1) |
maxAgentRunsPerMonth | 10 | 200 | Unlimited (-1) |
agentRunsPerHour | 3 | 20 | 100 |
Convention: -1 means unlimited in agent limits. 999999 means unlimited for general limits.
Feature Entitlements Matrix
The FEATURE_ENTITLEMENTS record maps each SubscriptionTier to its included Feature[] array. Higher tiers cascade — Professional includes all Potential features, Ultimate includes all Professional features.
Helper Functions
| Function | Signature | Purpose |
|---|
getMinimumTierForFeature() | (feature: Feature) → SubscriptionTier | Find the lowest tier that includes a feature |
tierIncludesFeature() | (tier, feature) → boolean | Check if a tier includes a specific feature |
getFeaturesForTier() | (tier) → Feature[] | Get all features for a given tier |
getLimitsForTier() | (tier) → TierLimits | Get numeric limits for a given tier |
FEATURE_NAMES: Record<Feature, string> — Display names (e.g., AI_GENERATION → 'AI Generation')FEATURE_DESCRIPTIONS: Record<Feature, string> — Short descriptions for upgrade prompts
Credit System Primitives
Credits are the consumable unit for AI agent operations. Each organization has a monthly credit allocation based on their tier, plus optional one-time purchased packs.
Credit Balance
CreditBalance {
total: monthlyAllocation + purchasedExtra
used: agentCreditsUsedThisMonth
reserved: agentCreditsReserved (active reservations)
available: max(0, total - used - reserved)
purchasedExtra: agentCreditsPurchased (one-time packs)
}
Organization Credit Fields
These fields live on the organization document in Firestore:
| Field | Type | Description |
|---|
subscription.features.agentCreditsPerMonth | number | Monthly allocation (from tier) |
usageMetrics.agentCreditsUsedThisMonth | number | Credits consumed this billing period |
agentCreditsReserved | number | Credits held by active agent runs |
agentCreditsPurchased | number | One-time top-up credits (carry over) |
Credit Reservation
Before an agent run starts, credits are reserved to prevent overdraw from concurrent runs:
CreditReservation {
id: string;
organizationId: string;
agentRunId: string;
amount: number; // Credits reserved
consumedAmount: number; // Credits actually used so far
status: 'active' | 'consumed' | 'released' | 'expired';
expiresAt: string; // Auto-release after 1 hour (safety net)
}
organizations/{orgId}/creditReservations/{id}
Credit Lifecycle
Reserve → Consume (per step) → Release (unused remainder)
- Reserve:
creditService.reserveCredits(orgId, budget, runId) — atomic Firestore transaction
- Consume:
creditService.consumeCredits(orgId, reservationId, actualCredits) — per agent step
- Release:
creditService.releaseCredits(orgId, reservationId) — on run completion/failure/cancellation
Each agent tool has a fixed credit cost per invocation:
| Tool | Credits | Description |
|---|
query_documents | 2 | RAG retrieval |
scan_expense | 3 | Receipt/image analysis |
generate_journal | 5 | Structured text generation |
analyze_compliance | 8 | Multi-document analysis |
forecast_budget | 10 | Statistical + AI projection |
generate_report | 15 | Multi-section narrative |
Monthly Reset
At the beginning of each billing cycle:
usageMetrics.agentCreditsUsedThisMonth → 0agentCreditsReserved → 0 (expired reservations cleaned up)agentCreditsPurchased carries over until consumed
Quota Enforcement (QuotaService)
File: src/shared/billing/QuotaService.ts
The QuotaService enforces tier-based limits across all resource types. It checks limits before create operations and emits warning/exceeded events.
Resource Types
type ResourceType = 'users' | 'projects' | 'storage' | 'ai_generations' | 'agent_credits' | 'agent_runs';
Quota Check Flow
Service.validateQuota(orgId, 'create')
│
▼
QuotaService.checkQuota({ organizationId, resourceType, action, additionalCount })
│
├─ Reads org subscription tier
├─ Looks up limit from TIER_LIMITS
├─ Compares current usage vs limit
├─ Emits QUOTA_WARNING at 80% and 90% thresholds
└─ Returns { allowed, limit, current, available, requiresUpgrade, suggestedTier }
Quota Events
| Event | When |
|---|
QUOTA_WARNING | 80% or 90% of limit consumed |
QUOTA_EXCEEDED | Limit reached; operation blocked |
BaseService Integration
BaseService provides a validateQuota() protected method that services can call before create operations. It uses lazy imports to avoid circular dependencies with QuotaService:
protected async validateQuota(
organizationId: string,
action: 'create' | 'update' = 'create',
additionalCount = 1
): Promise<void>
BusinessLogicError with upgrade metadata if quota is exceeded.
Agent-Specific Quota (AgentQuotaService)
File: src/features/agents/services/AgentQuotaService.ts
Enforces agent-specific tier limits before runs start:
| Check | Limit Field | Description |
|---|
| Monthly runs | maxAgentRunsPerMonth | Total runs this billing period |
| Concurrent agents | maxConcurrentAgents | Runs with status running or awaiting_human |
| Hourly rate | agentRunsPerHour | Runs started in the last 60 minutes |
| Steps per run | maxAgentStepsPerRun | Max steps before forced completion |
| Token budget | maxAgentTokenBudgetPerRun | Total input+output tokens per run |
Maintenance
Update this document when:
- Adding new features to the
Feature enum
- Changing tier limits in
TIER_LIMITS
- Adding new resource types to QuotaService
- Modifying credit reservation/consumption flow
- Adding new tool credit costs
