Xkye Solutions case study: an internal tool we build and use every day

Issues, plans and docs that speak one language.

Kova is where Xkye plans its work, tracks every issue, and writes everything down. It runs in the browser and in the terminal, and every screen uses words we agreed on before we built it.

Studio
Xkye Solutions
Platform
Web app, installable PWA & CLI
Scope
Product, design & engineering
CONTEXT.md
Suspend

To stop a member from using Kova without forgetting them: their memberships, history and name stay, their access tokens are revoked, and they can be restored.

Avoid deactivate disable ban
Chapter 1

A studio that keeps its own house in order.

Xkye runs its own product, Dalqen, alongside client engagements like Renigo and the work of running the studio. Every one of them needs a backlog, a plan, and somewhere to write down what was decided and why.

Kova is that place. It is a single installation for one company, built by the people who use it, and its own backlog has lived in Kova since the first working slice.

kova /

Kova is a desktop tool, so the prototype is easier to use on its own, full screen.

Chapter 2

Work in one place, writing in another, and words that drift.

The trouble with project tools is rarely a missing feature. It is the gap between them, and the way the same word means three things depending on who you ask.

Issues and documents live apart

The spec is in one tool and the work in another. A decision written down last month can’t show whether its issues ever shipped.

“Archive” means whatever you need it to

Does deleting hide something, or lose it? Is a deactivated person gone? When the vocabulary drifts, people stop trusting the buttons.

Developers live in a terminal

A tool that is only a website is one more tab. The people closest to the code want to read and move issues where they already are.

How might wegive a small studio one place for its work and its writing, where every word means exactly one thing, in the browser and on the command line?
Chapter 3

One roster, every state it can be in.

A person’s relationship with Kova is a real thing with a lifecycle, not a row in a users table. Owners govern the installation, and Project memberships decide what everyone else can reach.

KDKova DeveloperOwner: governs the installation, a full member of every ProjectActive
AAAda AdminA second Owner. At least one must always stay active.Active
MMMira MemberReaches only the Projects she belongs toActive
PPPat PendingInvited, and the invitation lapsed after 24 hoursInvited
SSSam SuspendedCan’t sign in, but their history and name staySuspended

These five come straight from the sample data the team develops against. Each one stands for a state the system has to handle, so every screen that shows “who” has a real answer to show.

Chapter 4

Five rules that shaped every screen.

  1. Words before screens

    Every concept is defined in a glossary, with the words to avoid, before it gets a button. The interface, the API and the CLI all use the same terms.

  2. The address is the state

    A Filter lives entirely in the URL, so a narrowed list is a link you can paste to a colleague and they see exactly what you see.

  3. One seam for browser and terminal

    The web app and the CLI call the same versioned API, so neither one can quietly drift from the other.

  4. Dense, not cramped

    A console that actually uses a desktop’s width: small type with steps a reader can tell apart, and rows that fit a scanning eye.

  5. Nothing is lost by accident

    Archive keeps things. The Trash waits 30 days. Suspending keeps someone’s history. Document Versions are never thrown away.

Chapter 5 · Key flows

Areas, not apps

The strip at the far left switches between Kova, Kova Docs and, for Owners, Admin. Each Area has its own navigation and remembers where you left it, so moving from an issue to a document and back is one press that keeps your place.

  • No top bar anywhere. The bell, search and the fold control moved into the panel header, so the content gets the full height.
  • Home answers “what needs me?” with your open issues, anything waiting on your review, and the running Sprints, each with its progress counted from the issues themselves.
  • Admin shows its count on the strip whenever something is waiting on an Owner.

Filters that are links

Narrow any issue list by Status, Priority, Assignee, Project or Placement. Values within one field are alternatives, and fields narrow together. The whole Filter is carried in the address.

/issues?status=in_progress,blocked&assignee=me
  • “Me” and “Unassigned” are values, not special views, so “my blocked work” is just a Filter.
  • A Saved filter is named and private. It shows up in your own panel and nobody else’s.
  • The keyboard is a first-class path: j and k move through the rows and Enter opens one.

Watch the address bar above the prototype change as you pick values.

Board and plan

A Project’s screens sit in one row of tabs (Overview, Issues, Board, Plan, Docs and Settings) and every tab is a real address. The board moves work between statuses, and the plan moves it between the Backlog and Sprints.

BeforeProgress was a percentage someone remembered to update.
After“3 of 12 issues done” is counted from the issues, so it can’t go stale.
  • Status is never colour alone. Every chip carries an icon and its word, so the tint is emphasis rather than information.
  • A new Project copies the Planning Defaults, so changing the defaults later never rewrites a Project that already exists.

An issue, and getting to it

