ReadMe

Alerta Gar - Twilio SMS App

This project is a Next.js application that connects to the Twilio API to receive SMS messages, saves the message content into a Supabase database, and displays the messages on the frontend in real-time.

Features

• Receive SMS Messages: Uses a Twilio virtual phone number to receive incoming SMS messages.

• Store SMS Data: Saves SMS details (sender, message, timestamp) into a Supabase database.

• Display Messages: Fetches and displays the stored SMS messages on the frontend.

• Secure Webhooks: Validates requests using Twilio's x-twilio-signature.

• Real-time Updates (Optional): Supports real-time message updates using Supabase subscriptions.

---

Technologies Used

• Next.js: React-based framework for building web applications.

• Twilio: Cloud communication platform for handling SMS messages.

• Supabase: Backend-as-a-service for database and authentication.

• TypeScript: Strongly-typed JavaScript for better developer experience.

• ngrok: Tool to expose your local server for webhook testing.

• Tailwind CSS (Optional): For frontend styling.

---

Getting Started

Prerequisites

• Node.js (v16+ recommended)

• npm

• Twilio account and virtual phone number

• Supabase account

Installation

1. Clone the Repository:

   gh repo clone Min11Benja/alertagas-twilio-sms
   cd alertagas-twilio-sms

2. Install Dependencies:

   npm install

3. Set Up Environment Variables: Create a .env.local file in the root of your project and add the following:

   # Twilio
   TWILIO_ACCOUNT_SID=your_twilio_account_sid
   TWILIO_AUTH_TOKEN=your_twilio_auth_token
   
   # Supabase
   NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
   NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
   SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

4. Set Up Supabase: Create a Supabase project. Add a table named sms_messages (and optional sensors table) with columns matching your SMS data. For example:

   create table public.sensors (
     id serial not null,
     sensor_name text null,
     phone_number text null,
     level integer null,
     updated_at timestamp with time zone not null default now(),
     constraint sensors_pkey primary key (id),
     constraint sensors_phone_number_key unique (phone_number)
   );
   
   create table public.sms_messages (
     id serial not null,
     from_number text null,
     body text null,
     received_at timestamp with time zone null default now(),
     sensor_id integer null,
     status text null default 'received'::text,
     constraint sms_messages_pkey primary key (id),
     constraint sms_messages_sensor_id_fkey foreign key (sensor_id) references sensors (id)
   );
   
   create index if not exists idx_from_number on public.sms_messages using btree (from_number);
   create index if not exists idx_received_at on public.sms_messages using btree (received_at);

5. Set Up Twilio: Purchase a Twilio phone number that supports SMS. Configure the webhook URL to point to your endpoint (e.g., /api/receive-sms). Use ngrok for local testing if needed.

6. Start the Development Server:

   npm run dev

---

Usage

1. Sending an SMS: Send an SMS to your Twilio phone number. The backend /api/receive-sms endpoint will handle the incoming request, validate it, and store the data in Supabase.

