Documentation Index
Fetch the complete documentation index at: https://grantmaster.dev/llms.txt
Use this file to discover all available pages before exploring further.
Data Flow Traces
End-to-end traces showing how data flows through the GrantMaster system for key workflows. Each trace follows the path from user action to final state.
Trace 1: Expense Submission & Approval
Submit an Expense
| Step | File | Function/Method |
|---|
| Form validation | src/hooks/useZodForm.ts | handleSubmit() |
| Create expense | src/features/expenses/services/ExpenseService.ts | create() |
| Submit for approval | src/features/expenses/services/ExpenseWorkflowService.ts | submitExpenses() |
| EventBus emission | @/core/eventBus | emit(EXPENSE_SUBMITTED) |
| Firestore collection | expenses | Document type: Expense |
Approve an Expense
| Step | File | Function/Method |
|---|
| Manager clicks Approve | Approval UI component | handleApprove() |
| Status transition | ExpenseWorkflowService.ts | approveExpenses() |
| Firestore update | expenses collection | status: 'approved' |
| EventBus emission | @/core/eventBus | emit(EXPENSE_APPROVED) |
| Notification to submitter | Notification service | Automatic via event listener |
| Audit log | auditLogs collection | Automatic via logSuccess() |
Trace 2: Grant Application Lifecycle
Discovery → Pipeline → Application → Submission
| Step | Firestore Collection | Document Type |
|---|
| Pipeline tracking | grantPipeline | Pipeline entry |
| Application draft | grantApplications | Grant application |
| Active grant (post-award) | activeGrants | Active grant record |
src/features/grants/services/ — grant discovery, pipeline, application servicessrc/features/grantors/services/ — grantor/funder relationship management
Trace 3: User Onboarding
Sign-Up → Auth → Tenant Provisioning → Guided Tour
| Step | File | Notes |
|---|
| Authentication | src/features/onboarding/components/Auth.tsx | Email/password, Google SSO, invitation links |
| MFA setup | src/features/onboarding/components/MfaSetup.tsx | Optional, prompted for admins |
| Tenant provisioning | Tenant provisioning wizard | 9 steps: org details → team → settings |
| Firestore writes | employees (users), organizations | Gotcha: employees stores User documents |
| Guided tour | @onboardjs/react | Role-specific steps and checklists |
Trace 4: Generic Request Lifecycle (Full Stack)
Generic trace showing every middleware layer a request passes through. Use this to understand where to add logging, validation, or auth checks.
Reading a Trace
Each trace documents:
- User action — what the user clicks/submits
- Component — React component handling the interaction
- Hook — custom hook managing state/mutations
- Service method — BaseService method processing the operation
- Firestore collection(s) — where data is written
- EventBus event(s) — what gets emitted for side effects
- Side effects — notifications, audit logs, cache invalidation
Key Architectural Invariants
- UI → Hook → Service → Firestore — data always flows through the service layer
- EventBus only in services — components never emit events directly
- All writes validated — Zod schemas enforce data integrity at the service boundary
- All queries limited — every Firestore query has explicit
limit()
- Audit trail automatic —
logSuccess() in BaseService handles audit logging
