# rodrighons/notifier architecture

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

- Interactive diagram: https://gitdiagram.com/rodrighons/notifier
- Repository: https://github.com/rodrighons/notifier

## Overview

##### Project Type & Purpose
- This is a mountable Rails Engine (gem) designed to be plugged into any Rails application.
- Purpose: allow a host app to enqueue and process notifications via configurable channels (e.g. email).
- Key use‐case: host app calls Notifier::BirthNotification.send(:email,…), which creates and processes notifications in the background.

##### File‐Structure Analysis
Top‐level:
- bin/, config/, lib/, app/, db/: standard Rails engine layout.
- app/controllers/notifier, app/models/notifier, app/services/notifier, app/jobs/notifier, app/mailers/notifier: namespaced MVC + service + job layers.
- lib/notifier/engine.rb: defines the mountable engine.
- test/dummy/: a full Rails app used for development/testing only.

##### README Insights
- Confirms mountable engine, Rails ≥8, Ruby ≥3.4, PostgreSQL.
- Explains basic API (send notifications, query channels).
- Background jobs (ActiveJob) handle creation and delivery.
- External dependency: mail delivery (SMTP or 3rd-party).

##### Main Architectural Components
a. Host Rails Application
– Initiates notification requests via engine API.
– Mounts the engine’s routes (config/routes.rb inside engine).
b. Notifier Engine
– Controllers & Views: optional admin UI to manage channels/notifications.
– Models (Notifier::EmailChannel, Notifier::EmailNotification): store configuration & state.
– Services:
- NotificationProcessor (orchestrates channel lookup and enqueueing).
- EmailProcessor (handles delivery logic).
- Domain‐specific services (e.g. BirthNotification).
– Jobs:
- NotificationCreationJob: creates DB records and links to channels.
- NotificationDeliveryJob (if separate) or processed by EmailProcessor via ActiveJob.
– Mailers: Notifier::ApplicationMailer for templating and sending.
– Engine Mount: defined in lib/notifier/engine.rb to isolate namespace and assets.
c. Infrastructure
– Database (PostgreSQL): stores channels, notifications.
– Background Job Queue (e.g. Sidekiq, DelayedJob, or default ActiveJob adapter).
– External Mail Service (SMTP relay, SendGrid, etc.).
d. Development/Test Environment
– test/dummy Rails app: not in production, but useful to show “engine → host app” integration.

1. Host App → calls Notifier API → Rails Engine
2. Engine’s NotificationProcessor enqueues NotificationCreationJob → Job Queue
3. Worker picks up NotificationCreationJob → creates Notifier::EmailNotification record in DB
4. Engine’s EmailProcessor (another job or invoked after creation) → renders email via Notifier::ApplicationMailer → sends to External Mail Service
5. Status updates flow back into DB (e.g. “created”, “sent”, “failed”)
6. Admin UI (optional): browser ↔ Notifier controllers/views for channel & notification management

