Zkt Timer

Zkt Timer is a project born out of my own needs as someone actively involved in speedcubing. I've been cubing for a long time, and after I started competing, I realized that the tools I was using were falling short in certain areas. I needed a more flexible and more powerful system, especially around analysis, the trainer, and the overall user experience.

With that need in mind, I started building a timer for myself, leveraging my software background. My initial goal was simple: to create a system that covered my own use case and that I had full control over. But as development progressed, the project grew. It evolved from a simple timer into a much more comprehensive system with analysis tools, trainer modules, smart cube integration, synchronization, and many other components.

Over a roughly nine-month period, the project evolved significantly. What started as a web application gradually expanded to mobile platforms and became a multi-platform app. Throughout this process, my work wasn't just about adding new features; the real focus was revisiting systems again and again, redesigning some of them from scratch, and making sure all the pieces worked together coherently.

Today, Zkt Timer is a system that began as the result of a single need, grew over time, and is still being actively developed.

Zkt Timer — ibrhyyme
The person who designs and develops Zkt Timer.

Credits

While building Zkt Timer, I actively benefited from existing projects in the speedcubing ecosystem. There is a strong open-source culture that has grown over the years, and I studied many of these projects in detail; I ran some of them, and read others line by line to understand how they worked.

Throughout this process, I learned different things from different places. Some projects guided me on the technical side — for example in scramble generation or solver approaches. Others helped me understand what works well on the trainer and user experience side. Sometimes it was an algorithmic idea, sometimes a data model, sometimes the overall approach of a system that became a reference for me.

Rather than taking these pieces as-is, I revisited each of them so they would fit Zkt Timer's own structure. I rewrote most systems from scratch; I simplified some and extended others. Bringing approaches from different sources together under a single architecture, in a coherent and interoperable way, was the most critical part of this process.

The resulting structure isn't tied to a single source. Rather, it emerged from combining and rebuilding approaches learned from different projects.

I believe this: moving something forward isn't just about adding something new; it's about properly understanding the work done before you and making an honest contribution on top of it. That's why it matters to me to acknowledge everyone who has had a direct or indirect impact on this project.

The projects and developers named below played different roles in shaping Zkt Timer. Some were the starting point of an idea, some helped me solve a problem, and some made it possible for me to see a better approach.

My deepest respect and gratitude to all of them.

— ibrhyyme

What's New in Zkt Timer

This section covers the features designed and developed for Zkt Timer. Each one grew out of the platform's own needs and the feedback that came from its users.

Competition Notification & Countdown System
Zkt Timer generates automatic notifications for the competitions you follow. Registration opening, publication of groups and assignments, results being entered and records being broken are all delivered as notifications, and a countdown runs up to the competition date. The system runs as scheduled jobs on the server and produces both in-app and push notifications.
Record Radar
Calculates in advance which records could fall at a competition you are attending. The competitor list, the event schedule and the current national records are compared to determine which records are at risk, and the result is shown on the competition page.
Native Mobile App
Zkt Timer ships as a native app on iOS and Android. Smart cube connectivity runs through a native BLE layer, and accelerometer and haptic support are provided through native plugins. Edge gestures, safe areas and keyboard behaviour are handled separately for each platform.
Full Offline Mode
Solves can be recorded, sessions can be opened and statistics can be viewed with no internet connection. When the connection returns, pending solves are queued and reconciled with the server, conflicts are resolved, and duplicate records are filtered out by fingerprint.
Battle (1v1) Mode
A mode designed for mobile that lets two people compete head to head on the same device. Players start independently, penalties and scores are tracked separately, and round history is stored in detail.
Cuber Card
A shareable card that turns profile information into a single image. Avatar, name, competition count, medals and WCA records appear on the card. It hooks into the native share sheet on mobile and into a direct download on desktop.

References

The projects below served as references in different ways throughout Zkt Timer's development. Each entry states two things: what was taken from that project, and what was built on top of it.

