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

​
Auditor

​
Overview

The auditor feature provides a read-only compliance review dashboard for external auditors and internal compliance reviewers. It surfaces compliance posture across five dimensions (journals, expenses, policy coverage, audit trail health, grantor compliance), supports time-boxed access grants, and allows CSV export of audit data. The Auditor role (SystemRole.AUDITOR) is distinct from Admin — auditors cannot approve or reject items; they can only view and export. Access is controlled via AuditorAccessGrant documents that carry an explicit expiry date. Entry point: /auditor → AuditorDashboard, AuditorReviewPanelPage

​
Data Model

​
Firestore Collections

The auditor feature does not own its own collections. It reads from compliance and audit infrastructure.
Collection (owned by)Read purpose
auditLogs (shared)Audit trail events for the selected period
complianceAlerts (compliance)Active/acknowledged compliance alerts
complianceSummaries (compliance)Per-period compliance summary aggregates
configurationSnapshots (compliance)Point-in-time configuration captures
auditorGrants (compliance)Time-boxed auditor access grant documents
ruleCoverageMatrix (PolicyContext)Policy rule application coverage

​
Key TypeScript Types

// Five compliance dimensions shown on the dashboard
interface AuditDashboardDimensions {
  journals: DimensionStatus;
  expenses: DimensionStatus;
  coverage: DimensionStatus;    // Policy rule coverage
  auditTrail: DimensionStatus;
  grantors: DimensionStatus;
}

// Status for each dimension
type DimensionStatus = 'ok' | 'warning' | 'critical' | 'unknown';

// Audit trail statistics for the selected period
interface AuditTrailStats {
  total: number;
  failures: number;
  uniqueUsers: number;
}

// Time-boxed auditor access (from compliance feature)
interface AuditorAccessGrant {
  id: string;
  organizationId: string;
  auditorUserId: string;
  expiresAt: string;
  scope: string[];
  grantedBy: string;
}

​
Key Behaviors

​
Period-Based Dashboard

useAuditDashboard drives the entire dashboard. It accepts a period (yyyy-MM) and fetches:
  • ComplianceMonitoringService.getComplianceSummary(orgId, period) — overall compliance score and domain breakdown
  • ComplianceMonitoringService.getActiveAlerts(orgId, { status: ['active', 'acknowledged'] }) — top 5 alerts
  • listConfigurationSnapshots(orgId, 5) — recent configuration snapshots for forensic review
  • Audit logs filtered to the period (fetchAuditLogs)
Period selector shows current month + previous 11 months.

​
Five Compliance Dimensions

Dimension statuses are derived from the compliance summary using pure helper functions in auditDashboardStatus.ts:
  • getJournalsDimensionStatus — based on journal submission rates and compliance scores
  • getExpensesDimensionStatus — based on flagged/rejected expense ratios
  • getCoverageDimensionStatus — based on policy rule coverage matrix completeness
  • getAuditTrailHealthStatus — ratio of failure events to total events
  • getGrantorComplianceStatus — based on grantor-specific compliance requirements in the coverage matrix

​
Time-Boxed Auditor Access

For AUDITOR role users, the dashboard loads the active AuditorAccessGrant document via getActiveAuditorGrants(). The grant is displayed in the panel header so the auditor knows their scope and expiry. SuperAdmins bypass this check.

​
Data Export

createExport() triggers an asynchronous export job (createAuditExportJob) that produces a CSV including audit logs, journals, expenses, and projects (but not raw user PII) for the selected period. The AUDIT_EXPORT_JOBS_ENABLED feature flag (from features/compliance/public) gates this capability.

​
Review Panel

AuditorReviewPanelPage contains the full review interface with filter controls, report display, permission guards, and quick action buttons. It uses AuditorReviewPanelContext for local state.

​
Service Contract

The auditor feature has no service files of its own — all data access is via hooks that delegate to compliance services.
HookOwnsKey returns
useAuditDashboardFull dashboard state and data loadingcomplianceSummary, dimensions, topAlerts, auditLogs, snapshots, auditorGrant, auditTrailStats, createExport, refresh

​
Events

​
Emitted

None. The auditor feature is read-only and does not emit any EventBus events.

​
Consumed

None. The auditor feature does not subscribe to EventBus events.

​
Dependencies

Depends on:
  • features/compliance — ComplianceMonitoringService, auditorAccessService, AuditExportJob
  • contexts/PolicyContext — coverageMatrix (rule coverage data)
  • contexts/RBACContext — hasRole, hasAuditorAccess, isAuditor
  • hooks/useAuditLog — audit log fetching and CSV export
Depended on by: None — terminal read-only feature.

​
File Structure

auditor/
├── components/
│   ├── AuditorReviewPanel/
│   │   ├── AuditorReviewPanelContext.tsx   # Local panel state
│   │   ├── ComplianceOverview.tsx
│   │   ├── FilterControls.tsx              # Period + dimension filters
│   │   ├── PanelHeader.tsx                 # Shows auditor grant info
│   │   ├── PermissionGuard.tsx             # RBAC gate
│   │   ├── QuickActions.tsx
│   │   ├── RecentReportsList.tsx
│   │   ├── ReportDisplay.tsx
│   │   └── index.tsx
│   ├── audit-dashboard/
│   │   ├── AuditDimensionCard.tsx          # Per-dimension status card
│   │   ├── ConfigurationSnapshotsCard.tsx
│   │   ├── GrantorComplianceCard.tsx
│   │   ├── RecentAuditEventsCard.tsx
│   │   └── TopAlertsCard.tsx
│   └── pages/
│       ├── AuditorDashboard.tsx            # Main dashboard page
│       └── AuditorReviewPanelPage.tsx      # Full review panel
├── hooks/
│   ├── auditDashboardStatus.ts             # Pure dimension-status helpers
│   └── useAuditDashboard.ts                # Primary data + state hook
└── index.ts