Documentation Index
Fetch the complete documentation index at: https://grantmaster.dev/llms.txt
Use this file to discover all available pages before exploring further.
State Machines & Lifecycles
GrantMaster manages several complex business lifecycles using structured state machines. This document details the transitions, triggers, and side-effects for each.
1. Grant Pipeline Lifecycle
Moves an opportunity from discovery to final outcome.
Transition Details
| From | To | Trigger | Side-Effects |
|---|
| Any | PROSPECT | addToPipeline() | Create GrantPipelineEntry, emit PIPELINE_ENTRY_CREATED. |
| PROSPECT | IN_PREPARATION | updateStage() | Initialize GrantApplication workspace, create default tasks. |
| SUBMITTED | WON | convertToActiveGrant() | Create ActiveGrant, freeze budget, notify finance team. |
| Any | DEAD | archivePipeline() | Log rejectionReason, notify team. |
2. Expense Approval Lifecycle
Source: ExpenseStatus in the expense schema/workflow contracts.
Transition Details
| State | Behavior |
|---|
| DRAFT | Editable by the creator. Not visible in department budgets. |
| PENDING | Immutable by creator. Blocks relevant budget line items as “committed”. |
| APPROVED | Final state for grant allocation. Emits EXPENSE_APPROVED trigger for Novu. |
| REJECTED | Returned to creator with comments. Can be edited and resubmitted. |
3. Reporting Lifecycle (Post-Award)
Managed for each ActiveGrant.
Automated Triggers
- 30 Days Before: Send internal reminder to Project Lead.
- 7 Days Before: Escalation notification to Director if status is not
SUBMITTED.
- Day After: Mark as
OVERDUE and trigger high-priority system alert.
4. Monthly Journal Lifecycle
Source: JournalSubmissionStatus in src/schemas/journals.schema.ts
Managed for monthly journal submissions via useJournalSubmissions hook.
States
| State | Behavior |
|---|
| DRAFT | Editable by the employee. May be auto-generated from journal data. |
| SUBMITTED | Locked for employee edits. Awaiting manager review. |
| APPROVED | Final state. Feeds into compliance reporting. |
| REJECTED | Returned with feedback. Employee can edit and resubmit. |
| REGENERATION_NEEDED | AI-generated content flagged for regeneration. Returns to DRAFT. |
5. Active Grant Lifecycle
Source: ActiveGrantStatus in the grants contract module.
Tracks the lifecycle of a won grant from activation through completion or early termination.
States
| State | Behavior |
|---|
| ACTIVE | Grant is live. Budget tracking, reporting, and compliance are active. |
| COMPLETED | All deliverables and reports submitted. Grant is closed normally. |
| SUSPENDED | Temporarily paused. Expenditures blocked until resolved. |
| TERMINATED | Early closure. Triggers close-out reporting and remaining fund return. |
6. Subscription Lifecycle
Source: functions/src/stripe/stateMachine.ts
Stripe-driven subscription state machine. Transitions are validated and audit-logged. Invalid transitions are stored in the subscription_transition_logs collection.
States
| State | Category | Behavior |
|---|
| trialing | Active | Full access to tier features. No charges yet. |
| active | Active | Subscription is current and paid. |
| past_due | Payment problem | Payment failed, retrying via Stripe dunning. Features remain accessible. |
| unpaid | Payment problem | All retry attempts exhausted. Features may be restricted. |
| incomplete | Payment problem | Initial payment not yet confirmed. |
| paused | Paused | Manually paused. No charges; features may be limited. |
| canceled | Terminal | Subscription ended. Organization downgraded to Starter (free) tier. |
| incomplete_expired | Terminal | Initial payment window expired. Organization on Starter tier. |
Helper Functions (functions/src/stripe/stateMachine.ts)
| Function | Description |
|---|
isValidTransition(from, to) | Check if a state transition is allowed |
validateAndLogTransition(orgId, from, to) | Validate and audit-log the transition |
isTerminalStatus(status) | true for canceled and incomplete_expired |
isActiveStatus(status) | true for active and trialing |
isPaymentProblemStatus(status) | true for past_due, unpaid, incomplete |
getTierForStatus(status) | Returns 'Starter' for terminal/unpaid states |
7. Document Lifecycle
Source: DocumentStatus in the documents contract module.
Documents pass through a RAG-indexing pipeline after upload, and can optionally enter an approval workflow before being shared externally.
States
| State | Behavior |
|---|
| UPLOADING | File is in transit to Firebase Storage. |
| PROCESSING | Document Brain is chunking and embedding the file for RAG. |
| INDEXED | Available for AI search. Editable metadata, downloadable. |
| FAILED | Processing error. Admin can retry or delete. |
| PENDING_APPROVAL | Awaiting manager sign-off before external distribution. |
| APPROVED | Cleared for sharing. Share link can be generated. |
| REJECTED | Returned to INDEXED state; rejection reason visible to uploader. |
| SHARED | External link is live and accessible. |
| ARCHIVED | Soft-deleted. Hidden from search; restorable by admin within 30 days. |
Side-Effects
| Transition | Side-Effects |
|---|
PROCESSING → INDEXED | Emit DOCUMENT_INDEXED; notify uploader |
PROCESSING → FAILED | Emit DOCUMENT_PROCESSING_FAILED; create compliance alert if required doc |
PENDING_APPROVAL → APPROVED | Emit DOCUMENT_APPROVED; generate share link |
PENDING_APPROVAL → REJECTED | Notify uploader with rejection reason |
8. Project Phase Lifecycle
Source: ProjectPhase and ProjectStatus enums in src/schemas/projects.schema.ts
Projects have two overlapping state dimensions: phase (where the project is in its lifecycle) and status (operational health). Phase advances sequentially; status can change at any phase.
Phase Progression
Status Overlay
Phase / Status Matrix
| Phase | Allowed Statuses | Notes |
|---|
initiation | planning | Initial state on project creation |
planning | planning, active | Budget and team assigned |
execution | active, on_hold | Milestone tracking live |
monitoring | active, on_hold | Reporting and evaluation active |
closure | active, completed | Final reports being prepared |
| Any | archived | Terminal; all write operations blocked |
Side-Effects
| Transition | Side-Effects |
|---|
Phase initiation → planning | Create default budget categories; emit PROJECT_CREATED |
Phase planning → execution | Emit PROJECT_STARTED; activate budget tracking |
Status active → on_hold | Emit PROJECT_ON_HOLD; notify project manager and finance |
Phase monitoring → closure | Emit PROJECT_CLOSURE_INITIATED; trigger grant report reminders |
Status * → completed | Emit PROJECT_COMPLETED; archive active milestones; notify linked grant managers |
Status * → archived | Emit PROJECT_ARCHIVED; freeze all writes on linked budgets and tasks |
9. User Invitation Lifecycle
Source: InvitationStatus in the shared auth contracts and invitationService.ts in src/shared/auth/
States
| State | Behavior |
|---|
| PENDING | Invitation email sent; signed JWT stored in invitations collection. |
| ACCEPTED | User account created in Firebase Auth; employees document created; invitation document deleted. |
| EXPIRED | Token TTL elapsed. Admin can issue a new invitation; original record remains for audit. |
| REVOKED | Admin manually cancelled before acceptance. |
Side-Effects
| Transition | Side-Effects |
|---|
[*] → PENDING | Send Postmark user-invitation email; emit USER_INVITED; write audit log |
PENDING → ACCEPTED | Create employees document with role from invitation; emit USER_ONBOARDED; trigger role-based onboarding tour |
PENDING → EXPIRED | Emit INVITATION_EXPIRED (scheduled check); update invitation status |
PENDING → REVOKED | Emit INVITATION_REVOKED; write audit log |
10. Extension / Module Installation Lifecycle
Source: extension contracts and ExtensionActivationService.ts in src/shared/platform/
States
| State | Behavior |
|---|
| INSTALLING | activate() hook running. ModuleRegistry entry created. Extension not yet visible to users. |
| ACTIVE | Extension fully operational. Widgets registered; commands available in ⌘K palette. |
| ERROR | Activation or runtime failure. Widgets and commands unregistered. Admin sees error details. |
| DEACTIVATED | Manually disabled. Widgets and commands removed; Firestore data preserved. |
Activation Steps (in order)
isCompatible(manifest.coreApiVersion) — version check; rejects if false- Quota check — does the org’s tier allow this module?
- Call
extension.activate() — registers EventBus subscriptions, widgets, commands
- Write
ModuleInstallation document with status: 'active'
- Emit
MODULE_INSTALLED on EventBus
Deactivation Steps (in order)
- Call
extension.deactivate() — cleans up commands and widgets
- Call
bus.unsubscribeAll() — removes all EventBus listeners
- Update
ModuleInstallation.status to 'deactivated'
- Emit
MODULE_DEACTIVATED on EventBus
11. Compliance Violation Lifecycle
Source: compliance schema/contracts.
States
| State | Behavior |
|---|
| OPEN | Alert created; visible in compliance dashboard and auditor 5-dimension view. |
| ACKNOWLEDGED | Team member has seen it. SLA clock starts. |
| IN_PROGRESS | Active remediation work underway. Linked to a task or workflow. |
| ESCALATED | SLA threshold breached; escalated to Director or Admin. |
| RESOLVED | Underlying rule condition no longer met; resolution notes recorded. |
SLA Defaults by Severity
| Severity | Acknowledge by | Resolve by |
|---|
low | 5 business days | 30 days |
medium | 2 business days | 14 days |
high | 1 business day | 7 days |
critical | 4 hours | 24 hours |
Side-Effects
| Transition | Side-Effects |
|---|
[*] → OPEN | Emit COMPLIANCE_VIOLATION_DETECTED; send notification to compliance lead |
OPEN → ESCALATED | Emit COMPLIANCE_ESCALATED; notify Director / Admin |
IN_PROGRESS → RESOLVED | Emit COMPLIANCE_VIOLATION_RESOLVED; write audit log with resolution notes |
Maintenance
Update this document when:
- Adding a new stage to the owning schema or feature contract enum.
- Changing the lead time for automated reminders.
- Introducing a new workflow (e.g., Partner Onboarding).
- Adding or changing SLA defaults for compliance alerts.
