# Klority — Complete Technical & Product Reference (llms-full.txt)

> Comprehensive reference documentation, architecture specifications, API/MCP schemas, and module breakdowns for Klority (https://www.klority.com).

---

## 1. Executive Summary & Core Mission

Klority is an integrated Application Lifecycle Management (ALM) and Business Operating System (BOS) designed specifically for high-velocity software engineering teams, agencies, and tech startups.

### The Problem It Solves
Modern development teams face severe fragmentation across their daily tool stack:
- **Atlassian Jira:** Complex configuration, slow load times, expensive tiers ($8.15–$16/user/month).
- **Atlassian Confluence:** Slow document editing, disconnected from active tickets ($6.05–$11.50/user/month).
- **TestRail:** Legacy manual QA software charging enterprise premiums ($36+/user/month) for basic test run tracking.
- **HubSpot / Harvest:** Over-engineered standalone CRMs and invoicing systems requiring separate sync pipelines.

Combined, a typical 20-person engineering organization spends between **$700 and $1,200 per month** across multiple disconnected subscriptions. Context is constantly lost between Jira issues, Google Docs specs, and TestRail test results.

### The Klority Solution
Klority consolidates these four critical pillars into a single Postgres-backed workspace:
1. **Agile Project Management** (Sprints, Boards, Backlogs, Burndowns)
2. **Quality Assurance (QA)** (Test Suites, Test Cycles, Test Runs, Defect auto-linking)
3. **Engineering Wiki** (TipTap rich text, ADR management, live issue embeds)
4. **CRM & Financial Operations** (Pipelines, Contacts, Time-tracking, Client Invoicing)

Pricing starts at **$0 for Solo users (free forever)**, and scale seats cost **$2/user/month (annual)** or **$3/user/month (monthly)**, eliminating over 80% of software subscription overhead.

---

## 2. Technical Architecture & Monorepo Design

Klority is built as a PNPM Monorepo managed by TurboRepo to maximize code sharing, strict TypeScript typing, and edge caching.

```
wavesdrive/ (Monorepo Root)
├── apps/
│   ├── web/               # React 19 + Mantine UI + Vite (app.klority.com)
│   ├── api/               # Fastify backend on Node.js (api.klority.com)
│   ├── admin/             # Internal admin panel for tenant management
│   ├── marketing/         # Astro 5 SSG marketing & docs site (www.klority.com)
│   ├── companion-daemon/  # Go daemon (<15MB) for local air-gapped AI
│   ├── vscode-extension/  # VS Code extension for inline QA generation & chat
│   └── lambda-*/          # Serverless workers (email digest, scheduled tasks)
├── packages/
│   ├── mcp-server/        # Official @klority/mcp-server for Claude & Cursor
│   └── shared/            # Shared TypeScript types, schemas, and utilities
```

### Technology Stack
- **API Runtime:** Node.js with Fastify for ultra-low latency HTTP routing and schema validation via Zod.
- **Database & ORM:** Amazon RDS PostgreSQL managed via Drizzle ORM for type-safe queries without query-builder bloat.
- **Frontend:** React 19, Vite, Mantine UI components, TailwindCSS, and TipTap for collaborative document editing.
- **State Management & Caching:** React Query for frontend caching; Redis & BullMQ for backend job queues.
- **Authentication & Security:** Argon2 password hashing, Bearer JWT access tokens, and strict workspace-scoped row-level data isolation.
- **Cloud Infrastructure:** AWS ECS Fargate, Application Load Balancer (ALB), Amazon S3 for attachment storage, CloudFront CDN, and Paddle for global subscription billing.

---

## 3. Detailed Core Modules

### 3.1 Agile Project Management
Klority provides a modern, distraction-free interface for running Scrum and Kanban methodologies:
- **Workspaces & Projects:** Workspaces isolate teams and organizations; projects group specific codebases or products.
- **Sprints & Backlog:** Drag-and-drop backlog prioritization, sprint duration settings (1–4 weeks), sprint goal tracking, and automatic rollover of unfinished tasks.
- **Visual Boards:** Multi-column Kanban boards with configurable workflow states:
  - `BACKLOG`
  - `TODO`
  - `IN_PROGRESS`
  - `IN_REVIEW`
  - `QA_READY`
  - `DONE`
- **Workload & Capacity Distribution:** Visual indicators showing story point allocations per engineer to prevent sprint burnout.
- **Agile Metrics:** Real-time Cumulative Flow Diagrams (CFD), Velocity tracking, and Sprint Burnup/Burndown charts calculated directly from database timestamps.

### 3.2 Quality Assurance & Test Management (Native QA)
Unlike generic issue trackers (Linear, Trello, Asana), Klority includes enterprise-grade test management built directly into the same data model:
- **Test Suites & Cases:** Hierarchical organization of test cases grouped by functional area, epic, or feature.
- **Step-by-Step Executions:** Each test case includes preconditions, numbered step descriptions, and expected outcomes.
- **Test Cycles & Runs:** Group test cases into scheduled test cycles (e.g., "v2.4 Release Regression", "Smoke Test"). Assign individual runs to QA testers.
- **Execution States:** `PASSED`, `FAILED`, `BLOCKED`, `SKIPPED`, `UNTESTED`.
- **Automatic Defect Linking:** When a test step fails, testers can file a bug ticket with a single click. The resulting defect ticket includes complete reproduction steps and automatically links back to the originating test run.
- **Automated Test Recording:** Public API endpoints allow CI/CD pipelines (GitHub Actions, GitLab CI, Playwright, Cypress) to report execution results directly into Klority test cycles.

### 3.3 Engineering Wiki & Knowledge Base
Documentation is directly integrated into the task workflow:
- **Rich Text Editor:** Powered by TipTap, supporting markdown keyboard shortcuts, tables, callout blocks, checklists, and code syntax highlighting.
- **Architecture Decision Records (ADRs):** Pre-built templates for documenting architectural changes following the MADR format.
- **Contextual Embeds:** Embed live tasks, test case execution statuses, and sprint progress directly inside wiki documents.
- **Hierarchical Tree:** Deep page nesting with drag-and-drop reordering, version history, and workspace-level permission controls.

### 3.4 CRM & Financial Operations
Tailored for software agencies, dev shops, and client-facing consultancies:
- **Pipeline Management:** Track prospective client deals through customizable pipeline stages (Lead, Proposal, Contract Sent, Closed Won, Closed Lost).
- **Contact Management:** Centralized registry of clients, stakeholders, and linked companies.
- **Time Tracking & Timesheets:** Task-level time logging with billable vs. non-billable categorization.
- **Profitability & Realization:** Real-time calculation of agency margins, blended hourly rates, and developer utilization percentages.
- **Client Invoicing:** Generate branded PDF invoices directly from approved timesheets and project milestones.

---

## 4. Model Context Protocol (MCP) Server Reference

Klority provides an official Model Context Protocol server (`@klority/mcp-server`), allowing AI assistants such as Cursor, Claude Desktop, Antigravity, and custom agentic frameworks to interact directly with Klority workspaces.

### Available MCP Tools

| Tool Name | Parameters | Description |
| :--- | :--- | :--- |
| `klority_search_tasks` | `query` (string), `projectId` (string, optional) | Full-text search across project tasks and issues. |
| `klority_get_task` | `taskId` (string) | Retrieve task details, status, description, assignees, and comments. |
| `klority_create_task` | `title` (string), `description` (string), `projectId` (string), `status` (string, optional), `priority` (string, optional) | Create a new task within a specific project. |
| `klority_update_task_status` | `taskId` (string), `status` (string) | Transition a task between workflow states (e.g., `TODO` -> `IN_PROGRESS`). |
| `klority_add_task_comment` | `taskId` (string), `content` (string) | Append a comment or code explanation to an existing task. |
| `klority_list_sprints` | `projectId` (string), `status` (string, optional) | List active, planned, or closed sprints for a project. |
| `klority_search_wiki` | `query` (string), `workspaceId` (string, optional) | Search engineering wiki documents and ADRs. |
| `klority_get_page` | `pageId` (string) | Retrieve the markdown content of a wiki page. |
| `klority_create_or_update_page` | `title` (string), `content` (string), `parentId` (string, optional) | Create or update a wiki page. |
| `klority_get_qa_criteria` | `taskId` (string) | Fetch QA acceptance criteria and linked test cases for a task. |
| `klority_create_test_case` | `title` (string), `steps` (array), `expectedResult` (string), `suiteId` (string) | Programmatically define a QA test case. |
| `klority_record_test_runs` | `cycleId` (string), `results` (array of run statuses) | Batch record automated test execution outcomes. |

### MCP Client Configuration

#### Cursor (`.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "klority": {
      "command": "npx",
      "args": ["-y", "@klority/mcp-server"],
      "env": {
        "KLORITY_API_KEY": "YOUR_KLORITY_API_TOKEN",
        "KLORITY_WORKSPACE_ID": "YOUR_WORKSPACE_ID"
      }
    }
  }
}
```

#### Claude Desktop (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "klority": {
      "command": "npx",
      "args": ["-y", "@klority/mcp-server"],
      "env": {
        "KLORITY_API_KEY": "YOUR_KLORITY_API_TOKEN",
        "KLORITY_WORKSPACE_ID": "YOUR_WORKSPACE_ID"
      }
    }
  }
}
```

