The TRMNL Salah Prayer Times Plugin is designed with a modern, serverless architecture that prioritizes scalability, efficiency, and ease of maintenance. This section details the core components, thei
The TRMNL Salah Prayer Times Plugin is designed with a modern, serverless architecture that prioritizes scalability, efficiency, and ease of maintenance. This section details the core components, their interactions, and the lifecycle of the plugin within the TRMNL ecosystem. For a high-level overview of the plugin's features and functionality, please refer to the [TRMNL Salah Prayer Times Plugin Overview].
The plugin utilizes a serverless backend hosted on AWS, a PostgreSQL-compatible database (Supabase), and integrates directly with the TRMNL platform's frontend capabilities. This setup ensures that prayer times are calculated and displayed accurately and efficiently, globally.
Key Components:
eu-west-2 region. This serverless approach allows for automatic scaling and cost-efficiency.date-fns and date-fns-tz for robust, timezone-aware date and time manipulations.User (TRMNL Device/Dashboard)
↓
TRMNL Platform (Plugin Management, Markup Requests, Webhooks)
↓
API Gateway (AWS)
↓
Lambda Functions (AWS - TypeScript)
├──> User Settings Service (Supabase)
└──> Prayer Times Service (Aladhan Prayer Times API)
The codebase adheres to a modular structure where each functional handler is self-contained. This design choice offers several benefits:
This structure is organized as follows:
src/handlers/: Contains individual Lambda function handlers, each in its own directory, alongside its validation schema and documentation.src/services/: Houses shared business logic that can be reused by multiple handlers (e.g., interacting with the prayer times API or Supabase).src/clients/: Provides API client instances for external services like Aladhan and TRMNL.src/controllers/: Orchestrates business logic by combining services to fulfill specific requests, often used by handlers.src/templates/: Stores the Liquid/HTML templates for different TRMNL display sizes.src/utils/: Contains common utility functions (e.g., date helpers, logging, middleware).The plugin fully implements the TRMNL plugin lifecycle, covering both installation and uninstallation, and managing user-specific configurations.
The installation process is a robust OAuth-like flow ensuring secure integration and user control:
/install endpoint. This request includes a unique authorization code and a callback URL for redirection.installation-handler receives the request. It then securely exchanges the provided code for an access token with the TRMNL OAuth endpoint using the plugin's client ID and secret.callback URL, completing the OAuth handshake from the user's perspective.installation-success endpoint, notifying the backend that the installation was successful. This webhook includes essential user information (e.g., UUID, name, email, timezone). The backend can store this initial user data in Supabase if needed, though for this plugin, specific settings are configured later./manage endpoint, which renders an HTML form (generated by the plugin-management-handler) allowing the user to configure settings such as city, country, calculation method, time format, etc. These settings are then saved to Supabase via the /save-settings endpoint./plugin-markup endpoint. This endpoint, handled by the plugin-markup-handler, retrieves the user's saved settings from Supabase, fetches current prayer times from the Aladhan API, processes the appropriate Liquid template (full, half, or quadrant view), and returns the generated HTML markup for display on the e-ink device.The uninstallation process is designed to cleanly remove user data and gracefully disconnect the plugin:
/uninstall endpoint. This webhook includes the user's unique UUID.uninstallation-handler receives this webhook. It then performs a lookup in Supabase using the user_uuid and deletes all associated user settings and data from the database.