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

​
Compliance

​
Overview

The Compliance feature provides comprehensive policy management, monitoring, and enforcement across grant projects. It enables organizations to:
  • Extract & manage compliance policies from grant documents via AI or manual creation
  • Monitor journal entries and expenses against policies with real-time alerts
  • Track audit trails of all compliance actions and policy changes
  • Report on compliance status with risk scoring and trend analysis
  • Map donor requirements to platform policies for efficient adoption
This feature bridges policy engine logic (what rules apply) with monitoring logic (what violations occur), providing auditors, finance leads, and compliance officers with visibility into organizational compliance posture.

​
Data Model

​
Firestore Collections

CollectionDocument TypeDescription
complianceRulesCompliancePolicyOrganization and project-level compliance policies (AI-extracted or manually created)
complianceSummariesComplianceSummaryMonthly aggregated compliance metrics per organization (journals, expenses, reports)
auditLogsAuditLogImmutable audit trail of all system actions (logins, resource changes, approvals)
expense_audit_logsExpenseAuditLogAudit trail specific to expense actions (created, approved, rejected, exported)
complianceAlertsComplianceAlertCompliance violations and warnings with status tracking (active → acknowledged → resolved)
tenantDonorConfigsTenantDonorConfigDonor type configuration per organization; links to recommended platform policies

​
Key TypeScript Types

TypePurpose
CompliancePolicyCore policy document: categories, severity, status, AI metadata, versions, adoption source
ComplianceAlertViolation instance: type (journal/expense/report), severity, status, resolution metadata
ComplianceSummaryMonthly snapshot: overall score, journal/expense/report counts by status, risk level
ComplianceTrendHistorical data points: compliance score, submission rate, approval time, risk counts over time
ActivityRulePersonnel eligibility rule: allowed activities, restrictions (max hours, pre-approval), citations
PolicyViolationPolicy breach record: type (missing_evidence, threshold_exceeded), status, resolution notes

​
Key Behaviors

​
AI-Powered Policy Extraction

When a grant document (contract, RFP) is uploaded, the compliance service:
  1. Sends document text to Google Gemini for analysis
  2. Extracts compliance requirements with AI confidence scores (0-1)
  3. Creates CompliancePolicy records in draft status
  4. Logs extraction metadata (processing ID, timestamp, AI model version)
  5. Emits COMPLIANCE_RULE_VIOLATED for critical thresholds
Extracted policies must be reviewed and approved by a manager before enforcement.

​
Manual Policy Creation

Users can manually create policies:
  • Via CompliancePolicyEditor component (form-based)
  • Without AI metadata; marked isManuallyCreated: true
  • Require approval before applying to projects

​
Approval Workflow

Policies transition through statuses:
  • AI_EXTRACTED → manager reviews → APPROVED | REJECTED
  • MANUALLY_CREATED → manager reviews → APPROVED | REJECTED
  • NEEDS_REVIEW → awaiting action
  • Rejections include reason; edit history preserved for audit

​
Real-Time Monitoring

ComplianceMonitoringService evaluates submissions (journals, expenses) against active policies:
  • Journal entries: Validates description quality, activity allocation percentages, eligibility dates, eligibility against ActivityRule
  • Expenses: Checks against project budgets, policy thresholds, supporting documentation
  • Reports: Tracks due dates and submission deadlines
Violations create ComplianceAlert records with severity levels (GREEN/YELLOW/RED).

​
Alert Lifecycle

  1. Active: Violation detected; manager notified
  2. Acknowledged: Manager reviewed; action in progress
  3. Resolved: Violation corrected or marked as false positive
Resolution requires user action and audit logging.

​
Donor-to-Policy Mapping

GrantorComplianceService manages grantor (donor) compliance logic:
  • When a donor type is added to organization, system recommends matching platform policies
  • When a donor is removed, detects orphaned rules and warns of affected projects
  • Tracks adoption source (donor_profile, manual, template, platform_default)
  • Maintains TenantDonorConfig document per organization

​
Policy Versioning

Policies support multiple versions:
  • currentVersion increments with updates
  • versions[] contains history: policy text, category, severity, timestamps
  • editHistory[] tracks all changes: field, old/new value, reason, editor

​
Audit Event Emission

The feature emits compliance-specific events (see EventBus rule):
  • COMPLIANCE_ALERT_RAISED: Policy violation detected
  • COMPLIANCE_ALERT_RESOLVED: Violation resolved
  • COMPLIANCE_RULE_VIOLATED: Policy threshold breached

​
Service Contract

