Jun 2023
Puzzle and Key Universe (PnKU) Website
An open-source platform for Puzzle Hunt events; contributed as a core collaborator across platform features, event-specific development, and production operations.
- React
- TypeScript
- Python
- Ant Design
- Puzzle Hunt
- Operations
Project overview
PnKU Website is an open-source platform for running Puzzle Hunt events. I joined in June 2023 as a core contributor, but I am not the project’s primary lead. Development is event-driven: the platform remains in maintenance between events, with focused development as each new event is prepared.
The platform has supported PnKU2, PnKU3 Part I, and PnKU3 Part II. Both the platform and each event are collaborative efforts involving multiple contributors.
Platform architecture
The public repository uses React, TypeScript, Vite, and Ant Design on the frontend, alongside Tailwind CSS, React Router, and SWR. Its Python backend includes Sanic, Flask, Pydantic, and SQLAlchemy, with MariaDB / MySQL for storage and Docker plus Nginx for deployment.
The server models event behavior as a state machine: the database primarily stores operations, while current state is computed and retained in memory. This is the project’s shared architecture, not a system I claim to have designed independently.
Platform contributions
My regular work has focused on frontend development, including in-site messaging, support tickets, and hints.
For individual events, I have also implemented selected puzzles with complex interactions. That work included both their frontend experiences and the corresponding Python adhoc state-transition logic. The screenshot below demonstrates the type of event-specific interface supported by the platform; authorship of the pictured puzzle is separate from my platform contributions.
Interactive puzzle page from P&KU3 Part I; puzzle author: esc
Event scale and operations
The latest event served more than 700 active teams and approximately 2,000 users. I also supported production operations as one member of a three-person operations team, helping diagnose incidents, execute recovery, and monitor the service through restoration.
The event experienced two service interruptions lasting at least 10 minutes, along with several shorter fluctuations and live updates. I directly executed the recovery procedure for one of the two longer interruptions. This gave me hands-on experience with the full path from incident detection to service restoration at real event scale; unconfirmed root causes, exact recovery times, and availability metrics are intentionally omitted.
Current status
The project is currently maintained between events. New development is concentrated around future event preparation and the requirements of each event.