AlertHub

AlertHub is a microservices platform for ingesting developer-task data from GitHub, Jira, and ClickUp, evaluating metrics against configurable thresholds, and dispatching email or SMS alerts when conditions are met. A React dashboard provides a single place to manage users, metrics, actions, evaluations, loader scans, and centralized logs.

How it works

1. LoaderMS scans JSON export files under loaderMS/data/{github,jira,clickup} on a schedule (hourly) or on demand, and persists normalized task records to MySQL.
2. MetricMS stores metric definitions (label, time window, threshold) per user.
3. ActionMS defines alert rules (schedule, condition matrix, notification target) and publishes due actions to the Kafka job-queue topic every 30 minutes—or immediately when triggered manually.
4. ProcessorMS consumes job-queue messages, evaluates each action's condition against live metric data from MetricMS and LoaderMS, and publishes notification events to the email or sms Kafka topic when thresholds are met.
5. Email Service and SMS Service consume those topics and deliver messages (SMTP / Twilio WhatsApp).
6. Evaluation Service runs ad-hoc analytics queries (top developer by label, label breakdown) and can notify a manager by email.
7. Logger Service consumes the Kafka logs topic and stores structured logs in MongoDB for querying from the UI.
8. Security Service issues JWTs and enforces role-based permissions.
9. UserMS acts as the API gateway for authenticated CRUD on users, metrics, actions, and evaluations.
10. Frontend (React + Vite) proxies requests to all backend services through nginx.

flowchart LR
  subgraph ingest [Ingestion]
    Files["JSON files\n(github / jira / clickup)"]
    LoaderMS["LoaderMS :8081"]
    Files --> LoaderMS
  end

  subgraph config [Configuration]
    UserMS["UserMS :9090"]
    MetricMS["MetricMS :8082"]
    ActionMS["ActionMS :8083"]
    Security["Security :8091"]
    UserMS --> MetricMS
    UserMS --> ActionMS
    UserMS --> Security
  end

  subgraph pipeline [Alert pipeline]
    Kafka["Kafka"]
    Processor["ProcessorMS :8085"]
    Email["Email :8088"]
    SMS["SMS :8990"]
    ActionMS -->|"job-queue"| Kafka
    Kafka --> Processor
    Processor -->|"email / sms"| Kafka
    Kafka --> Email
    Kafka --> SMS
    Processor --> MetricMS
    Processor --> LoaderMS
  end

  subgraph observability [Observability]
    Logger["Logger :8086"]
    Mongo["MongoDB"]
    Kafka -->|"logs"| Logger
    Logger --> Mongo
  end

  subgraph ui [UI]
    Frontend["Frontend :3000"]
    Frontend --> UserMS
    Frontend --> LoaderMS
    Frontend --> Logger
  end

  LoaderMS --> MySQL[(MySQL)]
  MetricMS --> MySQL
  ActionMS --> MySQL
  Evaluation["Evaluation :8087"] --> MySQL

Loading

Microservices

Service	Port	Database / messaging	Role
loaderMS	8081	MySQL (loaderdb)	Scan and ingest platform JSON exports
MetricMS	8082	MySQL (metric)	CRUD for metric definitions
ActionMS	8083	MySQL (alerthub) + Kafka	Scheduled and manual action dispatch to job-queue
ProcessorMS	8085	Kafka + Feign to Loader/Metric	Evaluate conditions; route to email / sms
logger-service	8086	MongoDB + Kafka (logs)	Centralized log storage and query API
evaluation-service	8087	MySQL (loaderdb) + Kafka	Analytics endpoints; manager notifications
email-service	8088	Kafka (email)	SMTP notification delivery
security-service	8091	MySQL (securitydb)	JWT issuance and RBAC
sms-service	8990	Kafka (sms)	Twilio WhatsApp delivery
UserMS	9090	MySQL (usersdb)	Authenticated gateway to metrics, actions, users, evaluation
frontend	3000	—	React dashboard (nginx in Docker)

Kafka topics

Topic	Producer	Consumer
job-queue	ActionMS	ProcessorMS
email	ProcessorMS, evaluation-service	email-service
sms	ProcessorMS	sms-service
logs	ProcessorMS, evaluation-service, sms-service, …	logger-service

Infrastructure (Docker)

Component	Host port	Notes
MySQL 8	3307	Databases: usersdb, metric, loaderdb, alerthub, securitydb
MongoDB 7	27017	Database: logger-service
Kafka (KRaft)	9092	No Zookeeper

Tech stack

• Backend: Java 17, Spring Boot 3.x, Spring Data JPA, Spring Kafka, OpenFeign, Lombok
• Frontend: React 19, Vite 6, React Router 7
• Data: MySQL 8, MongoDB 7, Apache Kafka
• Deploy: Docker Compose, nginx reverse proxy