ServiceOwnsKey Methods
ComplianceServicePolicy CRUD, AI extraction, approval workflowssaveCompliancePolicies(), extractRulesFromDocument(), analyzeDocument()
ComplianceMonitoringServiceReal-time compliance checking, alerts, summariesgetComplianceSummary(), raiseComplianceAlert(), resolveAlert()
ExpenseAuditServiceExpense audit logs (approval, rejection, export)logExpenseAction(), getExpenseAuditLogs()
JournalComplianceServiceJournal entry compliance validationvalidateAllocation(), validateDescription(), validateEligibility()
GrantorComplianceServiceDonor config, policy recommendations, orphan detectionanalyzeDonorChange(), getRecommendedRules()
AuditServiceCross-cutting audit logs (all resource changes)logAuditEvent(), queryAuditLogs()
AuditLogServiceFirestore audit log queries (organization/resource)getOrganizationAuditLogs(), getResourceHistory()

​
Events

​
Emitted

EventTriggerSeverityPersisted
COMPLIANCE_ALERT_RAISEDJournal/expense violation detectedHIGH✓
COMPLIANCE_ALERT_RESOLVEDManager resolves alertMEDIUM✓
COMPLIANCE_RULE_VIOLATEDPolicy threshold breached (e.g., 80% budget)HIGH✓

​
Consumed

EventHandler Behavior
JOURNAL_SUBMITTEDJournalComplianceService evaluates; raises COMPLIANCE_ALERT if violations found
EXPENSE_APPROVEDExpenseAuditService logs action; checks against budget policies
PROJECT_DONOR_UPDATEDGrantorComplianceService recommends policies; detects orphaned rules

​
Dependencies

  • Depends on:
    • documents (compliance policies extracted from documents)
    • expenses (expense audit logs, budget threshold checks)
    • journals (journal compliance validation)
    • organizations (tenant donor config, organization context)
    • projects (project policies, budget, eligibility dates)
    • ai (Gemini-based document analysis and rule extraction)
  • Depended on by:
    • auditor (audit log queries, compliance reports)
    • dashboard (compliance metrics, alert summaries)
    • reports (export audit logs, compliance trend reports)

​
File Structure

src/features/compliance/
├── README.md                          # This file
├── ComplianceContext.tsx              # Project-level policy state & operations
├── index.ts                           # Public API barrel export
├── public.ts                          # Re-export utilities (if any)
│
├── components/                        # 20 UI components
│   ├── ComplianceDashboard.tsx        # Main compliance view
│   ├── ComplianceConsolidated.tsx     # Multi-tab consolidated view
│   ├── CompliancePoliciesList.tsx     # Policy listing & filtering
│   ├── CompliancePolicyEditor.tsx     # Create/edit policies
│   ├── CompliancePolicyExtractor.tsx  # AI extraction workflow
│   ├── AIProcessingLogViewer.tsx      # View extraction metadata
│   ├── AlertsTab.tsx                  # Alert management
│   ├── AuditLogsTab.tsx               # Audit log viewer
│   ├── ComplianceReportsView.tsx      # Export & reporting
│   ├── ProjectComplianceOverview.tsx  # Project-specific view
│   └── ... (others: Coverage, Policy Recomm, GrantDocumentAI, etc.)
│
├── hooks/                             # Custom React hooks
│   ├── useCompliance.ts               # Compliance state management
│   └── useCompliancePoliciesFilters.ts # Filter & search logic
│
└── services/                          # Business logic & data access
    ├── complianceService.ts           # Policy CRUD & AI extraction
    ├── complianceMonitoringService.ts # Alert monitoring, summaries
    ├── expenseAuditService.ts         # Expense audit logging
    ├── journalComplianceService.ts    # Journal validation rules
    ├── GrantorComplianceService.ts    # Donor → policy mapping
    ├── auditService.ts                # (Re-export from @/shared)
    ├── auditLogService.ts             # Audit log queries
    ├── auditorAccessService.ts        # Auditor permission checks
    ├── auditEventSubscriber.ts        # Event listener for audit logging
    │
    ├── compliance/                    # Sub-services
    │   ├── documentAnalysis.ts        # AI document analysis
    │   ├── personnelCompliance.ts     # Activity & role validation
    │   └── policyLifecycle.ts         # Policy versioning & history
    │
    └── compliance-monitoring/         # Client wrapper around monitoring
        ├── ComplianceMonitoringServiceClient.ts
        ├── summary.ts                 # Build compliance summary
        ├── dateUtils.ts               # Period calculations
        └── types.ts                   # Alert filters & types
Generated: 2026-03-17 — Feature documentation for GrantMaster compliance system.