seatool-compare

Service for comparing legacy/seatool data and sending notifications.

---

Please visit our seatool-compare docs site for complete documentation.

---

Overview

The seatool-compare project (oftened referenced in the context of this repository as just 'compare') is a microservice compares legacy data and seatool data and sends notifications when certain conditions exist.

Contributing

Work items for seatool-compare are tracked in CMS' Jira. If you have access to our Jira, you can view seatool-compare related work there. While there's no dedicated seatool-compare product view in Jira yet, the Platform Team board is a good stand in.

If you don't have access to Jira, would like access to Jira, or would like to discuss any enhancement, bug, idea, or question, please visit the seatool-compare Slack channel. This is a public channel open to anyone in CMS Slack, and all input is welcome!

License

See LICENSE for full details.

Authentication

AWS Authentication

To work with this project, you'll need AWS credentials configured. The recommended way is to use AWS SSO:

1. Install the AWS CLI v2
2. Configure AWS SSO:

   aws configure sso

3. Enter the following when prompted:
   • SSO start URL: https://cmsgov.awsapps.com/start
   • SSO Region: us-east-1
   • Choose your account and role
   • CLI profile name: cmsgov

GitHub Authentication

For accessing private repositories and packages:

1. Create a GitHub Personal Access Token (PAT) with read:packages scope
2. Configure npm to use the token:

   npm login --registry=https://npm.pkg.github.com

Local Development

Prerequisites

• Node.js v22.x
• Yarn v1.22.19 or later
• AWS CLI v2
• AWS SSO configured

Setup

1. Clone the repository:

   git clone https://github.com/Enterprise-CMCS/seatool-compare.git
   cd seatool-compare

2. Install dependencies:

   yarn install:all

Available Commands

Workspace Commands

• yarn install:all - Install dependencies for all services
• yarn build:all - Build all services
• yarn deploy:all - Deploy all services
• yarn test:all - Run tests for all services

Individual Service Commands

To run commands for a specific service:

yarn workspace <service-name> <command>

Available services:

• alerts - Alert notification service
• appian - Appian integration service
• compare-appian - Appian comparison service
• compare-mmdl - MMDL comparison service
• connector - Data connector service
• mmdl - MMDL service
• seatool - Seatool service

Example:

# Build the alerts service
yarn workspace alerts build

# Run tests for the connector service
yarn workspace connector test

Running Tests

Each service has its own test suite. To run tests for a specific service:

yarn workspace <service-name> test

For example:

yarn workspace alerts test

Local Development Server

To run a service locally:

yarn workspace <service-name> start

This will start the service in development mode with hot reloading enabled.

Connector Service

The connector service uses Kafka Connect to stream data from Kafka topics into Lambda sink functions.

Kafka Connect Plugin

The service uses the Confluent AWS Lambda Sink Connector (io.confluent.connect.aws.lambda.AwsLambdaSinkConnector) to invoke Lambda functions for each message consumed from Kafka topics.

Note: As of November 2025, the Confluent connector replaced the previously used Nordstrom kafka-connect-lambda connector which became unavailable.

Migration Runbook

For deploying connector changes to val/production environments, see the Confluent Connector Migration Runbook.

Quick Connector Health Check

# Check connector status (replace <stage> with master, val, or production)
aws lambda invoke \
  --function-name compare-connector-<stage>-testConnectors \
  --region us-east-1 \
  --cli-binary-format raw-in-base64-out \
  --payload '{"cluster": "compare-connector-<stage>-connect"}' \
  /tmp/test.json && cat /tmp/test.json

# View recent Kafka Connect logs
aws logs tail /aws/fargate/compare-connector-<stage>-kafka-connect --since 10m --region us-east-1