##### Architectural Patterns & Principles
- Mountable Engine pattern (isolated namespace, asset pipeline)
- MVC separation for UI management of channels/notifications
- Service objects for business logic (single responsibility)
- Background jobs for decoupling and scalability (ActiveJob)
- Domain layering: Controllers → Services → Jobs → Models → External services
- Configuration by convention: default channel, pluggable channels via AbstractChannel

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Host Application" 
    HostApp["Host Rails App"]:::host
  end

  subgraph "Notifier Engine" 
    subgraph "Engine Setup"
      EngineEntry["lib/notifier.rb"]:::code
      EngineVersion["lib/notifier/version.rb"]:::code
      EngineDef["lib/notifier/engine.rb"]:::code
      Routes["config/routes.rb"]:::code
      RakeTasks["lib/tasks/notifier_tasks.rake"]:::code
    end

    subgraph "MVC (Admin UI)"
      AppCtrl["app/controllers/notifier/application_controller.rb"]:::mvc
      EmailChanCtrl["app/controllers/notifier/email_channels_controller.rb"]:::mvc
      EmailNotCtrl["app/controllers/notifier/email_notifications_controller.rb"]:::mvc
      ViewsLayout["app/views/layouts/notifier/application.html.erb"]:::mvc
      ViewsChan["app/views/notifier/email_channels/"]:::mvc
      ViewsNot["app/views/notifier/email_notifications/"]:::mvc
    end

    subgraph "Models"
      AppRecord["app/models/notifier/application_record.rb"]:::model
      AbstractChan["app/models/notifier/abstract_channel.rb"]:::model
      AbstractNot["app/models/notifier/abstract_notification.rb"]:::model
      EmailChanModel["app/models/notifier/email_channel.rb"]:::model
      EmailNotModel["app/models/notifier/email_notification.rb"]:::model
    end

    subgraph "Services"
      NotificationProcessor["app/services/notifier/notification_processor.rb"]:::service
      EmailProcessor["app/services/notifier/email_processor.rb"]:::service
      BirthNotification["app/services/notifier/birth_notification.rb"]:::service
    end

    subgraph "Jobs"
      ApplicationJob["app/jobs/notifier/application_job.rb"]:::job
      NotificationCreationJob["app/jobs/notifier/notification_creation_job.rb"]:::job
    end

    subgraph "Mailer"
      ApplicationMailer["app/mailers/notifier/application_mailer.rb"]:::mailer
    end

    subgraph "DB Migrations"
      Migration1["db/migrate/20250929045930_create_notifier_email_notifications.rb"]:::code
      Migration2["db/migrate/20250929052835_create_notifier_email_channels.rb"]:::code
      Migration3["db/migrate/20250930020014_add_channel_to_notifier_abstract_notifications.rb"]:::code
    end
  end

  subgraph "Infrastructure"
    JobQueue["Background Job Queue"]:::infra
    PostgresDB["PostgreSQL DB"]:::db
    ExternalMail["External Mail Service"]:::external
  end

  subgraph "Development/Test Environment"
    TestDummy["test/dummy/"]:::test
    FixturesChan["test/fixtures/notifier/email_channels.yml"]:::test
    FixturesNot["test/fixtures/notifier/email_notifications.yml"]:::test
  end

  HostApp -->|"mounts at /notifier"| EngineDef
  HostApp -->|"calls API"| NotificationProcessor
  NotificationProcessor -->|"enqueue job"| NotificationCreationJob
  NotificationCreationJob -->|"writes record"| EmailNotModel
  NotificationCreationJob -->|"writes record"| EmailChanModel
  NotificationCreationJob -->|"queues delivery"| EmailProcessor
  EmailProcessor -->|"uses mailer"| ApplicationMailer
  ApplicationMailer -->|"sends email"| ExternalMail
  NotificationCreationJob -->|"writes"| PostgresDB
  EmailNotModel -->|"status updates"| PostgresDB
  EmailChanModel -->|"config stored"| PostgresDB
  NotificationProcessor -->|"uses"| AbstractChan
  NotificationProcessor -->|"uses"| AbstractNot
  HostApp -->|"UI access"| AppCtrl
  AppCtrl -->|"renders layout"| ViewsLayout
  AppCtrl -->|"manages"| EmailChanCtrl
  AppCtrl -->|"manages"| EmailNotCtrl
  EmailChanCtrl -->|"CRUD"| EmailChanModel
  EmailNotCtrl -->|"CRUD"| EmailNotModel
  TestDummy -->|"mounts engine"| EngineEntry

  click EngineEntry "https://github.com/rodrighons/notifier/blob/main/lib/notifier.rb"
  click EngineVersion "https://github.com/rodrighons/notifier/blob/main/lib/notifier/version.rb"
  click EngineDef "https://github.com/rodrighons/notifier/blob/main/lib/notifier/engine.rb"
  click Routes "https://github.com/rodrighons/notifier/blob/main/config/routes.rb"
  click RakeTasks "https://github.com/rodrighons/notifier/blob/main/lib/tasks/notifier_tasks.rake"
  click AppCtrl "https://github.com/rodrighons/notifier/blob/main/app/controllers/notifier/application_controller.rb"
  click EmailChanCtrl "https://github.com/rodrighons/notifier/blob/main/app/controllers/notifier/email_channels_controller.rb"
  click EmailNotCtrl "https://github.com/rodrighons/notifier/blob/main/app/controllers/notifier/email_notifications_controller.rb"
  click ViewsLayout "https://github.com/rodrighons/notifier/blob/main/app/views/layouts/notifier/application.html.erb"
  click ViewsChan "https://github.com/rodrighons/notifier/tree/main/app/views/notifier/email_channels/"
  click ViewsNot "https://github.com/rodrighons/notifier/tree/main/app/views/notifier/email_notifications/"
  click AppRecord "https://github.com/rodrighons/notifier/blob/main/app/models/notifier/application_record.rb"
  click AbstractChan "https://github.com/rodrighons/notifier/blob/main/app/models/notifier/abstract_channel.rb"
  click AbstractNot "https://github.com/rodrighons/notifier/blob/main/app/models/notifier/abstract_notification.rb"
  click EmailChanModel "https://github.com/rodrighons/notifier/blob/main/app/models/notifier/email_channel.rb"
  click EmailNotModel "https://github.com/rodrighons/notifier/blob/main/app/models/notifier/email_notification.rb"
  click NotificationProcessor "https://github.com/rodrighons/notifier/blob/main/app/services/notifier/notification_processor.rb"
  click EmailProcessor "https://github.com/rodrighons/notifier/blob/main/app/services/notifier/email_processor.rb"
  click BirthNotification "https://github.com/rodrighons/notifier/blob/main/app/services/notifier/birth_notification.rb"
  click ApplicationJob "https://github.com/rodrighons/notifier/blob/main/app/jobs/notifier/application_job.rb"
  click NotificationCreationJob "https://github.com/rodrighons/notifier/blob/main/app/jobs/notifier/notification_creation_job.rb"
  click ApplicationMailer "https://github.com/rodrighons/notifier/blob/main/app/mailers/notifier/application_mailer.rb"
  click Migration1 "https://github.com/rodrighons/notifier/blob/main/db/migrate/20250929045930_create_notifier_email_notifications.rb"
  click Migration2 "https://github.com/rodrighons/notifier/blob/main/db/migrate/20250929052835_create_notifier_email_channels.rb"
  click Migration3 "https://github.com/rodrighons/notifier/blob/main/db/migrate/20250930020014_add_channel_to_notifier_abstract_notifications.rb"
  click FixturesChan "https://github.com/rodrighons/notifier/blob/main/test/fixtures/notifier/email_channels.yml"
  click FixturesNot "https://github.com/rodrighons/notifier/blob/main/test/fixtures/notifier/email_notifications.yml"
  click TestDummy "https://github.com/rodrighons/notifier/tree/main/test/dummy/"

  classDef host fill:#D0E6FF,stroke:#0366D6,color:#0366D6
  classDef engine fill:#E6FFED,stroke:#28A745,color:#28A745
  classDef mvc fill:#FFF5E6,stroke:#FF8C00,color:#FF8C00
  classDef model fill:#F0F0F0,stroke:#6E6E6E,color:#6E6E6E
  classDef service fill:#FFFBE6,stroke:#FFD33D,color:#8A6D3B
  classDef job fill:#FFE6F0,stroke:#D63384,color:#D63384
  classDef mailer fill:#E6F7FF,stroke:#17A2B8,color:#117A8B
  classDef infra fill:#F2F2F2,stroke:#6C757D,color:#6C757D
  classDef db fill:#E9ECEF,stroke:#ADB5BD,color:#495057
  classDef external fill:#FFF3CD,stroke:#856404,color:#856404
  classDef test fill:#F8E6FF,stroke:#6F42C1,color:#6F42C1
  classDef code fill:#ECECEC,stroke:#343A40,color:#343A40
```
