kongruity

kongruity pulls in unstructured artifacts of the creative-engineering process -- to-dos, action items, agile tickets, Jira thread comments, Slack thread comments, retrospective notes -- and synthesizes them into semantically coherent, prioritized clusters that can be incoporated into implementation planning.

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

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

How it works

1. Ingest — Sticky notes are loaded and displayed on a board.
2. Cluster — An LLM reads every note and groups them by semantic similarity (not keywords).
3. 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.
4. Validate — Structural checks confirm every note is assigned to exactly one cluster, no clusters are empty, and labels are present.
5. 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)
• PostgreSQL (v14 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>
DATABASE_URL=postgresql://<user>:<password>@localhost:5432/kongruity
EOF

Replace placeholder values with your actual keys and database credentials.

3. Set up the database

Create a PostgreSQL database for the project:

createdb kongruity

Run the migration to create tables:

cd backend
npm run db:migrate

Seed the database with the sample sticky notes:

npm run db:seed

4. 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