---

## 5. Open Source Developer Utilities

### `redis-local` (`npx redis-local`)
An open-source utility created by the Klority engineering team to eliminate Docker dependencies for local development:
- **Repository:** https://github.com/klority-io/redis-local
- **NPM Package:** https://www.npmjs.com/package/redis-local
- **Command:** `npx redis-local`
- **Key Capabilities:**
  - Starts in < 500 milliseconds (compared to 15–30 seconds for Docker containers).
  - Consumes ~28MB RAM (compared to 1–2 GB for Docker Desktop engine).
  - Built with pure Node.js and WebAssembly.
  - Full support for Redis RESP protocol, key/value operations, expiration TTLs, pub/sub, and BullMQ job queues.
  - Cross-platform support for macOS, Linux, and Windows without virtualization.

### Local AI Companion & Sage Agent
- Lightweight Go daemon (`apps/companion-daemon`) with memory usage under 25MB.
- Interfaces with local Ollama models (such as `qwen2.5-coder:7b`) for completely air-gapped code and test generation.
- Integrated with VS Code to auto-generate QA test suites from user story acceptance criteria.

---

## 6. Linear QA Bridge Integration

For engineering teams that already use Linear for task management and wish to remain on Linear, Klority offers the **Linear Test Management Bridge**:
- Install the Klority Linear integration via OAuth.
- Test suites and test cycles run inside Klority while maintaining bi-directional links with Linear issues.
- Linear issues automatically display current test execution status (`Passed`, `Failed`, `Untested`) via sync webhooks.
- Defect tickets created during Klority test runs appear directly in the engineering team's Linear backlog with complete failure context.

