fireflyframework · ancongui · Feb 11, 2026 · Feb 10, 2026 · Feb 11, 2026
diff --git 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
@@ -1,145 +1,92 @@
-# fireflyframework-notifications-twilio
+# Firefly Framework - Notifications - Twilio
 
 [![CI](https://github.com/fireflyframework/fireflyframework-notifications-twilio/actions/workflows/ci.yml/badge.svg)](https://github.com/fireflyframework/fireflyframework-notifications-twilio/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)
 
-Twilio SMS adapter for Firefly Notifications Library.
+> Twilio SMS adapter for Firefly Notifications.
 
-## Overview
-
-This module is an **infrastructure adapter** in the hexagonal architecture that implements the `SMSProvider` port interface. It handles all Twilio-specific integration details, including API authentication, request formatting, and SMS delivery.
+---
 
-### Architecture Role
+## Table of Contents
 
-```
-Application Layer (SMSService)
-    ↓ depends on
-Domain Layer (SMSProvider interface)
-    ↑ implemented by
-Infrastructure Layer (TwilioSMSProvider) ← THIS MODULE
-    ↓ calls
-Twilio REST API
-```
+- [Overview](#overview)
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
 
-This adapter can be replaced with other SMS providers (AWS SNS, Vonage) without changing your application code.
+## Overview
 
-## Installation
+Firefly Framework Notifications Twilio implements the `SMSProvider` interface from the Firefly Notifications core module using Twilio as the delivery provider. It provides `TwilioSMSProvider` which handles SMS delivery through the Twilio API.
 
-Add these dependencies to your `pom.xml`:
+The module includes auto-configuration for seamless activation when included on the classpath alongside the notifications core module. Configuration properties allow customizing API credentials and provider-specific settings.
 
-```xml path=null start=null
-<dependency>
-  <groupId>org.fireflyframework</groupId>
-  <artifactId>fireflyframework-notifications-core</artifactId>
-  <version>1.0.0-SNAPSHOT</version>
-</dependency>
+## Features
 
-<dependency>
-  <groupId>org.fireflyframework</groupId>
-  <artifactId>fireflyframework-notifications-twilio</artifactId>
-  <version>1.0.0-SNAPSHOT</version>
-</dependency>
-```
+- `SMSProvider` implementation using Twilio
+- Spring Boot auto-configuration for seamless activation
+- Configurable API credentials via application properties
+- Standalone provider library (include alongside fireflyframework-notifications)
 
-## Configuration
+## Requirements
 
-Add the following to your `application.yml`:
+- Java 21+
+- Spring Boot 3.x
+- Maven 3.9+
+- Twilio account and API credentials
 
-```yaml path=null start=null
-notifications:
-  sms:
-    provider: twilio  # Enables this adapter
+## Installation
 
-twilio:
-  config:
-    account-sid: ${TWILIO_ACCOUNT_SID}
-    auth-token: ${TWILIO_AUTH_TOKEN}
-    phone-number: "+1234567890"  # Your Twilio phone number
+```xml
+<dependency>
+    <groupId>org.fireflyframework</groupId>
+    <artifactId>fireflyframework-notifications-twilio</artifactId>
+    <version>26.01.01</version>
+</dependency>
 ```
 
-### Getting Your Credentials
-
-1. Sign up at [twilio.com](https://www.twilio.com)
-2. Get your Account SID and Auth Token from the console dashboard
-3. Purchase or verify a phone number
-4. Set as environment variables:
-   ```bash
-   export TWILIO_ACCOUNT_SID="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
-   export TWILIO_AUTH_TOKEN="your-auth-token"
-   ```
-
-## Usage
-
-Inject `SMSService` from the core library. Spring automatically wires this adapter:
-
-```java path=null start=null
-@Service
-public class VerificationService {
-
-    @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());
-                } else {
-                    log.error("Failed: {}", response.getError());
-                }
-            });
-    }
-}
+## Quick Start
+
+```xml
+<dependencies>
+    <dependency>
+        <groupId>org.fireflyframework</groupId>
+        <artifactId>fireflyframework-notifications</artifactId>
+    </dependency>
+    <dependency>
+        <groupId>org.fireflyframework</groupId>
+        <artifactId>fireflyframework-notifications-twilio</artifactId>
+    </dependency>
+</dependencies>
 ```
 
-## Features
-
-- **International SMS** - Supports sending to any country Twilio serves
-- **Synchronous API** - Returns response immediately
-- **Error handling** - Validates phone numbers and handles API errors
-- **Delivery tracking** - Returns Twilio message SID for status tracking
-
-## Switching Providers
-
-To switch from Twilio to another SMS provider:
-
-1. Remove this dependency from `pom.xml`
-2. Add alternative SMS adapter dependency
-3. Update configuration to use different provider
-
-**No code changes required** in your services—hexagonal architecture ensures provider independence!
-
-## Implementation Details
-
-This adapter:
-- Implements `SMSProvider` interface from `fireflyframework-notifications-core`
-- Uses Twilio Java SDK for API calls
-- Transforms `SMSRequestDTO` to Twilio's `Message` format
-- Handles authentication via Account SID and Auth Token
-- Returns standardized `SMSResponseDTO`
-
-## Troubleshooting
+## Configuration
 
-### Error: "No qualifying bean of type 'SMSProvider'"
+```yaml
+firefly:
+  notifications:
+    twilio:
+      account-sid: ACxxxxxxxxxx
+      auth-token: your-auth-token
+      from-number: +1234567890
+```
 
-- Ensure `notifications.sms.provider=twilio` is set
-- Verify Twilio credentials are configured
+## Documentation
 
-### Error: "Invalid phone number"
+No additional documentation available for this project.
 
-- Phone numbers must be in E.164 format (e.g., +1234567890)
-- Ensure the number includes country code
+## Contributing
 
-### Error: "Insufficient balance"
+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.
 
-- Check your Twilio account balance
-- Add funds or use trial credits for testing
+## License
 
-## References
+Copyright 2024-2026 Firefly Software Solutions Inc.
 
-- [Twilio SMS API Documentation](https://www.twilio.com/docs/sms/api)
-- [Firefly Notifications Architecture](../fireflyframework-notifications/ARCHITECTURE.md)
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.