Technical Architecture

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].

Architectural 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:

• Frontend: The user-facing component residing within the TRMNL e-ink device ecosystem. It consists of custom HTML/Liquid templates that adhere to TRMNL's design system, providing responsive layouts for full-screen, half-screen, and quadrant views.
• Backend: Implemented using AWS Serverless technologies, specifically AWS Lambda functions orchestrated by API Gateway in the eu-west-2 region. This serverless approach allows for automatic scaling and cost-efficiency.
• Database: Supabase is used to store persistent user settings, such as preferred city, country, prayer calculation method, time format, Asr method, and Maghrib offset.
• External Data Source: The Aladhan Prayer Times API serves as the primary source for accurate worldwide prayer time data and Hijri date information.
• Language & Utilities: The entire backend is developed in TypeScript, leveraging date-fns and date-fns-tz for robust, timezone-aware date and time manipulations.

Component Relationship Diagram

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)

Project Structure Philosophy

The codebase adheres to a modular structure where each functional handler is self-contained. This design choice offers several benefits:

• Cohesion: All files pertinent to a specific feature (e.g., installation, prayer times retrieval, settings management) are grouped within their own directory.
• Discoverability: Developers can easily locate all components related to a particular function, simplifying navigation and understanding.
• Modularity: Each handler operates as an independent unit, promoting clear separation of concerns.
• Maintainability: Changes or updates to a feature are localized to a single module, reducing the risk of unintended side effects across the system.

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).

TRMNL Plugin Lifecycle

The plugin fully implements the TRMNL plugin lifecycle, covering both installation and uninstallation, and managing user-specific configurations.

Installation Flow

The installation process is a robust OAuth-like flow ensuring secure integration and user control:

1. Installation Request: A user initiates the plugin installation from their TRMNL dashboard. The TRMNL platform sends a request to the plugin's designated /install endpoint. This request includes a unique authorization code and a callback URL for redirection.
2. Token Exchange: The backend's 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.
3. Redirect: Upon successful token exchange, the backend redirects the user's browser back to the TRMNL platform using the provided callback URL, completing the OAuth handshake from the user's perspective.
4. Success Webhook: TRMNL sends a server-to-server webhook to the plugin's 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.
5. Plugin Configuration: After installation, the user can access a management interface within TRMNL. TRMNL directs the user to the plugin's /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.
6. Markup Generation: When the plugin is added to a TRMNL playlist or viewed on a device, the TRMNL platform periodically makes a POST request to the plugin's /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.

Uninstallation Flow

The uninstallation process is designed to cleanly remove user data and gracefully disconnect the plugin:

1. Uninstallation Webhook: When a user uninstalls the plugin from their TRMNL dashboard, the TRMNL platform sends a webhook to the plugin's /uninstall endpoint. This webhook includes the user's unique UUID.
2. Data Cleanup: The backend's 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.
3. Confirmation: The backend returns a success response to TRMNL, confirming that the uninstallation and data cleanup were completed.