Prerequisites

• Docker Desktop (recommended for full stack)
• JDK 17+ and Maven (for running individual services locally)
• Node.js 18+ (for frontend development)

Quick start (Docker)

All compose files live under docker/.

1. Create environment file

Copy the template below into docker/.env and fill in secrets. This file is gitignored.

# JWT (required for security-service and UserMS)
SECRET_KEY=
JWT_EXPIRATION_MS=

# MySQL (optional overrides; defaults match compose)
SQL_USERNAME=
SQL_PASSWORD=

# Email (required for email-service and evaluation notifications)
MAIL_HOST=smtp-mail.outlook.com
MAIL_PORT=587
MAIL_USERNAME=your-email@outlook.com
MAIL_PASSWORD=your-app-password
MAIL_FROM=your-email@outlook.com
MANAGER_EMAIL=manager@example.com

# SMS via Twilio WhatsApp (optional)
TWILIO_ACCOUNT_SID=
TWILIO_AUTH_TOKEN=
TWILIO_WHATSAPP_FROM=

2. Start infrastructure

cd docker
docker compose -f docker-compose.infra.yml up -d

Wait until MySQL is healthy (docker compose -f docker-compose.infra.yml ps).

3. Start all application services

docker compose -f docker-compose.infra.yml -f docker-compose.apps.yml up --build

Or run detached:

docker compose -f docker-compose.infra.yml -f docker-compose.apps.yml up --build -d

4. Open the dashboard

Browse to http://localhost:3000. Sign in with a numeric user ID (for example 1). The demo login flow assigns the admin role and requests a JWT from the security service.

5. Trigger a loader scan (optional)

Sample data ships under loaderMS/data/. After services are up:

curl -X POST http://localhost:8081/loader/scan

Or use the Loader page in the UI.

Local development

Run infrastructure in Docker, then start individual services from their module directories.

Infrastructure only

cd docker
docker compose -f docker-compose.infra.yml up -d

MySQL is exposed on localhost:3307 (root / 1234).

Run a single microservice

cd loaderMS          # or MetricMS, ActionMS, etc.
./mvnw spring-boot:run          # macOS / Linux
.\mvnw.cmd spring-boot:run      # Windows

Point each service at local infrastructure using its application.properties (MySQL on localhost:3307, Kafka on localhost:9092, MongoDB on localhost:27017).

Suggested startup order when running manually:

1. MySQL, MongoDB, Kafka (Docker)
2. security-service, MetricMS, loaderMS
3. ActionMS, ProcessorMS, logger-service, evaluation-service
4. email-service, sms-service (optional)
5. UserMS
6. frontend

Frontend dev server

cd frontend
npm install
npm run dev

The Vite dev server does not include nginx proxies; configure API base URLs or use the Docker frontend for integrated routing.

Project structure

AlertHub/
├── docker/                  # Compose files and MySQL init scripts
├── frontend/                # React dashboard
├── loaderMS/                # File scanner and ingest
├── MetricMS/                # Metric definitions
├── ActionMS/                # Alert rules and scheduler
├── ProcessorMS/             # Condition evaluation and notification routing
├── logger-service/          # Centralized logging (see logger-service/README.md)
├── evaluation-service/      # Analytics queries
├── email-service/           # SMTP consumer
├── sms-service/             # Twilio WhatsApp consumer
├── security-service/        # JWT and roles
└── UserMS/                  # Authenticated API gateway

Security and permissions

The security service seeds these roles in securitydb: createAction, updateAction, deleteAction, createMetric, updateMetric, deleteMetric, triggerScan, triggerProcess, triggerEvaluation, read, and admin.

UserMS validates JWTs on protected routes and delegates authorization checks to the security service before forwarding requests to downstream microservices.

Sample loader data

JSON exports are organized by provider:

loaderMS/data/
├── github/
├── jira/
└── clickup/

Files are processed once per (filename, provider) pair. Drop new exports into the matching folder and trigger a scan.

Service documentation

• logger-service/README.md — Kafka → MongoDB logging flow, Postman examples, troubleshooting

Troubleshooting

Symptom	Likely cause
UserMS / security errors on login	SECRET_KEY missing or mismatched between docker/.env and running containers
Email not sent	Verify MAIL_* credentials in docker/.env; check email-service logs
Processor skips actions	Metric thresholds not met—confirm loader scan ran and metric label/time window match ingested data
Kafka connection refused	Ensure alerthub-kafka is running: docker ps
MySQL connection refused locally	Use port 3307 on the host, not 3306
Empty logs page	Services publish to Kafka topic logs; confirm logger-service and Kafka are up

Stop the stack

cd docker
docker compose -f docker-compose.infra.yml -f docker-compose.apps.yml down

To also remove volumes:

docker compose -f docker-compose.infra.yml -f docker-compose.apps.yml down -v