Calendar Invite Server (CIS) Briefing Document
I. Executive Summary
The Calendar Invite Server (CIS) is a robust, serverless application built on AWS that automates the creation, management, tracking, and communication of calendar invitations.
We refer to this as the Calendar Invite Messaging pipeline.
It features a Vue.js front end, showcased by Calendarsnack.com, and an AWS Backend.
The system handles the entire lifecycle of an event, from initial invitation and RSVP tracking to updates and cancellations, ensuring efficient and scalable event management.
A key aspect of CIS is its reliance on email-based data injection and notification, leveraging iCal format for calendar events and reports. The platform is designed with a strong emphasis on security, data integrity, and automated CI/CD processes.
See the NFL Demo Site as a fully built-out Calendar Invite Messaging Pipeline built around the NFL Game Schedule. It’s super cool!
Mini Site for NFL Demo https://nfl2025.31events.com
II. Key Components and Architecture
The Calendar Invite Server is fundamentally comprised of two main pieces of technology:
VUE.JS Front End: "The Front End is showcased by a Free Application called Calendarsnack.com. It is a VUE app that connects to the calendar invite server, a set of APIs, and Workflows built on AWS Serverless for the Calendar Invite Server."
AWS Backend: This is a serverless stack that forms the core of the CIS, managing all event logic, data storage, and communication.
A. Core AWS Services Utilized
CIS heavily leverages a suite of AWS serverless technologies for its operations:
AWS Lambda: The primary compute service for executing business logic (e.g., invite verification, event updates, email processing).
Amazon DynamoDB: The NoSQL database for storing event records, attendee information, organizer statistics, and subscription details.
Amazon SQS (Simple Queue Service): Used for managing message queues, ensuring reliable and asynchronous processing of event requests, replies, updates, and cancellations.
Amazon SNS (Simple Notification Service): Facilitates publishing notifications for various event-related actions, allowing for decoupled communication between different parts of the system.
Amazon SES (Simple Email Service): Crucial for sending all outbound email communications, including calendar invites (in iCal format), updates, cancellations, and organizer notifications.
Amazon S3 (Simple Storage Service): Stores incoming email content for processing (e.g., event requests, RSVP replies, bulk invite CSVs).
AWS CodeCommit: Stores email notification templates, allowing for dynamic content and easy management of communication assets.
AWS IAM Identity Center: Manages authentication and access to profiles for AWS resources.
AWS CodeBuild & GitHub Actions: Automates CI/CD workflows for efficient code deployment and infrastructure management.
B. Repository Structure
The CIS project is organized into several GitHub repositories, facilitating modular development and management:
calendar-invite-cicd/: Core infrastructure and deployment configurations.
calendar-invite-event-management/: Event processing and calendar logic.
calendar-invite-dashboard/: Dashboard UI and supporting services.
calendar-invite-shared-library/: Common shared functions and utilities.
III. Main Themes and Functionalities
CIS provides a comprehensive suite of functionalities organized around the event lifecycle.
A. Data Injection and CRUD Operations
"The Calendar Event Data is injected into the AWS Serverless stack using a custom Lambda (Lambda 1 Machine). That machine ETLs the data by taking it from a calendar invite sent to an AWS Email Box from a customer client and assigns a UID attached to the Email Name of Client, which becomes the 'Organizer'. Anytime the organizer updates the Calendar Client, the data is updated in the Calendar Invite Server and to anyone who has received the calendar invite from the Calendar Invite Server."
This highlights a core design principle: email-centric data input. All CRUD (Create, Read, Update, Delete) operations on event data are primarily triggered by emails (calendar invites, replies, updates, cancellations) sent to an AWS Email Box.
B. Event Lifecycle Management
CIS automates and manages all stages of an event:
Event Creation:
Get New Event Request from Email: Processes event creation requests received via email (iCal).
Create New Event Record: Validates the organizer, stages event data, stores it in DynamoDB, and publishes SNS notifications. This includes checks for organizer authorization, account suspension, and event limits.
Notify Organizer of Successful Event Creation: Sends a confirmation email to the organizer upon successful event registration.
Notify Organizer of Failed Event Creation: Informs the organizer if an attempt to create an event fails.
Invitation Management:
Verify New Event Invite Request: Validates the organizer's status, invite limits, and potential restrictions before sending invitations.
Send Event Invite: Processes and sends individual iCal calendar invitations via SES, tracking invitee details and updating event statistics.
Send Bulk Event Invites: Handles large-scale event invitations by processing requests from SQS, sending invites via SES, and updating event statistics.
Get New Bulk Event Invites from Email: Extracts attendee details from attached CSV files in emails, validates the sender, and queues valid invites.
Get New Event Invite from API: Processes event invite requests from external API sources, validates the data, and queues them via SNS.
Event Updates:
Update Event: Modifies existing event details in DynamoDB and publishes SNS notifications for changes.
Stage Attendees for Updated Event: Identifies and queues update notifications for all attendees of an updated event.
Send Event Update: Generates and sends iCal-formatted update emails to attendees via SES.
Event Cancellations:
Cancel Event Function: Marks events as canceled in DynamoDB and triggers notifications.
Stage Attendees for Cancelled Event: Identifies and queues cancellation notifications for all attendees of a canceled event.
Send Event Cancellation: Generates and sends iCal-formatted cancellation emails to attendees via SES.
RSVP & Attendee Management:
Get New Event Reply from Email: Processes RSVP responses received via email (iCal), extracts details, and publishes SNS notifications for status updates.
Update Event Attendee Record: Updates attendee RSVP statuses (accepted, declined, tentative) in DynamoDB based on responses, and modifies event statistics.
Get Event Attendee Report: Generates a CSV report of attendees for a given event and emails it to the organizer.
Get Event Attendee Sanitized List: Retrieves attendee lists, redacting PII (e.g., johndoe@example.com -> j*******@example.com, John Doe -> J*******) for privacy compliance.
C. Organizer-Specific Functionality
Get Organizer Events: Retrieves all events associated with a specific organizer. A legacy version (Get Organizer Events (Legacy)) is also mentioned, distinguishing between the path parameter and the request body for extracting organizer emails.
Notify Organizer of Event Limit Reached: Optional feature to inform organizers when they have reached their event creation limit.
Notify Organizer of Successful Enrollment: "While not a core function of the Calendar Invite Server (CIS), it provides an automated notification mechanism when an organizer successfully enrolls via an external system such as Shopify."
D. System Administration & Security
Get System Events: Provides system administrators with access to all events across the entire CIS database, emphasizing restricted access to authorized users.
Security Considerations: Throughout the documentation, consistent mentions of:
"IAM Role Restrictions: Access is limited to authorized roles."
"Data Encryption: Ensures secure data transmission and storage."
"Access Control: Tenant-based filtering enforces data isolation."
"Subscription records should be write-protected to avoid duplicate entries."
PII sanitization for attendee lists.
E. E-Commerce Integration (Shopify)
Process Shopify Order: Automates subscription handling for purchases made via Shopify. It validates orders, registers user subscriptions in DynamoDB, and sends confirmation notifications.
IV. API Overview and Dashboard
A. CIS API Suite
The CIS exposes a RESTful API, structured into categories:
Event API: Handles event summaries, invite information, attendee reports, and event-level statistics. (e.g., GET /event/{uid})
Organizer API: Manages organizer-specific event lists and statistics. (e.g., GET /organizer/{organizer}/events)
System API: Provides administrative access to system-wide events and statistics. (e.g., GET /system/events)
Statistics API: Offers statistical insights at event, organizer, and system levels.
Order API (Shopify Integration): Processes Shopify orders. (e.g., POST /order)
B. CIS Dashboard
The CIS Dashboard acts as a central hub for managing, tracking, and processing calendar invite events. It provides tools for:
Event Management (retrieving event details, generating attendee reports, and creating sanitized lists).
Attendee and Invitation Handling (processing new invites from API).
System Administration & Security (accessing system-wide events, logging).
E-Commerce Integration (processing Shopify orders).
V. Development and Deployment (CI/CD)
The system emphasizes a structured approach for setup and management:
GitHub Repositories: Required for code management.
AWS Profile Configuration: Utilizes AWS IAM Identity Center for SSO and role assignment.
CI/CD Pipeline Integration: "GitHub Actions and AWS CodeBuild Setup" with references to sceptre-launch.yaml for infrastructure deployment.
Version Control & Branching Strategy: "Use short-lived feature branches for development. All changes must be committed through Pull Requests (PRs). PRs trigger GitHub Actions for linting and testing."
Deployment Workflow: Uses Git tagging (git tag -am "Release vX.x.x" X.x.x and git push origin X.x.x) to trigger AWS CodeBuild for updating the AWS Serverless Application Repository.
VI. Important Ideas/Facts
Serverless-First Approach: CIS is entirely built on AWS Serverless technologies, enabling scalability, cost-effectiveness, and reduced operational overhead.
Email as a Primary Interface: Event data injection, updates, cancellations, and RSVP replies are primarily initiated via email (iCal format), sent to an AWS Email Box. This is a unique and central design choice.
Automated Event Lifecycle: The system automates nearly every aspect of event management, from initial creation and invitation sending to handling RSVPs, updates, and cancellations.
Robust Error Handling and Logging: Across all functions, there is a consistent emphasis on "Exception Logging: Logs errors to facilitate debugging" and the handling of specific failure cases (e.g., invalid requests, DynamoDB failures, and email sending failures). Failed SQS messages remain for retry.
Security and Privacy by Design: Features like IAM role restrictions, data encryption, tenant-based access control, and PII sanitization demonstrate a focus on security and data privacy.
Modularity: The system is broken down into distinct Lambda functions and GitHub repositories, promoting maintainability and independent deployment.
Pre-Built Notification Email Templates: CIS includes customizable HTML email templates stored in AWS CodeCommit for various notifications, emphasizing brand consistency and ease of modification.
Integration Capabilities: The system supports integration with external platforms, such as Shopify, for subscription management and provides a public API for other external sources to create event invitations.
Deprecation Strategy: The inclusion of a "Legacy" Get Organizer Events function highlights a forward-looking approach to API versioning and backward compatibility.
1. What is the Calendar Invite Server (CIS), and what are its core components?
The Calendar Invite Server (CIS) is a robust, serverless-based platform on AWS designed for managing, tracking, and processing calendar invitations. It consists of two main technological pieces: a VUE.JS Front End (showcased by a free application called Calendarsnack.com) and an AWS Backend. The backend is built on AWS Serverless architecture, utilizing services like Lambda for processing, DynamoDB for data storage, SQS and SNS for messaging and notifications, SES for email communication, and S3 for data storage. The CIS acts as a central hub for event data, offering comprehensive capabilities across event creation, management, invitations, cancellations, updates, and attendee tracking.
2. How does the Calendar Invite Server handle the creation and updating of events?
The CIS manages event creation and updates through a structured workflow. For new events, data is injected into the AWS Serverless stack via a custom Lambda function (Lambda 1 Machine). This function ETLs (Extracts, Transforms, Loads) data from calendar invites sent to an AWS Email Box. It assigns a unique ID (UID) to the email sender, who becomes the "Organizer." The Create New Event Record function validates the organizer, stages the event, stores it in DynamoDB, and triggers SNS notifications for creation or updates. For existing events, the Update Event function modifies event details in DynamoDB, increments the event sequence number, and publishes update notifications to SNS. This ensures that any changes made by the organizer are reflected across the system and communicated to attendees.
3. What mechanisms are in place for managing event invitations and attendee responses?
The CIS provides comprehensive mechanisms for managing event invitations and attendee responses. The Send Event Invite function processes and sends individual iCal invitations via AWS SES, updating attendee records and event statistics in DynamoDB. For larger-scale events, the Send Bulk Event Invites function handles mass invitations, processing attendee details from attached CSV files, validating sender authorization, and queuing invites for sending. Attendee responses (RSVPs) received via email are processed by the 'Get New Event Reply from Email' function, which extracts event details, formats the response, and uses SNS to update the event's status. The Update Event Attendee Record function then accurately reflects these RSVP changes in DynamoDB, ensuring event participation status and statistics are maintained.
4. How does the Calendar Invite Server handle event cancellations and updates for attendees?
When an event is cancelled or updated, the CIS ensures all affected attendees are promptly notified. The Cancel Event Function marks an event as "canceled" in DynamoDB and publishes a cancellation notification via SNS. Similarly, the Update Event function records changes to event details in DynamoDB and triggers notifications. To manage these notifications, the Stage Attendees for Updated Event and Stage Attendees for Cancelled Event functions are responsible for identifying all attendees for an updated or cancelled event, respectively. These functions then queue specific update or cancellation notifications for processing, which are subsequently sent out via AWS SES by the Send Event Update and Send Event Cancellation functions, using properly formatted iCal updates or cancellation notices.
5. The Calendar Invite Server primarily utilizes what AWS services, and why?
The Calendar Invite Server heavily leverages a suite of AWS services to achieve its serverless and scalable architecture:
AWS Lambda: For executing event-driven code without provisioning servers, powering all the individual functions like creating events, sending invites, and processing replies.
Amazon DynamoDB: As a NoSQL database for high-performance storage and retrieval of event records, attendee data, and organizer statistics, due to its scalability and low latency.
Amazon SQS (Simple Queue Service): For reliable message queuing, enabling asynchronous processing of event requests, replies, updates, and cancellations, ensuring messages are not lost and can be retried.
Amazon SNS (Simple Notification Service): For fan-out messaging and notifications, allowing multiple downstream services to be triggered by a single event (e.g., a new event creation triggering various notification and processing steps).
Amazon SES (Simple Email Service): For cost-effective and scalable email sending, used for delivering calendar invites, updates, cancellations, and various organizer notifications.
Amazon S3 (Simple Storage Service): For storing static content like email templates and incoming email files containing event data or CSV attachments for bulk invites.
AWS CodeBuild & GitHub Actions: For automating CI/CD workflows, facilitating continuous integration and deployment of the application.
AWS IAM Identity Center: For managing authentication and profile access, ensuring secure access to AWS resources.
AWS CodeCommit: For storing email notification templates, allowing for easy modification and version control of these templates.
These services together provide a highly available, scalable, and cost-efficient infrastructure for the CIS.
6. How does the CIS ensure data privacy and security, especially concerning attendee information?
The CIS incorporates several measures to ensure data privacy and security. Access to sensitive functions, such as Get System Events (which retrieves all system-wide event data), is strictly restricted to system administrators or authorized users through IAM roles and API Gateway authentication. For attendee data, the Get Event Attendee Sanitized List function is specifically designed to retrieve attendee lists while redacting personally identifiable information (PII). This function masks email addresses (e.g., johndoe@example.com becomes j*******@example.com) and obfuscates attendee names (e.g., John Doe becomes J*******), allowing organizers to analyze data without compromising individual privacy. Additionally, IAM policies are crucial for restricting access to DynamoDB and SNS, thereby preventing unauthorized modifications or data exposure. All processes include extensive logging for auditing and security monitoring, and data encryption is utilized for secure transmission and storage of sensitive data.
7. What administrative and integration capabilities does the CIS Dashboard offer?
The CIS Dashboard serves as a central hub for administrators and authorized users, providing comprehensive tools for event management, tracking, and integration with external services. Key administrative capabilities include:
Event Management: Functions like Get Event Attendee Report (generates and emails CSV reports), Get Event Attendee Sanitized List (returns privacy-compliant attendee data), Get Organizer Events (retrieves events for a specific organizer), and Get System Events (provides system-wide event visibility for administrators).
System Administration & Security: Features like Get System Events ensure oversight, and the system is integrated with AWS logging for auditing. Access control is managed through IAM roles, restricting sensitive operations.
E-Commerce Integration: The Shopify Order function enables the automation of subscription handling for purchases made via Shopify, including order validation, subscription registration, and user enrollment, thereby enhancing the user experience for subscription-based services.
API Integration: The 'Get New Event Invite from API' function enables external sources to process new event invites, validating the data and queuing them for further handling, thereby supporting broader ecosystem integration.
These capabilities ensure efficient management, robust security, and seamless integration with other platforms.
8. How does the CIS handle errors and ensure reliability in its event processing workflows?
The CIS is designed with robust error handling and reliability mechanisms throughout its event processing workflows. A key aspect is the use of AWS SQS queues, which manage messages for various event-related requests. If an error occurs during the processing of an SQS message by a Lambda function (e.g., invalid data, a service failure), the message is not immediately deleted from the queue. Instead, it remains in SQS for automatic retry, preventing data loss and allowing for transient issues to resolve. Each function also includes:
Exception Logging: Detailed errors are consistently logged (e.g., to AWS CloudWatch) to facilitate debugging and issue resolution, while protecting sensitive information in responses.
Validation Checks: Functions perform extensive validation on incoming requests (e.g., checking for valid email formats, UIDs, and organizer authorization, as well as invite limits) to prevent the processing of malformed or unauthorized requests. Invalid requests are often logged and skipped or result in specific error notifications.
Notification of Failures: Organizers are notified of failures, such as Notify Organizer of Failed Event Creation or if email sending fails. However, these failures typically do not halt the overall CIS functionality.
Conditional Updates: DynamoDB operations often use conditional checks (e.g., preventing duplicate entries during subscription registration or ensuring an event isn't already canceled before updating its status) to maintain data integrity.
Cleanup Mechanisms: Successfully processed SQS messages are explicitly deleted to prevent reprocessing, and temporary files (such as CSV reports) are cleaned up to avoid storage issues.
APIS
Visualization of Pipeline by the Numbers
NFL Game Demo using the Stack
