🚧 Fence Tracker

📋 Overview

Fence Tracker is a scheduled zone-based alerting service that monitors activity levels in defined geographic or logical zones. It operates on a rolling 12-hour window, splitting each day into two distinct monitoring periods (00:00–11:59 and 12:00–23:59), based on São Paulo local time.

The system retrieves aggregated event counts per account and zone from a centralized Query Gateway. If the number of events exceeds a configurable threshold, Fence Tracker generates and sends an alert via WhatsApp, while persisting alert states to prevent duplicate notifications.

To ensure reliability and accuracy, Fence Tracker uses a trigger table to track previously sent alerts and only notifies on new threshold crossings (e.g., from 50 to 100 events). It also automatically cleans up outdated trigger records at the start of each new 12-hour cycle.

Fence Tracker helps operational teams respond to abnormal zone activity quickly and effectively, reducing noise and increasing situational awareness.

🎯 Objectives

• Monitor zone activity on a 12-hour rolling window (00:00–11:59 or 12:00–23:59)
• Retrieve aggregated zone activity data from the Query Gateway via named queries
• Filter and count events per account and zone
• Detect when event counts exceed a defined threshold (e.g., 50 events)
• Calculate and track alert states using a Prisma-managed trigger table
• Avoid duplicate notifications by only triggering on threshold multiples
• Clean up expired trigger records at the start of each 12-hour window
• Format alert messages with account, zone, cabinet, and condominium details
• Send alert notifications via WhatsApp using the ChatPro API
• Support Basic and Bearer token authentication for secure API access
• Log all operations and errors for auditability and diagnostics
• Run as a recurring scheduled job integrated with backend infrastructure

---

📦 Quick Start

⚠️ Prerequisites

• Node.js ≥ 20.14.0 — JavaScript runtime environment
• MySQL ≥ 8.0 — Relational database
• Query Gateway ≥ 3.0.3 — Configurable data query service

⚙️ Setup

# Clone & navigate
git clone <repository-url> && cd fence-tracker

# Configure environment
cp .env.example .env  # Edit with your settings

# Install dependencies (auto-runs database setup)
npm install

💡 Database: Import storage.sql.example before running npm install

---

⚡ Usage

🛠️ Development

npm run start:development

🏗️ Production

npm run build && npm run start:production

---

📚 Command Reference

🧰 Core

Command	Description
npm run start:development	Start the application in development
npm run start:production	Start the application in production
npm run build	Build the application for production
npm run build:watch	Build the application with watch mode
npm run clean	Clean application build artifacts

🛢️ Database

Command	Description
npm run db:pull	Pull database schema into Prisma across all schemas
npm run db:push	Push Prisma schema to the database across all schemas
npm run db:generate	Generate Prisma Client for all schemas
npm run db:migrate:dev	Run development migrations across all schemas
npm run db:migrate:deploy	Deploy migrations to production across all schemas
npm run db:studio	Open Prisma Studio (GUI) across all schemas
npm run db:reset	Reset database (pull + generate) for all schemas

🐳 Docker

Command	Description
npm run docker:build:development	Build Docker image for development
npm run docker:build:production	Build Docker image for production
npm run docker:run:development	Run development Docker container
npm run docker:run:production	Run production Docker container
npm run docker:compose:up:development	Start Docker Compose in development
npm run docker:compose:up:production	Start Docker Compose in production
npm run docker:compose:up:build:development	Start & rebuild Docker Compose in development
npm run docker:compose:up:build:production	Start & rebuild Docker Compose in production
npm run docker:compose:down	Stop Docker Compose services
npm run docker:compose:logs	View Docker Compose logs
npm run docker:prune	Clean up unused Docker resources

🧪 Testing

Command	Description
npm test	Run all tests once
npm run test:watch	Run tests in watch mode
npm run test:coverage	Run tests and generate a coverage report