🔔 Integrations, Notifications & Analytics

IntelliSignup bridges the gap between web-based signup forms and daily organizer workflows by integrating directly with external calendar ecosystems, providing automated background email dispatches, and recording privacy-first analytics.

💡 Asynchronous Architecture

External network API calls (Google Calendar synchronization and SMTP email transmissions) execute asynchronously inside background threads or dedicated systemd workers. Web requests return to users in milliseconds without blocking on network latency.

1. Google Calendar 2-Way Sync

Implemented inside app/google_calendar.py, organizers can link their Google account via OAuth 2.0 to enable automatic calendar synchronization:

OAuth 2.0 Integration Flow

Authorization Request: Organizers click "Connect Google Calendar" (/integrations/google/connect), generating an OAuth2 flow requesting the calendar.events scope.
Token Persistence: The authorization callback exchanges the auth code for access and refresh tokens. Refresh tokens are immediately encrypted with AES-256 Fernet before being written to the database.
Automatic Token Refreshing: When an access token expires, the application automatically requests fresh credentials using Google's Request() handler and stores the updated expiration.

Synchronization Capabilities

1. Event Lifecycle

Event Mirroring

Creating or updating a signup automatically creates or edits a primary Google Calendar event with title, date, location, and link.

➔ Background Sync

2. Roster Ingestion

Live Description Sync

As guests claim spots, the calendar event description dynamically updates with the live list of participant names and claimed items.

➔ Deletion Sync

3. Clean Purge

Calendar Deletion

Deleting a signup in IntelliSignup removes the corresponding event from the organizer's Google Calendar automatically.

2. Apple & Outlook iCal (.ics) Feeds

For participants and organizers using Apple Calendar, Microsoft Outlook, or local calendar applications, IntelliSignup provides standards-compliant RFC 5545 iCalendar downloads:

Event Calendar Feed (/events/<slug>/calendar.ics): Generates an event-wide invitation containing full descriptions, physical venue addresses, and public coordinator contacts.
Participant Claim Feed (/claims/<token>/calendar.ics): Generates a tailored calendar entry specifically for the individual participant, including their exact shift start/end times and claimed item notes.

3. Automated Email Engine (`mail_utils.py`)

Outbound communications are rendered using responsive HTML templates paired with plaintext fallbacks. The system catalog encompasses eight distinct operational email categories:

Email Category	Recipient	Trigger Condition	Payload & Key Action
Email Verification	New User	Account creation / resend	Time-limited cryptographic activation link (24-hour expiry).
Password Reset	User	Forgot password request	Time-limited password reset link (1-hour expiry).
Claim Confirmation	Guest Participant	Slot / item claimed	Summary of commitment, Apple/Google calendar invite, and private self-service edit link.
Organizer Claim Alert	Event Organizer	New claim submitted	Alert notifying organizer who signed up and what remaining capacity is.
Waitlist Promotion	Waitlisted Guest	Spot opened & promoted	Notice that a spot opened up, with instant confirmation and management links.
Event Update Diff	All Active Participants	Organizer edits live event	Itemized bulleted diff detailing modified times, venue shifts, or item changes.
Event Reminder	All Active Participants	Systemd timer / manual click	Timely reminder sent N hours prior to event commencement.
Organizer Broadcast	All Active Participants	Organizer broadcast tool	Custom message blast sent directly to all roster participants.

4. Systemd Reminder Worker

Rather than relying on persistent memory-heavy cron loops inside the web application, IntelliSignup leverages system-level Linux timers to execute automated reminder sweeps:

How `send_reminders.py` Operates

Python (Reminder Evaluation Logic)

def send_due_reminders(now=None):
    now = now or datetime.now()
    claims = SignupClaim.query.all()
    for claim in claims:
        event = claim.item.event
        if not event.reminder_enabled or not event.event_date or not claim.email or claim.reminder_sent_at:
            continue
        reminder_time = event.event_date - timedelta(hours=max(event.reminder_hours_before, 1))
        # Compares local timezone clock basis
        if reminder_time <= now <= event.event_date:
            if send_event_reminder(claim):
                claim.reminder_sent_at = now
                db.session.add(claim)
    db.session.commit()

🕒 Redundant Delivery Prevention

Once an email reminder is successfully delivered, claim.reminder_sent_at is permanently stamped in the database. Subsequent worker runs bypass stamped claims, guaranteeing participants never receive duplicate reminders.

5. Real-Time Email Activity Log

Every outbound email attempt is appended to instance/email_activity.log as a structured JSON record:

JSON (Audit Log Entry Example)

{
  "timestamp": "2026-09-23T12:05:14",
  "status": "sent",
  "email_type": "claim_confirmation",
  "subject": "You're signed up for Fall Volunteer Day",
  "recipients": ["volunteer@example.com"],
  "event_id": 4,
  "claim_id": 18
}

These logs populate real-time activity widgets inside the organizer's dashboard and event management consoles, providing clear visibility into delivery status, skipped addresses, and SMTP transmission errors.

6. Privacy-Preserving Analytics (`AnalyticsPageView`)

IntelliSignup avoids third-party tracking scripts (such as Google Analytics or Meta Pixels) to honor participant privacy. Instead, a lightweight internal engine records page impressions:

Anonymous Visitor Hashing: Visitors are identified by a salted SHA-256 hash combining client IP and User-Agent strings. No tracking cookies are placed on user devices.
Conversion Funnel Tracking: The system computes exact conversion metrics by contrasting total views on /events/<slug> with the volume of completed claims.
Endpoint & Temporal Metrics: Organizers can inspect daily traffic curves, peak viewing hours, and most-visited public questionnaires directly from the /analytics dashboard.