Kova

How Kova works

The short version: things that happen at a customer come in as events, Kova stores every event, rebuilds the account from them, scores it, and tells the CSM when it slips. Everything below is running on this site right now. You can try it or call the API.

Overview

Dashboard buttonsVisitor clicks a scenarioAPI Explorer / cURLVisitor sends a real requestCustomer systemsHubSpot, Zendesk, Stripe…dashed: how a real customer connectsKova APINext.js on Vercel · auth, checks, limitsScoring engineReplays events, scores, explainsPostgres (Supabase)Sandboxes and event historyDashboardPolls the API every 3 secondsAI model (optional)Anthropic API: alerts, QBRsMake scenarioWebhook → GmailVisitor's inboxThe at-risk alertPOST eventsGET accountband dropsalert

Solid arrows are live on this site. The dashed one is how a real Kova customer would feed it; here, the buttons and the API Explorer stand in for those systems.

One event, end to end

What happens when you click “Customer at risk” and the first event, “weekly usage falls to 17”, is sent:

  1. Request. The browser sends POST /api/v1/events with the sandbox key as a bearer token.
  2. Checks. Kova checks the key, confirms the sandbox hasn't expired, applies the rate limit, and validates the event type and payload. Anything wrong gets a clear error: 400, 401, 410, 413, 422 or 429.
  3. Store. The event is written to Postgres. Events are never edited or deleted, except by a full reset.
  4. Rebuild. Kova replays every event for the account, in order, to rebuild its current state: seats, active users, features, tickets, contacts, NPS, invoices.
  5. Score. Five components (usage, feature adoption, support, relationship, commercial) are scored with written reasons, and the rules engine picks a next step.
  6. Compare. If the account has dropped into a worse band (healthy to at risk, or at risk to critical), an alert is written, by the AI model if one is connected or by a template if not.
  7. Deliver. If the visitor gave an email and hasn't used their 3 emails, Kova posts the alert to a Make webhook. Make sends it through Gmail.
  8. Log. Every outbound call is recorded with its status and timing, and shown in the dashboard's integration log.
  9. Show. The response carries the new score. The dashboard updates straight away; anything sent from outside (cURL, Postman) appears within 3 seconds because the dashboard polls.

Design decisions

Store events, not scores

Kova keeps the history of what happened and works out the score from it each time. Every score can be traced back to the events that caused it, which is what a CSM needs when a customer asks “why are we red?”. It also means a change to the scoring model rescores the whole history, with no migration.
Trade-off: replaying gets slower as history grows. Fine at this scale; in production I'd add a snapshot every few hundred events.

Rules first, not machine learning

The score is a transparent weighted model. A new customer can check it against their own instinct in the first week, and it works from day one without months of churn data.
Trade-off: it won't spot patterns nobody thought to write a rule for. Once a customer has a year of renewals and losses, a predictive model can be tested against the rules, not instead of them.

Alerts on band changes only

Alerting on every score movement trains people to ignore alerts. Kova only alerts when an account crosses into a worse band, with a cooldown and a hard cap on emails per sandbox.

A private sandbox for every visitor

Each visitor gets their own account and key, so one person's experiments never spoil another's demo. Sandboxes and any email addresses expire after 7 days.

Hand off to a workflow tool for delivery

Kova doesn't send email itself. It posts to a webhook and Make does the delivery. Swapping Gmail for Slack, Teams or a CRM task becomes a change in Make, not in Kova's code, which is how most customers want to work.

Secrets stay on the server

The database key, AI key and webhook address live in the hosting environment, never in the code or the browser. The only key a visitor sees is their own sandbox key, which can only touch their own sandbox.

Stack

PartToolWhy
Web app and APINext.js, TypeScriptOne codebase for pages and API routes
HostingVercelDeploys on every GitHub commit, secrets kept in environment settings
DatabasePostgres on SupabaseReached through its REST API, row-level security on
Alert workflowMake, GmailWebhook trigger, email step, run history for debugging
AI writingAnthropic APIOptional, with a template fallback so nothing breaks without it

Command-line client

kova.sh is a small Bash client for the API: curl for the requests, jq for readable output when it's installed, and clear errors when something's wrong. It keeps the sandbox key in a file only you can read. You can also try the same commands in the terminal on the home page.

curl -sO https://<this-site>/kova.sh && chmod +x kova.sh export KOVA_URL=https://<this-site> ./kova.sh new # create a sandbox ./kova.sh score # score, reasons, next step ./kova.sh send contact.left role=champion # send a real event ./kova.sh send usage.weekly active_users=14 logins=30 ./kova.sh events # recent history ./kova.sh reset # back to the start
$ ./kova.sh send usage.weekly active_users=14 logins=30 Weekly usage: 14 active users, 30 logins Health: 76 -> 58 (at_risk) Alert raised: the account dropped a band

Run Kova on a Linux server

The live site runs on Vercel, but Kova is a standard Node.js app and runs on any Linux server. On Ubuntu 24.04, as a user with sudo:

1. Install Node.js and create a service user

sudo apt update && sudo apt install -y git curl curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs sudo useradd --system --create-home --shell /usr/sbin/nologin kova

2. Get the code and build it

sudo -u kova git clone https://github.com/amakai-nkay/portfolio.git /home/kova/app cd /home/kova/app sudo -u kova npm ci sudo -u kova npm run build

3. Keep the secrets out of the code

sudo tee /etc/kova.env > /dev/null <<'EOF' SUPABASE_URL=https://your-project.supabase.co SUPABASE_SERVICE_ROLE_KEY=your-service-role-key N8N_WEBHOOK_URL=https://hook.eu1.make.com/your-webhook EOF sudo chown root:kova /etc/kova.env sudo chmod 640 /etc/kova.env

4. Run it as a service that restarts itself

sudo tee /etc/systemd/system/kova.service > /dev/null <<'EOF' [Unit] Description=Kova After=network-online.target [Service] User=kova WorkingDirectory=/home/kova/app EnvironmentFile=/etc/kova.env ExecStart=/usr/bin/npm start -- -p 3000 Restart=on-failure [Install] WantedBy=multi-user.target EOF sudo systemctl daemon-reload sudo systemctl enable --now kova systemctl status kova --no-pager

5. Put it behind nginx and open the firewall

sudo apt install -y nginx sudo tee /etc/nginx/sites-available/kova > /dev/null <<'EOF' server { listen 80; server_name kova.example.com; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } } EOF sudo ln -s /etc/nginx/sites-available/kova /etc/nginx/sites-enabled/ sudo nginx -t && sudo systemctl reload nginx sudo ufw allow OpenSSH && sudo ufw allow 'Nginx Full' && sudo ufw enable

6. Check it and watch the logs

curl -s -o /dev/null -w "%{http_code}\n" localhost:3000/api/v1/account # 401 means it's up and asking for a key journalctl -u kova -f # follow the logs sudo systemctl restart kova # after pulling new code and rebuilding

Add HTTPS with sudo apt install -y certbot python3-certbot-nginx and sudo certbot --nginx once the domain points at the server.

What changes in production

This is a demo, and some things are deliberately simpler than they would be for a paying customer. What I'd add: