Skip to main content

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/admin/admin.md.

​
Admin

​
Overview

The admin feature provides a unified operations cockpit for organization Admins and Managers. It aggregates pending items from multiple domains — journals, expenses, M&E impact data points, and compliance documents — into a single approval queue, enabling administrators to act on cross-domain work without navigating between feature areas. It also surfaces a team health snapshot, a unified deadline timeline, workflow blockers, a compliance matrix per team member, and a settings traceability panel (who last changed what). Roles served: Admin, Manager Entry point: /admin → AdminStartPage, AdminApprovalsPage, AdminActivityPage

​
Data Model

​
Firestore Collections

The admin feature does not own any Firestore collections. It reads directly from collections owned by other features.
Collection (owned by)Read purpose
timesheets (journals)Pending journal submissions
expenses (expenses)Pending expense approvals
meDataPoints (impact)Submitted M&E data points awaiting approval
complianceDocuments (compliance)Documents in under_review status
milestones (projects/workflows)Upcoming and overdue deadlines
complianceDeadlines (compliance)Grant reporting deadlines
auditLogs (shared)Activity feed entries
organizations/{id}/config/settingsSettings traceability

​
Key TypeScript Types

// Normalized approval item across all domain types
interface AdminApprovalItem {
  id: string;                    // Prefixed: "journal:{id}", "expense:{id}", etc.
  type: 'journal' | 'expense' | 'impact' | 'compliance_document';
  sourceId: string;
  severity: 'low' | 'medium' | 'high' | 'critical';
  status: 'submitted' | 'approved' | 'rejected' | 'under_review' | 'blocked';
  needsMyAction: boolean;
  blockedReason: 'unassigned_approver' | 'missing_doc' | 'overdue_milestone' | null;
  availableActions: Array<'approve' | 'reject' | 'assign' | 'escalate'>;
  raw: JournalSubmission | Expense | MEIndicatorDataPoint | ComplianceDocument;
}

// Per-user compliance document status matrix
interface AdminComplianceMatrixRow {
  userId: string;
  role: SystemRole;
  requirements: Array<{ status: 'missing' | 'uploaded' | 'approved' | 'expired'; ... }>;
  missingRequiredCount: number;
  expiredCount: number;
}

// Aggregate dashboard data bundle
interface AdminDashboardSnapshot {
  approvals: AdminApprovalItem[];
  complianceRows: AdminComplianceMatrixRow[];
  deadlines: AdminTimelineItem[];      // Up to 12, sorted by due date
  blockers: AdminWorkflowBlocker[];
  teamHealth: AdminTeamHealthSnapshot;
  settingsTraceability: AdminSettingsTraceability[];
}

​
Key Behaviors

​
Unified Approval Queue

getAdminDashboardSnapshot() fetches from 7 sources in parallel. Results are normalized into AdminApprovalItem[] and sorted by severity (critical → high → medium → low), then by submission date (oldest first). Severity is derived per domain:
  • Journals: critical if red compliance flags > 0, high if yellow flags > 0, medium if total hours ≥ 160
  • Expenses: critical if flaggedForAudit, high if amount ≥ 1000, medium if ≥ 250
  • Impact data points: always medium
  • Compliance docs: critical if expired, otherwise medium
Blocked items surface separately as AdminWorkflowBlocker[], grouped by blocking reason (unassigned_approver, missing_doc, overdue_milestone).

​
Bulk Approval Actions

applyAdminApprovalAction() dispatches to the appropriate domain service for each selected item:
  • approve → approveJournal(), expenseWorkflowService.approveExpenses(), dataPointService.bulkApprove(), complianceDocumentService.updateStatus('approved')
  • reject → mirrors with rejection counterparts
  • assign → writes assignedApproverId to the source document and sends a notification to the assignee
  • escalate → writes escalatedAt, escalatedBy, escalationReason to the source document
Every action logs an audit event via logAuditEvent().

​
Compliance Matrix

buildComplianceMatrix() evaluates required documents for each MEMBER / MANAGER / ADMIN user against 6 role-based requirements (contracts, insurance, policy acknowledgements, certifications). Returns rows sorted by most missing or expired requirements first.

​
Deadline Timeline

buildDeadlineTimeline() merges workflow milestones (from milestones collection) and grant reporting deadlines (from complianceDeadlines collection) into a unified, date-sorted list capped at 12 items.

​
Activity Feed

getAdminActivityFeed() merges auditLogs and complianceAuditTrail events, deduplicates by timestamp, and groups results byUser and byGrant for dashboard display.

​
Settings Traceability

getSettingsTraceability() returns which settings groups were last modified and by whom — covering org settings, onboarding configuration, and notification office hours.

​
Service Contract

All functions are exported directly from adminOperationsService.ts (no class wrapper).
ExportOwnsKey signature
getAdminDashboardSnapshotFull dashboard data fetch(orgId, currentUserId, users[]) → AdminDashboardSnapshot
applyAdminApprovalActionCross-domain approval dispatch(request, items[]) → void
buildApprovalItemsNormalization of cross-domain items(params) → AdminApprovalItem[]
buildComplianceMatrixPer-user doc requirement check(users[], docs[]) → AdminComplianceMatrixRow[]
buildDeadlineTimelineMerged deadline list(workflowDeadlines[], complianceDeadlines[]) → AdminTimelineItem[]
buildWorkflowBlockersBlocker grouping(items[], deadlines[]) → AdminWorkflowBlocker[]
buildTeamHealthTeam metrics snapshot(users[], journals[], deadlines[]) → AdminTeamHealthSnapshot
getAdminActivityFeedAudit + compliance event feed(orgId) → AdminActivityFeed
sendComplianceReminderNotify user of missing docs(request) → void
getSettingsTraceabilitySettings change attribution(orgId) → AdminSettingsTraceability[]

​
Events

​
Emitted

The admin feature does not emit EventBus events directly. It delegates to domain services which emit their own events (e.g., EXPENSE_APPROVED, JOURNAL_APPROVED).

​
Consumed

None. The admin feature is a read/action orchestration layer; it does not subscribe to EventBus events.

​
Dependencies

Depends on:
  • features/expenses — expenseWorkflowService.approveExpenses/rejectExpenses
  • features/journals — approveJournal, rejectJournal, listSubmissions
  • features/compliance — complianceDocumentService, auditTrailService
  • features/settings — loadOrganizationSettings, fetchAppSettings
  • extensions/compliance-vault — ComplianceDocumentService, AuditTrailService
  • extensions/impact — dataPointService.bulkApprove/bulkReject
  • shared/audit — logAuditEvent, queryAuditLogs
  • shared/notifications — sendNotification
Depended on by: None — this is a terminal orchestration feature.

​
File Structure

admin/
├── components/
│   ├── AdminWorkflowInsights.tsx      # Workflow blocker cards
│   ├── DocumentsComplianceCockpit.tsx # Compliance matrix UI
│   └── SettingsTraceabilityCard.tsx   # Settings audit panel
├── hooks/
│   └── useAdminApprovalsState.ts      # Local state for approvals page
├── pages/
│   ├── AdminStartPage.tsx             # Dashboard entry point
│   ├── AdminApprovalsPage.tsx         # Unified approval queue
│   └── AdminActivityPage.tsx          # Activity feed
├── services/
│   └── adminOperationsService.ts      # All data fetching and action dispatch
├── types.ts                           # AdminApprovalItem, AdminDashboardSnapshot, etc.
└── index.ts