2. Viewing Messages: Open the application in your browser (http://localhost:3000). View the list of received SMS messages on the homepage or relevant dashboard pages.

---

Project Structure

src
├── app
│   ├── api
│   │   ├── receive-sms
│   │   │   └── route.js
│   │   └── sensors
│   │       └── route.ts
│   ├── auth
│   │   ├── layout.tsx
│   │   ├── login
│   │   │   └── page.tsx
│   │   ├── register
│   │   │   └── page.tsx
│   │   └── reset-password
│   │       └── page.tsx
│   ├── components
│   │   ├── HOC
│   │   │   └── ProtectedPage.tsx
│   │   ├── data-tables
│   │   │   ├── SensorForm.tsx
│   │   │   └── SensoresTable.tsx
│   │   ├── landing
│   │   │   ├── Contact.tsx
│   │   │   ├── CtaBanner.tsx
│   │   │   ├── Faq.tsx
│   │   │   ├── Features.tsx
│   │   │   ├── Footer.tsx
│   │   │   ├── Header.tsx
│   │   │   ├── HeroSection.tsx
│   │   │   ├── StepArrows.tsx
│   │   │   └── Testimonials.tsx
│   │   └── layout-components
│   │       ├── SideBar.tsx
│   │       └── TopBar.tsx
│   ├── dashboard
│   │   ├── PlatformLayout.tsx
│   │   ├── citas
│   │   │   ├── page.tsx
│   │   │   ├── programar
│   │   │   │   └── page.tsx
│   │   │   └── tabla
│   │   │       └── page.tsx
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   ├── rutas
│   │   │   ├── page.tsx
│   │   │   ├── programar
│   │   │   │   └── page.tsx
│   │   │   └── tabla
│   │   │       └── page.tsx
│   │   ├── sensores
│   │   │   ├── crear
│   │   │   │   └── page.tsx
│   │   │   ├── editar
│   │   │   │   └── [id]
│   │   │   │       └── page.tsx
│   │   │   ├── page.tsx
│   │   │   └── tabla
│   │   │       └── page.tsx
│   │   ├── settings
│   │   │   ├── globales
│   │   │   │   └── page.tsx
│   │   │   └── usuario
│   │   │       └── page.tsx
│   │   ├── sms
│   │   │   ├── page.tsx
│   │   │   └── tabla
│   │   │       └── page.tsx
│   │   ├── ticket
│   │   │   └── page.tsx
│   │   └── usuarios
│   │       ├── clientes
│   │       │   └── page.tsx
│   │       ├── operadores
│   │       │   └── page.tsx
│   │       ├── page.tsx
│   │       └── vendedores
│   │           └── page.tsx
│   ├── hooks
│   │   ├── useAuth.tsx
│   │   ├── useFetchData.tsx
│   │   └── useFetchUnlinkedPhoneNumbers.tsx
│   ├── landing
│   │   ├── LandingLayout.tsx
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── layout.tsx
│   └── page.tsx
├── lib
│   ├── helpers
│   │   └── formatDate.ts
│   └── supabase
│       └── supabaseClient.ts
└── styles
    └── globals.css

---

API Endpoints

Method	Endpoint	Description
POST	/api/receive-sms	Handles incoming SMS messages from Twilio.
GET	/api/sensors	Retrieves sensor data.

---

Enforce Branch Naming Convention

To maintain consistency and traceability between Jira issues and Git branches, follow this naming convention:

• feature/ → Used for new features or improvements.

• bugfix/ → Used to fix identified bugs.

• hotfix/ → Used for critical fixes that need immediate deployment.

Each branch should be linked to a Jira issue ID (AGT-XXX), ensuring better integration with project tracking and automation tools.

Commit Types

• feat: Commits that add or remove a new feature to the API or UI

• fix: Commits that fix a API or UI bug of a preceded feat commit

• refactor: Commits that rewrite/restructure your code, however do not change any API or UI behaviour

• perf: Commits that improve performance

• style: Commits that do not affect the meaning (white-space, formatting, missing semi-colons, etc)

• test: Commits that add missing tests or correcting existing tests

• docs: Commits that affect documentation only

• build: Commits that affect build components like build tool, ci pipeline, dependencies, project version, etc

• ops: Commits that affect operational components like infrastructure, deployment, backup, recovery, etc

• chore: Miscellaneous commits that dont fit anyhwere else

---

Jira & Git Integration

1. Link Jira with Your Git Repository

To track branches, commits, and PRs in Jira, integrate with GitHub (or GitLab/Bitbucket):

1. Go to Jira Settings → Click Apps → Search for GitHub for Jira.

2. Install the app and authorize Jira to access your GitHub repository.

3. Ensure your repository (alertagas-twilio-sms) is linked to Jira.

4. Enable Smart Commits to recognize AGT-XXX in commits and branches.

2. Automate Issue Tracking with Smart Commits

Use Smart Commit messages to automatically update Jira issues based on commits:

git commit -m "AGT-004: Implement sensor logging #done"
git commit -m "Fix AGT-005: Handle Twilio webhook errors #in-progress"

#done → Moves issue to "Done" #in-progress → Moves issue to "In Progress" #review → Moves issue to "Code Review"

---

Deployment

To deploy the project to Google Cloud Run:

gcloud run deploy nextjs-cloud-run \
  --image gcr.io/alertagas-nextjs-project/alertagas-twilio-sms:latest \
  --region us-central1 \
  --platform managed \
  --allow-unauthenticated

---

Contributing

1. Fork the repository.

2. Clone your fork: git clone https://github.com/your-user/alertagas-twilio-sms.git

3. Create a feature branch: git checkout -b feature/AGT-XXX-new-feature

4. Make changes and commit: git commit -m "AGT-XXX: Description"

5. Push to GitHub: git push origin feature/AGT-XXX-new-feature

6. Create a Pull Request and request a review.

---

Contact

• Developer: Benjamin Martinez Juarez

• Email: [email protected]

• GitHub: @min11benja

---

License

This project is licensed under the MIT License.