cubedesk — kash
My strongest reference on the software architecture side of Zkt Timer. How React + SSR, Node.js + GraphQL, PostgreSQL + Prisma and Redis fit together inside a cubing platform was worked out by studying cubedesk by kash. It guided the service organisation and folder structure. Its influence was not limited to the server side: the interface language cubedesk established was also a reference for the timer screen layout, the solve list and the module arrangement. Where we part ways: cubedesk is a web app. I wanted the same codebase to ship to iOS and Android through Capacitor, so I rebuilt the SSR layer, the session handling and the cross-device sync to carry the native side as well.
csTimer + min2phase — cs0x7f
The foundation of scramble generation. The scramble algorithms and subset structure for the puzzle types, the min2phase Kociemba solver and the group theory library were built with reference to csTimer and min2phase by cs0x7f. While moving this code from JavaScript to TypeScript it was restructured around a registry-based generator architecture; every puzzle type now registers its own generator, and the client and the server can produce the same scramble. On top of that, more than 40 CFOP, Roux, Mehta and ZZ subsets, my own 2D renderers for Square-1 and Clock, and a Web Worker layer that runs the heavy solvers without freezing the interface were added.
cubedex — Pau Oliva Fora (poliva)
One of my main references for the user experience side of the Trainer module. How a smart cube connects into a drilling flow was worked out by studying Pau Oliva Fora's project. In Zkt Timer this structure was split into four separate modes (Standard, Smart Cube, Recognition, Efficiency); per-algorithm statistics were kept, the queue order was made to adapt to the cases a user is weak at, and 2D and 3D pattern visualisation plus PDF export for printing algorithm sheets were added.
cubingapp — spencerchubb
A large portion of the algorithm collection used in the Trainer came from the cubingapp dataset created by spencerchubb and was adapted to Zkt Timer's data model. The setup algorithms were regenerated with my own scripts, the pattern images were run through my own rendering pipeline, the collection was split into 31 categories and extended with algorithms of my own.
RubiksSolverDemo — or18
The starting point for the Cross, XCross, EOCross and F2L pair solver logic. The coordinate-based IDA* implementations developed by or18 were a fundamental reference in the design of Zkt Timer's solver system. The work in this module was porting and adaptation: the solvers were moved into a Web Worker architecture and wired into a step-by-step solution interface. The mathematics behind the algorithm belongs to or18.
LetsCube — coder13
The conceptual basis for 1v1 rooms and the friendly-race format comes from this project. How a synchronised, shared solve model is built was worked out by studying coder13's work. Zkt Timer's room system was written from scratch on top of that idea, and the following were added as things I considered missing in LetsCube: smart cube support inside rooms, live chat, spectator mode, room moderation and user banning, a 1v1 duel mode, and a Socket.IO layer that broadcasts across multiple servers through Redis.
competitor-groups — coder13
A project built so competitors can follow their own groups and assignments at WCA competitions, and it does that job very well. I did not want competitors to have to visit a separate site for this information, so the same experience was brought inside Zkt Timer. A competitor's own schedule, their judging and scrambling assignments, their per-event personal bests and their round results are now gathered on a single screen. The layout of the group screens took shape under the influence of this project.
wca-live — WCA Software Team
A platform built for following WCA competitions live, and one that solves round-by-round result flow genuinely well. The WCA Software Team's work was the direct source for the structural approach of the WCA Live integration in Zkt Timer. The ZKT competition platform itself was written from scratch for Zkt Timer: registration, scorecard entry, batch entry mode, round management, judge, scrambler and runner assignment, national record tracking, delegate management, A/B day-split competitions and WCIF generation. What was taken from wca-live is the logic of the delegate workflow.
Rubik-Cube — Dev-tanay
The interactive 3D cube on the landing page was ported one-to-one from this project by Dev-tanay. The source was written against Three.js r95; the changed APIs were adapted while moving it to r125 and the code was converted to TypeScript. The class structure and method names stayed the same as the source. My addition was wiring the cube into Zkt Timer's timer: scramble generation, solve detection and timing. In this entry the skeleton of the code belongs to Dev-tanay.
pll_recognition_trainer — Roman Strakhov
The direct basis for the PLL Recognition Trainer module. The keyboard-driven PLL recognition practice, the two-sided recognition guide and the adaptive repetition logic came from Roman Strakhov's project. The source was written in Vue; the module was rewritten in React and TypeScript. During the rewrite the recognition guide was completed to cover all 73 cases, and an on-device history layer, a glossary view and a 13-step guided quest were added. The module is roughly four times the size of the source today.

Libraries Used

Core cubing libraries used directly in Zkt Timer's infrastructure.

cubing.js — Lucas Garron & the cubing.js team
The core library used for smart cube state tracking, WCA notation, and KPattern matching. Developed by Lucas Garron and the cubing.js contributors.
gan-web-bluetooth — afedotov
The library that provides Bluetooth connection management and gyroscope/motion logic for GAN smart cubes. The Smart Cube module is built on top of this library.
cubejs
A core cube solver library used in various analysis and solve features.

Open Source

Zkt Timer is built on top of hundreds of open-source packages, including React, Apollo, Prisma, and Three.js. The full list of dependencies can be found in the package.json file. A heartfelt thanks to everyone who has built and maintained these libraries over the years.

To the Community

To the WCA and the global speedcubing community. A remarkable worldwide community has been built around a single puzzle. The real reason Zkt Timer means anything is that it gets to be a part of this community.

Copyright Notices

Portions of this software reference code or concepts from the projects mentioned above. Each project retains its own original copyright. Zkt Timer's own architecture, systems, and features are subject to the following copyright:

This project is released under the GNU General Public License v3.0.