# jaredwray/airhorn architecture

> Architecture diagram of the GitHub repository jaredwray/airhorn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jaredwray/airhorn
- Repository: https://github.com/jaredwray/airhorn

## Overview

##### Main Components
- Core API & Notification Functions: Represented by the main file (airhorn.ts) that exposes key functions like send(), sendSMTP(), sendSMS(), sendWebhook(), and sendMobilePush().
- Provider Service & Strategy Layer: Modules in src (such as provider-service.ts and provider-type.ts) coordinate the selection and execution of the correct notification provider.
- Provider Implementations: The src/providers subdirectory contains individual modules for each cloud service (aws-ses, aws-sms, aws-sns, firebase-messaging, twilio-sendgrid, twilio-sms, webhook). These can be shown as individual “provider” components.
- Template Management:
– Template Service (src/template-service.ts and template-sync.ts): Handles template loading, rendering, and possibly synchronization between file system and a database.
– Template Provider Abstraction: Noted by template-providers (with an in-memory version in memory.ts, and a MongoDB-based one in mongo.ts) to abstract how templates are fetched.

##### Relationships and Interactions
- Optionally, include a “Template Provider” abstraction that can use either the in-memory or database-backed (MongoDB/Postgres) implementation as configured via Airhorn options.

##### Architectural Patterns & Design Principles
- Use of the Strategy Pattern for selecting among different provider implementations.
- Loose coupling between the core API and provider implementations (achieved through abstraction over provider types and template providers).
- The modularized design in “src” (with dedicated directories for providers and template providers) emphasizes separation of concerns.
- The file system-based templating (as outlined in the README) is a key design aspect, so emphasize the structure (templates folder structure in test/templates can serve as an example).

##### Relevant Technologies and Frameworks
- Node.js (ESM with TypeScript): The project is built as an ESM module with the latest Node.js features.
- Cloud Services: AWS (SES, SMS, SNS), Twilio (Sendgrid, SMS), Firebase (Messaging) are critical external integrations.
- Template Engines: While not explicitly shown in code, the README mentions support for EJS, Handlebars, etc.
- CI/CD Integration: GitHub Actions, Docker (docker-compose.yml) are used to streamline testing and deployment.

##### Final Assembly
- Every component is labeled and its role clearly described—don’t skip over details such as error-handling flows or fallback mechanisms if applicable (active/passive fail over mentioned in the README for multiple providers).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Component
    AirhornCore["Airhorn Core"]:::core
    click AirhornCore "https://github.com/jaredwray/airhorn/blob/main/src/airhorn.ts"

    %% Template Management Subgraph
    subgraph "Template Management"
        TemplateService["Template Service"]:::template
        click TemplateService "https://github.com/jaredwray/airhorn/blob/main/src/template-service.ts"
        TemplateSync["Template Sync"]:::template
        click TemplateSync "https://github.com/jaredwray/airhorn/blob/main/src/template-sync.ts"
        TemplateFile["Template File Handling"]:::template
        click TemplateFile "https://github.com/jaredwray/airhorn/blob/main/src/template.ts"
        subgraph "Template Provider Abstraction"
            TemplateMemory["In-Memory Provider"]:::template
            click TemplateMemory "https://github.com/jaredwray/airhorn/blob/main/src/template-providers/memory.ts"
            TemplateMongo["MongoDB Provider"]:::template
            click TemplateMongo "https://github.com/jaredwray/airhorn/blob/main/src/template-providers/mongo.ts"
        end
        TemplateService -->|"uses"| TemplateMemory
        TemplateService -->|"uses"| TemplateMongo
    end

    %% Provider Layer Subgraph
    subgraph "Provider Layer"
        ProviderService["Provider Service"]:::provider
        click ProviderService "https://github.com/jaredwray/airhorn/blob/main/src/provider-service.ts"
        ProviderType["Provider Type"]:::provider
        click ProviderType "https://github.com/jaredwray/airhorn/blob/main/src/provider-type.ts"
    end

    %% High-level Flow from Core
    AirhornCore -->|"load/render"| TemplateService
    AirhornCore -->|"select-provider"| ProviderService
    ProviderService -->|"choose"| ProviderType

    %% Provider Implementations Subgraph
    subgraph "Provider Implementations"
        subgraph "AWS Providers"
            AWSSes["AWS SES"]:::provider
            click AWSSes "https://github.com/jaredwray/airhorn/blob/main/src/providers/aws-ses.ts"
            AWSSms["AWS SMS"]:::provider
            click AWSSms "https://github.com/jaredwray/airhorn/blob/main/src/providers/aws-sms.ts"
            AWSSns["AWS SNS"]:::provider
            click AWSSns "https://github.com/jaredwray/airhorn/blob/main/src/providers/aws-sns.ts"
        end
        subgraph "Twilio Providers"
            TwilioSendgrid["Twilio Sendgrid"]:::provider
            click TwilioSendgrid "https://github.com/jaredwray/airhorn/blob/main/src/providers/twilio-sendgrid.ts"
            TwilioSMS["Twilio SMS"]:::provider
            click TwilioSMS "https://github.com/jaredwray/airhorn/blob/main/src/providers/twilio-sms.ts"
        end
        FirebaseMessaging["Firebase Messaging"]:::provider
        click FirebaseMessaging "https://github.com/jaredwray/airhorn/blob/main/src/providers/firebase-messaging.ts"
        Webhook["Webhook"]:::provider
        click Webhook "https://github.com/jaredwray/airhorn/blob/main/src/providers/webhook.ts"
    end

    %% Connections from Provider Type to Specific Providers
    ProviderType -->|"aws-ses"| AWSSes
    ProviderType -->|"aws-sms"| AWSSms
    ProviderType -->|"aws-sns"| AWSSns
    ProviderType -->|"firebase"| FirebaseMessaging
    ProviderType -->|"twilio-sendgrid"| TwilioSendgrid
    ProviderType -->|"twilio-sms"| TwilioSMS
    ProviderType -->|"webhook"| Webhook

    %% External Cloud Services
    AWSCloud["AWS Cloud"]:::external
    TwilioCloud["Twilio Cloud"]:::external
    FirebaseCloud["Firebase Cloud"]:::external
    WebhookService["Webhook Endpoint"]:::external

    AWSSes -->|"integrates"| AWSCloud
    AWSSms -->|"integrates"| AWSCloud
    AWSSns -->|"integrates"| AWSCloud
    TwilioSendgrid -->|"integrates"| TwilioCloud
    TwilioSMS -->|"integrates"| TwilioCloud
    FirebaseMessaging -->|"integrates"| FirebaseCloud
    Webhook -->|"integrates"| WebhookService

    %% Testing and CI/CD Components
    Testing["Automated Tests (test folder)"]:::test
    click Testing "https://github.com/jaredwray/airhorn/tree/main/test"
    CICD["CI/CD Workflows (.github/workflows)"]:::test
    click CICD "https://github.com/jaredwray/airhorn/tree/main/.github/workflows"
    AirhornCore --- Testing
    AirhornCore --- CICD

    %% Styles
    classDef core fill:#f9d9ff,stroke:#333,stroke-width:2px;
    classDef provider fill:#fff3b0,stroke:#333,stroke-width:2px;
    classDef template fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef external fill:#ffd1d1,stroke:#333,stroke-width:2px;
    classDef test fill:#e6ccff,stroke:#333,stroke-width:2px;
```