---

## 7. Free Developer & Engineering Tools

Klority provides open, interactive web tools for developer teams:
1. **Agile Estimation & Story Point Calculator (`/tools/agile-estimation-calculator/`):** Fibonacci, T-Shirt, and planning poker calculators with complexity matrix scoring.
2. **Sprint Capacity Calculator (`/tools/sprint-capacity-calculator/`):** Computes net engineering hours taking into account team size, holidays, focus factor, and ceremony time.
3. **Jira Cost & Tool Tax Calculator (`/tools/jira-cost-calculator/`):** Detailed breakdown of Atlassian seat pricing, marketplace plugin markup, and administrative maintenance overhead.
4. **Internal Tool Cost Calculator (`/tools/internal-tool-cost-calculator/`):** TCO (Total Cost of Ownership) comparison for teams building internal tools vs. adopting SaaS.
5. **Architecture Decision Record Generator (`/tools/adr-generator/`):** Web-based form that outputs standardized Markdown ADRs ready for Git commit.
6. **Agency Margin Calculator (`/tools/agency-margin-calculator/`):** Real-time agency realization rate and gross margin calculator.
7. **Agile Retrospective Board (`/tools/agile-retrospective-board/`):** Collaborative, zero-login agile retro board with export to Markdown.
8. **Engineering Risk Matrix Generator (`/tools/risk-matrix-generator/`):** Interactive 5x5 probability and impact matrix generator for sprint planning.