An issue reads like a document: a Markdown description, then its history and comments in one timeline. Its properties sit to the side, each one a single click to change.

  • Keys are published addresses. DAL-1 is allocated once per Project, never reused, and works the same in a link, a document and the CLI.
  • ⌘K reaches everything: any destination, any issue, any document, and the common commands, without leaving the keyboard.

Kova Docs

Documents are written in a Space inside a Project, and read in one Area across every Project you belong to. Each one starts as a Draft that only its author and their invited collaborators can see.

  • Embeds are live. The issue list in this Draft is drawn from a Filter, so moving a card on the board changes the document without anyone editing it.
  • Publish is one-way and says so before you press it. Archiving retires a published Document without breaking a single link to it.
  • Type / on an empty line for headings, toggles, callouts, a table of contents that rebuilds itself from the headings, and Embeds.

Versions mark moments, not saves

Several people can edit a Document at once, so Kova doesn’t ask anyone to save. A version is taken automatically once the editors go quiet, and anyone can name one by hand, for example “Sent to client”.

  • Every version is kept for as long as the Document exists, and reading one is clearly marked as read-only.
  • An Icon and a Cover belong to the Document, not its content, so changing them never creates a new version.

Admin and the Confirmation code

Admin opens on Needs attention, a queue of things waiting on an Owner, such as an expired invitation or someone suspended for longer than the review period. Each item leaves the queue when it’s dealt with.

Usual approachRe-enter your password for anything sensitive, then do whatever you like.
KovaA six-digit code names the exact act it confirms, and lets guarded acts through for five minutes.
  • Only acts that move ownership or end a membership for good are guarded: Make Owner, demoting or suspending an Owner, and Remove from Kova.
  • Suspending unassigns someone’s unfinished issues, and restoring them doesn’t hand the work back, so nobody stays assigned to work they can’t reach.
Chapter 6

The glossary came first.

Kova’s repository opens with a glossary. Every concept is defined once, in plain words, together with the words not to use for it. Those terms then become the labels, the API fields and the CLI commands, so a person never has to translate between them.

Chapter 7

The same Kova, in a terminal.

The kova CLI calls the same API as the browser. It signs in with a personal access token kept in the system keychain, never passed as an argument, and every failure carries a request id the server can trace.

~/xkye/dalqen

The commands and arguments are the real ones. The output here is shortened for the page.

Chapter 8

Built so the rules can’t be skipped.

Product behaviour lives in use cases, not in routes or screens. The web server is the only place the system is put together, and the database refuses anything a migration hasn’t explicitly granted.

24
Database migrations, each checked to be applied and to lint cleanly before a release
35
pgTAP suites that test the database’s own rules, including who can see what
316
Test files across the apps and packages, plus browser suites for the critical web flows
52
Colour pairs measured for contrast across both themes, with an automated accessibility scan as the lasting gate
0
Credentials allowed in the repository or its history. A scan checks every tracked file and every past commit.
Chapter 9

One family of marks, one set of tokens.

The interface is built on a token layer: a colour is written in exactly one place, and every component asks for a role like “surface” or “muted text” rather than a hex value. That is what makes the dark theme a peer of the light one instead of an inversion.

Brand colour

Kova Navy#06142D
Deep Blue#032EA4
Action Blue#0449D4
Electric Blue#0497F8
Sky Cyan#52DDFC
Paper#F5F8FF

Logo

Kova primary logoKova, primary
Kova reverse logoReverse, on navy
Kova Docs logoKova Docs

Type

Sprint 4 reviewInter · 22 · 600
Ship the issue read sliceInter · 14 · 400
Edited 4 min agoInter · 12
DAL-1 · 19 OctJetBrains Mono · 11.5

Inter in the product, Outfit for brand moments like this page. Issue keys and dates use tabular figures so columns never shift.

Status, with a shape and a word

Todo In progress In review Blocked Done Cancelled

Priority, a different family

Urgent High Medium Low

Surfaces, light and dark

Default
Tertiary text
Default
Tertiary text

The theme is a cookie read on the server, so the first byte is already the right theme. There’s no flash of the wrong one to hide.

Chapter 10

What the design holds itself to.

These aren’t usage numbers. They are promises the product makes and the test suites check on every change.

1 link
For any narrowed list

Paste it and your colleague sees the same issues, in the same order.

5 min
For guarded acts after one code

Long enough for a batch of changes, short enough that an open laptop isn’t a risk.

30 days
In the Trash before a purge

Only a Draft or an archived Document can be deleted at all.

1 place
Where each colour is written

Components ask for a role, so a theme can’t be written twice or drift.

Reflection
The hardest part wasn’t a screen. It was agreeing that archive, delete and purge are three different things, and writing that down before we built any of them.