# Klairia

Klairia is a SaaS for tracking how a website appears in AI-generated answers. It measures visibility across multiple LLMs, languages, and prompt specificities, then turns the results into a score and supporting evidence for product and marketing teams.

## What The Product Does

- Analyzes a website to extract context, keywords, competitors, and positioning.
- Generates topic sets and 5 prompts per topic, progressing from generic to highly specific.
- Runs scans across selected models, languages, and repetitions.
- Uses an LLM-based judge to detect brand mentions, position, context, sentiment, and competitor references.
- Aggregates results into a visibility score with per-model and per-language breakdowns.
- Tracks changes over time with weekly scans.
- Supports paid-workspace agent workflows through MCP and REST endpoints.

## Public Website

### Routes

- Home: `/`
- Pricing: `/pricing`
- Blog index: `/blog`
- Blog post: `/blog/<slug>`
- Brands directory: `/brands`
- Brand detail: `/brands/<slug>`
- Privacy: `/privacy`
- Terms: `/terms`
- Refund policy: `/refund-policy`
- RSS feed: `/rss.xml`
- Sitemap: `/sitemap.xml`

### Marketing Notes

- The home page emphasizes weekly progressive-prompt scans, multilingual coverage, and the MCP workflow.
- Pricing is plan-based and centered around weekly snapshots, topic limits, language limits, and model coverage.
- The brands directory shows visibility scores and category groupings for tracked SaaS brands.

## App

### Entry Points

- Main app entry redirects to `/dashboard`.
- Dashboard data and workspace management live under `apps/app/app/(dashboard)`.
- API routes live under `apps/app/app/api`.

### Dashboard Routes

- `/dashboard` and `/sites` show tracked sites, score history, and scan controls.
- `/scans` shows scan details, status, results, and stored output inspection.
- `/prompts` is the admin prompt-management view.
- `/billing` redirects into pricing checkout.
- `/account` manages API keys and integration endpoints.
- `/subscription-settings` is the global subscription plan admin page.
- `/settings` is workspace settings.
- `/admin` is the global admin control panel.
- `/demo-scan` runs a demo scan flow.

### App Responsibilities

- Authentication and session handling.
- Workspace and site management.
- Scan creation, scan resumption, and progress tracking.
- Billing and plan access checks.
- API key management.
- Admin controls for plans, model availability, language availability, and scheduler operations.

## API And Agent Access

### External Surfaces

- MCP endpoint: `/api/mcp`
- REST base: `/api/v1`
- Skill descriptor: `/api/v1/skill`

### REST Endpoints

- `GET/POST /api/v1/sites`
- `GET/PATCH/DELETE /api/v1/sites/[siteId]`
- `PATCH /api/v1/sites/[siteId]/scan-settings`
- `GET/POST /api/v1/sites/[siteId]/snapshots`
- `GET/POST /api/v1/scans`
- `GET /api/v1/scans/[scanId]`
- `GET /api/v1/workspace`

### API Notes

- The API layer is intended for workspace/site/scan data access and scan control.
- Paid workspaces can use agent clients against the MCP endpoint with personal API keys.
- The account page exposes integration URLs derived from the app base URL.

## Worker

- The worker app lives in `apps/worker`.
- It consumes BullMQ jobs for scan execution.
- It calls LLM providers, detects mentions, computes scores, and persists results.
- It also supports batch polling, provider retries, mention detection, and scan progress checks.

## Shared Packages

- `packages/db` contains MongoDB connection utilities and Mongoose models.
- `packages/llm` defines the provider abstraction and batch/sync request types.
- `packages/scoring` contains competitor extraction, recommendation logic, and score calculation.
- `packages/types` contains shared TypeScript types and enums.

## Data Model Overview

The primary Mongoose models live in `packages/db/src/models/index.ts`.

- Organizations and subscription plans.
- Recommendation settings.
- Users and subscriptions.
- API keys.
- Tracked sites, topics, prompt sets, scans, and scan batches.
- Search snapshots and agent reference snapshots.
- Scan results and model API error resolutions.
- Snapshots that store aggregated visibility data.

## Scoring And Retrieval Concepts

- Visibility score: aggregate measure of how visible a brand is in AI responses.
- Specificity level: the earliest prompt level where the brand first appears.
- Competitor mentions: extracted competitors and alternatives from model output.
- Agent reference bonus: adjustment used in some dashboard rollups.
- Model and language breakdowns: used to show where visibility is strong or weak.

## Billing And Plans

- Billing uses LemonSqueezy.
- The repo supports plan previews and plan metadata management.
- Public pricing currently exposes Starter, Pro, and Business plan tiers.
- The dashboard uses plan limits for models, languages, and stored topics.

## Key Workflow

1. Site analysis extracts context and generates scan setup.
2. Prompt generation creates the topic and prompt set.
3. The worker executes model requests and batch polling.
4. Mention detection judges the results.
5. Scoring aggregates the results into a visibility score.
6. Dashboard pages expose score trends, stored scan details, and history.

## Environment And Runtime

- Node.js 20+
- pnpm 10+
- MongoDB
- Redis
- TypeScript across the monorepo
- Next.js for the app
- Astro for the landing site

## Development Commands

- `pnpm install`
- `pnpm dev`
- `pnpm build`
- `pnpm lint`
- `pnpm typecheck`
- `pnpm test`
- `pnpm check`

## Deployment And Operations

- Production uses Docker Swarm with Traefik.
- Production config lives in `docker/klairia.yml`.
- Production secrets are managed with SOPS and Age.
- `deploy/prod.env.example` is the plaintext template.
- `deploy/prod.env.enc` is the encrypted production environment file.
- GitHub Actions decrypts secrets during deployment.

## Environment Variables

- Shared variables include `MONGODB_URI` and `REDIS_URL`.
- App-specific variables cover NextAuth and LemonSqueezy.
- Worker-specific variables cover LLM provider keys, Firecrawl, Serper, and Resend.
- Runtime code should import typed `env` modules instead of reading `process.env` directly.

## Blog Publishing

- Posts live at `apps/landing/src/content/blog/<post-folder>/index.md`.
- Post images should stay in the same folder as the Markdown file.
- Blog routes are `/blog` and `/blog/<slug>`.
- Required frontmatter includes `title`, `description`, `publishedAt`, and `slug`.
- Optional `coverImage` can be used for the listing and post page.

## Useful Files

- Repository overview: `README.md`
- Public site pages: `apps/landing/src/pages`
- Landing components: `apps/landing/src/components`
- Landing content config: `apps/landing/src/content/config.ts`
- Dashboard routes: `apps/app/app/(dashboard)`
- App APIs: `apps/app/app/api`
- App shared logic: `apps/app/src/lib`
- Worker entrypoint: `apps/worker/src/index.ts`
- DB models: `packages/db/src/models/index.ts`
- LLM types: `packages/llm/src/types.ts`
- Scoring logic: `packages/scoring/src/score.ts`

## Notes For Agents

- Prefer the README for a quick orientation and the full file for detailed ingestion.
- Prefer typed modules and existing helpers over direct environment or database access.
- Keep blog, pricing, and plan references aligned with the source files rather than duplicating content manually.