User Guide

How to use ExpDater to track expiration dates and get notified by SMS and/or Email.

What “OCR” means

In this context, OCR stands for Optical Character Recognition, a technology that converts text in images into machine-readable text. When we say “We OCR it to extract dates,” it means the software automatically finds and pulls out date information from your uploaded image (e.g., a scanned receipt or form). This eliminates manual data entry, making the process faster and reducing errors.

• What it is: Software recognizes characters in a digital image (photo or scan) and converts them into editable/searchable text.
• How it works for dates: It scans the image, identifies date patterns (e.g., 10/16/2025 or October 16, 2025), and extracts them as structured data.
• Why it’s used: Automation saves time and avoids mistakes from manual transcription.

Quick Start

1. Open Home and create a user with your Email and optional Phone. Note your User ID.
2. Click SMS & Email in the top navigation to save your phone and send test messages.
3. Use either:
   • Capture to snap a photo of a bill, ID, or document, or
   • the Upload section on Home to choose a file (JPG/PNG/PDF).
   Enter your User ID, optionally set an alert date, tick SMS and/or Email, and submit to receive alerts.

Capture or Upload & process a document

ExpDater supports two equivalent ways to send a document into the system:

• Capture – mobile-friendly camera flow (/capture).
• Upload – traditional file upload (from the Home page).

Both flows feed into the same OCR + reminder pipeline; they only differ in how the file is selected.

Capture / Upload (camera-first flow)

From the Capture page you’ll see a form like:

Capture / Upload
Snap a photo of the document (or choose from your library). Optionally set the alert date manually.

• User ID (numbers only)
  Use the numeric-only User ID you created on the Home page. This ties the document to your contact details for SMS/Email reminders. Use the numeric User ID shown on the Home page (for example: 101), not your name.
• Photo (opens camera on phone)
  On a phone or tablet, tapping this will open your camera so you can snap a picture of the bill, ID, prescription, etc. You can also choose an existing photo from your library. On desktop, this behaves like a standard file picker.
• Alert date (optional)
  Format: mm/dd/yyyy. If you set this, ExpDater uses it as the expiration date. If you leave it blank, ExpDater will try to read the date via OCR from the captured photo.
• Email reminder and SMS reminder
  Check these if you want ExpDater to schedule email and/or SMS reminders for this document.

When you click Submit:

• ExpDater uploads the captured photo.
• If you didn’t set an alert date, we run OCR and try to detect the expiration date on the image.
• We create reminder jobs for the chosen channels (SMS, Email) according to your reminder schedule.

Upload & process a document (file-first flow)

1. Enter your User ID (shown after you create a user).
2. Choose the file (JPG/PNG/PDF). We OCR it to extract dates (e.g., “expires 2026-03-15”).
3. Optionally set the Alert date manually if you don’t want OCR to guess the date.
4. Choose SMS alerts and/or Email alerts for this upload.
5. Click Process. You’ll see results and we’ll schedule reminders based on ALERT_INTERVAL_DAYS.

Configure SMS & Email

Go to SMS & Email settings (from the top navigation):

• Phone in E.164 format (e.g., +15551234567).
• Carrier is optional (only for email-to-SMS). If you are using Twilio for SMS, you can usually leave it blank.
• Click Send Test SMS to confirm SMS works.
• Use Send Test Email to confirm emails arrive from your configured SMTP.

Reminder schedule (how often we notify)

ExpDater schedules reminders relative to the expiration date (either user-specified or OCR-detected from Capture/Upload). The cadence is controlled by ALERT_INTERVAL_DAYS in your .env.

Default (as shipped):

# .env
ALERT_INTERVAL_DAYS=30,14,7,3,1

Customize examples:

# include a same-day reminder
ALERT_INTERVAL_DAYS=30,14,7,3,1,0

# include overdue nudges (1 and 3 days after)
ALERT_INTERVAL_DAYS=30,14,7,3,1,0,-1,-3

• Positive numbers = days before the expiration date.
• 0 = day-of reminder.
• Negative numbers = days after the expiration date (overdue nudges).

Which channels send? For each upload or capture, your selections map to flags: should_sms and/or should_email. If no date is detected, no reminders are scheduled. Each document schedules its own reminders (no deduplication by default).

Apply changes: after editing .env, restart the scheduler to pick up the new cadence:

docker compose up -d --build scheduler

Notification preferences

On the Home page, pick SMS only, Email only, Both, or None. This saves locally (browser storage) and fills the Email/SMS reminder checkboxes automatically on both Capture and Upload forms.

FAQ & Troubleshooting

I didn’t receive the SMS.

• Try Send Test SMS on the SMS & Email settings page.
• Check the Twilio console logs. You’ll also see delivery webhooks recorded under twilio_status in the app’s logs.

I didn’t receive the email.

• Use Send Test Email on the settings page.
• Check your spam/junk folder and verify your SMTP credentials in .env.

Capture/Upload fails or doesn’t detect dates.

• Ensure the image is clear and the expiration date is visible. Try a PDF if available for higher clarity.
• Look at the app logs: docker compose logs --since=2m app.

Privacy & storage

• Files are stored under /data/uploads (Docker volume data).
• Only essential fields are stored (user contact, extracted dates, notification logs).
• Delete old files/records per your policy to minimize storage and exposure.