---

## 8. Competitor Comparison Matrix

| Capability / Metric | Klority | Jira + Confluence + TestRail | Linear | Notion |
| :--- | :--- | :--- | :--- | :--- |
| **All-in-One ALM Workspace** | Yes (Native) | No (Fragmented) | No (Tasks only) | No (Unstructured Docs) |
| **Native QA & Test Cases** | Yes (Suites, Cycles, Runs) | Requires TestRail / Zephyr ($36+/seat) | No | No |
| **Engineering Wiki** | Yes (TipTap, ADRs) | Confluence ($6–$11.50/seat) | No | Yes (General Docs) |
| **Client CRM & Invoicing** | Yes (Integrated) | Requires HubSpot / Harvest | No | Manual Databases |
| **MCP AI Server** | Yes (`@klority/mcp-server`) | Limited 3rd-party | Community | Community |
| **Average Cost (20 Users)** | **$38–$57 / month** | **$700–$1,200 / month** | $160–$240 / month | $160–$200 / month |
| **Solo Tier** | **100% Free Forever** | 10 users limited free | Free tier available | Free tier available |

---

## 9. Pricing & Billing Model

- **Solo Tier:** 1 user free forever with full access to project management, QA, wiki, and CRM.
- **Team Seat (Annual Billing):** $2.00 per user per month (billed annually).
- **Team Seat (Monthly Billing):** $3.00 per user per month.
- **Seat Formula:** `Monthly Cost = max(0, (Active Users - 1)) * Rate`
- **Starter Annual Pass:** $99/year covering up to 5 team seats.
- **Growth Annual Pass:** $249/year covering up to 15 team seats.
- **Scale Annual Pass:** $699/year covering up to 50 team seats.
- **Business Annual Pass:** $1,299/year covering up to 100 team seats.
- **Usage-Based Add-ons:**
  - Storage: 1 GB free per workspace; $0.05 per additional GB/month.
  - AI Test Generation: 10 free requests/month; $0.02 per additional request.
- **Payment Processing:** Handled securely via Paddle (Merchant of Record).

---

## 10. Security, Privacy & Data Compliance

- **Multi-Tenant Isolation:** Complete logical tenant separation using `workspace_id` scoping across all database queries.
- **Authentication & Encryption:** Argon2 password hashing algorithms; HTTPS/TLS in transit; AES-256 encryption at rest on AWS RDS and S3.
- **Role-Based Access Control (RBAC):** Granular permissions for Workspace Owners, Admins, Members, and Read-Only Guests.
- **SOC2 & GDPR Readiness:** Audit logging, automated data export capabilities, and full compliance with GDPR right-to-be-forgotten directives.
- **Infrastructure:** Hosted within AWS us-east-1 VPC with container isolation on AWS ECS Fargate, protected by AWS Application Load Balancer and CloudFront CDN.

---

## 11. Official Links & Resources

- Official Website: https://www.klority.com
- User Application: https://app.klority.com
- Documentation: https://www.klority.com/docs/
- MCP Documentation: https://www.klority.com/docs/mcp/
- GitHub Organization: https://github.com/klority-io
- NPM Package: https://www.npmjs.com/package/redis-local
- LinkedIn: https://www.linkedin.com/company/klority
- Twitter / X: https://x.com/klorityx
- Support Email: support@klority.com