# WY-ICARE Automated Donor Reporting Reminders

## What it does

Each grant reporting period can carry its own deadline, owner, reminder schedule and escalation policy. The server checks open obligations automatically and creates deduplicated notifications.

### Default reminders

- 30 days before due date
- 14 days before due date
- 7 days before due date
- 3 days before due date
- 1 day before due date
- Due today
- Daily overdue alerts

The reminder offsets are configurable per reporting period.

## Overdue escalation

Once a reporting period passes its deadline and is not submitted or approved, the schedule is moved to `overdue`. If escalation is enabled, active Founder and Co-Founder accounts receive escalation notifications.

## Channels

### In-app
Always available when the database is available. Users can review notifications at `/ngo-portal/donor-notifications.html`.

### Email
Optional. Configure SMTP in the environment:

`SMTP_HOST`, `SMTP_PORT`, `SMTP_SECURE`, `SMTP_USER`, `SMTP_PASSWORD`, `SMTP_FROM`.

### Calendar
Authorised reporting users can download an authenticated `.ics` calendar from `/api/ngo/donor-reporting-calendar.ics` or the Reporting Calendar page. It can be imported into Google Calendar, Microsoft Outlook or Apple Calendar.

## Reliability

Reminder processing uses a PostgreSQL advisory lock to prevent duplicate processing across multiple application instances. Database uniqueness constraints also prevent duplicate notifications for the same schedule/reminder/channel/day.

## Governance

A reminder does not mark a report as submitted or approved. It only prompts the responsible person. Approval remains subject to the existing donor-report permission and audit trail.


## Role-based escalation
Each reporting period can define `escalation_roles` and `escalation_after_days`. The default escalation roles are Founder and Co-Founder, with escalation beginning on the due date.