kongruity
kongruity pulls in the unstructured artifacts of the creative-engineering process -- to-dos, action items, agile tickets, Jira comment threads, Slack 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)
- 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