kongruity pulls in the unstructured artifacts of the creative-engineering process -- to-dos, action items, agile tickets, Jira comment threads, retrospective notes -- and synthesizes them into semantically coherent, prioritized clusters ready for implementation planning.

In kongruity world, these artifacts are "sticky notes." A board full of them looks chaotic. With a click, an LLM analyzes their semantic meaning and groups them into thematic clusters, each with a descriptive header.

An independent embedding-based evaluation scores clustering quality, so the output is data-backed. From there, teams can simply drag-and-rank clusters by implementation priority, turning noise into an actionable workflow.

How it works

Ingest — Sticky notes are loaded and displayed on a board.
Cluster — An LLM reads every note and groups them by semantic similarity (not keywords).
Evaluate — In parallel, a separate embedding model (Voyage AI) generates vector representations of each note. A silhouette-based cohesion score measures how well-separated and internally consistent clusters are. The score is displayed alongside the results.
Validate — Structural checks confirm every note is assigned to exactly one cluster, no clusters are empty, and labels are present.
Prioritize — Clusters appear ranked and are drag-reorderable. Teams set implementation priority by dragging clusters into position.

Dev implementation note

Developers may swap in other LLM SDKs/APIs and alter prompt syntax in backend/services/clustering.service.js to experiment with any model or platform.

Prerequisites

Node.js (v18 or later recommended)
An Anthropic API key (or other LLM platform, for clustering)
A Voyage AI API key (for embedding-based evaluation)

Setup

1. Clone the repository

git clone https://github.com/kjannette/kongruity_
cd kongruity

2. Create an environment file

The backend expects a .env file in the backend/ directory. This file is git-ignored and must be created manually:

cat > backend/.env << 'EOF'
ANTHROPIC_API_KEY=<your Anthropic API key> (or other LLM platform key)
VOYAGEAI_API_KEY=<your Voyage AI API key>
EOF

Replace placeholder values with your actual keys.

3. Install dependencies

cd backend
npm install

cd frontend
npm install

Run the app

Start the backend — Production mode

From the backend/ directory:

npm run start

The API server starts on http://localhost:3001 (configurable via the PORT environment variable).

Start the backend — Development mode

To start using Nodemon for hot reloads while developing:

npm run dev

Build the frontend — Production mode

From the frontend/ directory:

npm run build

Start the frontend — Development mode

From the frontend/ directory:

npm run dev

The Vite dev server starts on http://localhost:5173 by default. Open that URL in a browser.

Running tests

Backend tests

From the backend/ directory:

npm test

Backend tests use Vitest with Supertest for HTTP assertions.

Frontend tests

From the frontend/ directory:

npm test

This runs Vitest with jsdom. For watch mode during development:

npm run test:watch