From 2f50da924e82bb60d0bc3303695847c9128b2ac9 Mon Sep 17 00:00:00 2001 From: Andres Contreras Date: Wed, 11 Feb 2026 10:15:12 +0100 Subject: [PATCH] docs: add professional README with unified template (#5) Standardize README.md with a consistent template including CI badge, features, installation, quick start, configuration, and documentation sections. Add paths-ignore to ci.yml to skip CI for docs-only changes. --- .github/workflows/ci.yml | 19 ++- README.md | 293 ++++++++------------------------------- 2 files changed, 74 insertions(+), 238 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b9093b6..9567aee 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,8 +2,22 @@ name: CI on: push: branches: [develop] + paths-ignore: + - '**.md' + - 'docs/**' + - 'tutorials/**' + - 'examples/**/README.md' + - 'LICENSE' + - '.gitignore' pull_request: branches: [develop, main] + paths-ignore: + - '**.md' + - 'docs/**' + - 'tutorials/**' + - 'examples/**/README.md' + - 'LICENSE' + - '.gitignore' workflow_dispatch: inputs: triggered-by: @@ -13,10 +27,5 @@ on: jobs: build: uses: fireflyframework/.github/.github/workflows/java-ci.yml@main - permissions: - packages: read - contents: read - actions: write with: java-version: '25' - secrets: inherit diff --git a/README.md b/README.md index c81beef..aa3718a 100644 --- a/README.md +++ b/README.md @@ -1,272 +1,99 @@ -# fireflyframework-notifications +# Firefly Framework - Notifications [![CI](https://github.com/fireflyframework/fireflyframework-notifications/actions/workflows/ci.yml/badge.svg)](https://github.com/fireflyframework/fireflyframework-notifications/actions/workflows/ci.yml) +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) +[![Java](https://img.shields.io/badge/Java-21%2B-orange.svg)](https://openjdk.org) +[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.x-green.svg)](https://spring.io/projects/spring-boot) -Firefly Notifications Library - A hexagonal architecture implementation for multi-channel notifications. +> Notifications core library with email, SMS, and push notification service contracts and provider abstraction. -## Overview +--- -This library provides a clean, testable notification system for email, SMS, and push notifications using **Hexagonal Architecture** (Ports and Adapters pattern). The core domain logic is completely isolated from infrastructure concerns, making it easy to swap providers, test in isolation, and maintain over time. +## Table of Contents -### Architecture Layers +- [Overview](#overview) +- [Features](#features) +- [Requirements](#requirements) +- [Installation](#installation) +- [Quick Start](#quick-start) +- [Configuration](#configuration) +- [Documentation](#documentation) +- [Contributing](#contributing) +- [License](#license) -``` -┌─────────────────────────────────────────────────────────────┐ -│ Application Layer │ -│ (EmailService, SMSService, PushService) │ -└────────────────────┬────────────────────────────────────────┘ - │ depends on - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ Domain Layer (Ports) │ -│ EmailProvider │ SMSProvider │ PushProvider │ -│ (interfaces + DTOs) │ -└─────────┬──────────────────────┬────────────────────┬───────┘ - │ │ │ - implemented by implemented by implemented by - │ │ │ - ▼ ▼ ▼ -┌──────────────────┐ ┌──────────────────┐ ┌─────────────────┐ -│ Infrastructure │ │ Infrastructure │ │ Infrastructure │ -│ (Adapters) │ │ (Adapters) │ │ (Adapters) │ -├──────────────────┤ ├──────────────────┤ ├─────────────────┤ -│ SendGrid Adapter │ │ Twilio Adapter │ │ Firebase Adapter│ -│ Resend Adapter │ │ │ │ │ -└──────────────────┘ └──────────────────┘ └─────────────────┘ -``` +## Overview -### Components +Firefly Framework Notifications provides the core service layer and provider contracts for sending email, SMS, and push notifications. It defines provider interfaces (`EmailProvider`, `SMSProvider`, `PushProvider`) that concrete notification providers implement, along with application services that orchestrate notification delivery. -#### Core Module (`fireflyframework-notifications-core`) +The module is structured as a multi-module project with a core sub-module containing the service implementations, DTOs, and provider interfaces. The notification services delegate to the appropriate provider implementation, which is supplied by separate provider modules (SendGrid, Resend, Twilio, Firebase). -**Domain Layer (Ports & DTOs):** -- `EmailProvider`, `SMSProvider`, `PushProvider` - Port interfaces defining contracts -- Request/Response DTOs for each notification type -- No infrastructure dependencies +This architecture allows applications to switch notification providers without changing business logic, as all providers implement the same standardized interfaces. -**Application Layer (Services):** -- `EmailService`, `SMSService`, `PushService` - Service interfaces and implementations -- Depend only on port interfaces, never on concrete adapters -- Contain business logic and orchestration +## Features -#### Adapter Modules (Infrastructure) +- `EmailService` with template-based email sending and attachments +- `SMSService` for SMS message delivery +- `PushService` for push notification delivery +- `EmailProvider` interface for pluggable email providers +- `SMSProvider` interface for pluggable SMS providers +- `PushProvider` interface for pluggable push notification providers +- DTOs for email requests/responses with attachment support +- DTOs for SMS requests/responses +- DTOs for push notification requests/responses +- Email status tracking enum -- **`fireflyframework-notifications-sendgrid`** - SendGrid email adapter -- **`fireflyframework-notifications-resend`** - Resend email adapter -- **`fireflyframework-notifications-twilio`** - Twilio SMS adapter -- **`fireflyframework-notifications-firebase`** - Firebase Cloud Messaging push adapter +## Requirements -Each adapter implements the corresponding port interface and handles provider-specific integration details. +- Java 21+ +- Spring Boot 3.x +- Maven 3.9+ ## Installation -Add the core library to your Spring Boot application: - -```xml path=null start=null - - org.fireflyframework - fireflyframework-notifications-core - 1.0.0-SNAPSHOT - -``` - -Then add one or more adapter libraries based on your notification needs: - -```xml path=null start=null - - - org.fireflyframework - fireflyframework-notifications-sendgrid - 1.0.0-SNAPSHOT - - - +```xml - org.fireflyframework - fireflyframework-notifications-resend - 1.0.0-SNAPSHOT - - - - - org.fireflyframework - fireflyframework-notifications-twilio - 1.0.0-SNAPSHOT - - - - - org.fireflyframework - fireflyframework-notifications-firebase - 1.0.0-SNAPSHOT + org.fireflyframework + fireflyframework-notifications + 26.01.01 ``` -See individual adapter READMEs for configuration details. - -## Configuration - -This library uses Spring Boot relaxed property binding. Both kebab-case and camelCase property names are accepted (e.g., `api-key` or `apiKey`). The examples below use kebab-case; if your service uses camelCase (as seen in some projects), it will also work. - -### Provider Selection - -If you include multiple email providers, select one using: - -```yaml path=null start=null -notifications: - email: - provider: resend # or sendgrid -``` +## Quick Start -Only the selected email provider will be instantiated. +```java +import org.fireflyframework.notifications.core.services.email.v1.EmailService; +import org.fireflyframework.notifications.interfaces.dtos.email.v1.EmailRequestDTO; -### Provider Properties - -Configure providers in your `application.yml`: - -```yaml path=null start=null -# Twilio (SMS) -twilio: - config: - account-sid: ${TWILIO_ACCOUNT_SID} - auth-token: ${TWILIO_AUTH_TOKEN} - phone-number: "+1234567890" - -# SendGrid (Email) -sendgrid: - api-key: ${SENDGRID_API_KEY} - -# Resend (Email) -resend: - api-key: ${RESEND_API_KEY} - default-from: "noreply@example.com" - # base-url: https://api.resend.com # optional; override for testing - -# Firebase (Push) -firebase: - project-id: ${FIREBASE_PROJECT_ID} - credentials-path: ${FIREBASE_CREDENTIALS_PATH} # optional; uses ADC if omitted -``` - -Notes: -- Use either kebab-case (recommended) or camelCase (e.g., `accountSid`, `authToken`, `phoneNumber`, `apiKey`, `projectId`, `credentialsPath`). Both are supported. -- Providers are conditionally loaded only when required properties are present. -- Avoid configuring more than one email provider at the same time unless `notifications.email.provider` is explicitly set. - -## Usage - -Inject the service interfaces from the core module. Spring automatically wires the adapter implementations you've added to your classpath. +@Service +public class OrderNotificationService { -### Email Example + private final EmailService emailService; -```java path=null start=null -@Service -public class UserNotificationService { - - @Autowired - private EmailService emailService; - - public void sendWelcomeEmail(String userEmail) { + public Mono sendOrderConfirmation(Order order) { EmailRequestDTO request = EmailRequestDTO.builder() - .from("noreply@example.com") - .to(List.of(userEmail)) - .subject("Welcome to Firefly") - .html("

Welcome!

Thanks for signing up.

") - .text("Welcome! Thanks for signing up.") + .to(order.getCustomerEmail()) + .subject("Order Confirmation - " + order.getId()) + .body("Your order has been confirmed.") .build(); - - emailService.sendEmail(request) - .subscribe(response -> { - if (response.isSuccess()) { - log.info("Email sent successfully: {}", response.getMessageId()); - } else { - log.error("Failed to send email: {}", response.getError()); - } - }); + return emailService.send(request); } } ``` -### SMS Example - -```java path=null start=null -@Autowired -private SMSService smsService; - -public void sendVerificationCode(String phoneNumber, String code) { - SMSRequestDTO request = SMSRequestDTO.builder() - .phoneNumber(phoneNumber) - .message("Your verification code is: " + code) - .build(); - - smsService.sendSMS(request) - .subscribe(response -> { - if (response.isSuccess()) { - log.info("SMS sent: {}", response.getMessageId()); - } - }); -} -``` - -### Push Notification Example - -```java path=null start=null -@Autowired -private PushService pushService; - -public void sendPushNotification(String deviceToken, String title, String body) { - PushNotificationRequest request = PushNotificationRequest.builder() - .token(deviceToken) - .title(title) - .body(body) - .data(Map.of("type", "alert", "priority", "high")) - .build(); - - pushService.sendPush(request) - .subscribe(response -> { - if (response.isSuccess()) { - log.info("Push sent: {}", response.getMessageId()); - } - }); -} -``` +## Configuration -## Benefits of Hexagonal Architecture +Configuration is provided by the specific notification provider module (SendGrid, Resend, Twilio, Firebase). -1. **Provider Independence**: Switch from SendGrid to Resend without changing business logic -2. **Testability**: Mock port interfaces for unit tests without touching real providers -3. **Maintainability**: Clear separation between domain logic and infrastructure -4. **Flexibility**: Add new providers by simply implementing the port interface -5. **Domain Focus**: Business logic in services depends only on abstract interfaces +## Documentation -## Testing +No additional documentation available for this project. -Test your notification logic without real providers: +## Contributing -```java path=null start=null -@Test -public void testEmailNotification() { - // Mock the port interface - EmailProvider mockProvider = mock(EmailProvider.class); - when(mockProvider.sendEmail(any())) - .thenReturn(Mono.just(EmailResponseDTO.success("test-id"))); - - EmailServiceImpl service = new EmailServiceImpl(); - service.emailProvider = mockProvider; - - // Test without touching real email infrastructure - StepVerifier.create(service.sendEmail(someRequest)) - .expectNextMatches(response -> response.isSuccess()) - .verifyComplete(); -} -``` +Contributions are welcome. Please read the [CONTRIBUTING.md](CONTRIBUTING.md) guide for details on our code of conduct, development process, and how to submit pull requests. -## Documentation +## License -For detailed architecture documentation, see [ARCHITECTURE.md](ARCHITECTURE.md). +Copyright 2024-2026 Firefly Software Solutions Inc. -For adapter-specific configuration and usage: -- [SendGrid Adapter](../fireflyframework-notifications-sendgrid/README.md) -- [Resend Adapter](../fireflyframework-notifications-resend/README.md) -- [Twilio Adapter](../fireflyframework-notifications-twilio/README.md) -- [Firebase Adapter](../fireflyframework-notifications-firebase/README.md) +Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.