# Reminders

## Purpose

Reminders allow the creation of **scheduled notifications** sent to users and their contacts using the channels configured in each recipient's profile (e.g. email, WhatsApp).

A firing [Metric Alert](metric-alerts.md) also creates a reminder to keep re-notifying the recipients until the alert is acknowledged.

## How it works

Each reminder is linked to:

- a main user
- a custom message
- a scheduling rule
- a list of recipients (the user and/or related contacts)

The system periodically checks for due reminders. When a reminder is due, it sends the notification and automatically calculates the next execution date.

### Scheduling modes

#### One time — `once`

The reminder is sent **only once** at the specified date and time.

Example: date/time `2025-03-15 10:30` → the message is sent only at that moment and the reminder is considered completed.

#### Daily — `daily`

The reminder is sent **every day** at the chosen time.

Example: time `09:00` → a notification is sent every day at 09:00.

#### Weekly — `weekly`

The reminder is sent on specific days of the week at the same time.

Example: Monday and Thursday at `08:30` → the system sends the reminder every Monday and Thursday at 08:30.

#### Fixed interval — `interval`

The reminder is sent based on a fixed interval expressed in minutes, hours, or days.

Examples: every 30 minutes, every 6 hours, every 10 days.

After each delivery, the system automatically calculates the next execution by adding the configured interval.

### Recipients

For each reminder it is possible to choose:

- the main user
- one or more related contacts

Each recipient receives the notification through the **channels configured in their profile** (e.g. email, WhatsApp).

### Delivery channels

The system uses the channels defined in `users.notification_channels`.

Examples: `["mail"]`, `["mail","whatsapp"]`

It is not necessary to configure the channel on the reminder itself — it is inherited from user preferences.

## Key entities & DB

| Field / concept | Description |
|-----------------|-------------|
| `enabled` | Whether the reminder is active |
| `next_run_at` | Next scheduled execution time |
| `last_sent_at` | Timestamp of the last delivery |
| `timezone` | Timezone used for scheduling |
| `users.notification_channels` | Delivery channels inherited per recipient |

## Technical flow

1. The scheduler runs the command `reminders:dispatch`.
2. The system selects reminders with `enabled = true` and `next_run_at <= now`.
3. For each due reminder, a `SendReminderJob` is dispatched.
4. The job:
   - sends the notification to recipients
   - updates `last_sent_at`
   - recalculates `next_run_at`

## Notes / edge cases

- The reminder timezone is defined by the `timezone` field.
- If a reminder is disabled (`enabled = false`), it will never be sent.
- Reminders of type `once` are not rescheduled after sending.

### Practical examples

| Type | Configuration | Result |
|------|---------------|--------|
| `once` | `2025-04-10 14:00` | Single delivery on April 10 at 14:00 |
| `daily` | `07:30` | Every day at 07:30 |
| `weekly` | mon, wed `09:00` | Every Monday and Wednesday |
| `interval` | 3 days | Every 3 days from the last delivery |

Future extensions (e.g. monthly scheduling or advanced rules) can be added while keeping the same architecture.


## Grouped Drug Administration Reminders

The system groups prescriptions scheduled at the same administration time into a single notification.
The patient receives one message containing all drugs with a single confirmation button
Contacts receive the same message without confirmation
Retry reminders resend the same grouped message until confirmed
Grouping occurs only when prescriptions share the same hour and minute. Different times or offsets generate separate notifications.
The admin reminders list includes an info dialog showing patient, administration time and related drugs in a user-friendly format.

## Related documentation

- [Notifications](notifications.md) — delivery channels and CTA confirmation
- [Business Logic](../business-logic.md) — drug prescriptions that generate reminders