-
-
Public gallery where submitted projects can be discovered by project, team, and track without exposing private judging information.
-
Normalized project rankings alongside judge review counts, score means, and statistical variation.
-
Result-integrity dashboard showing normalization freshness, review changes, pending reviews, and publication status.
-
Live judging dashboard showing overall completion, per-track review requirements, remaining reviews, and assignment health.
-
Organizer view of submitted projects with teams, tracks, submission status, judge assignments, and completed reviews.
-
Judge workspace showing assigned reviews, completion progress, track scope, and completed evaluations.
-
Participant-facing workspace showing the submitted project, team, submission status, deadline state, and public project access.
-
RUNBOOK converts event data into actionable states such as Complete, Active, and Stale, with reasons and recommended next actions.
-
Detailed judging progress by track, remaining reviews, assignment coverage, and normalization freshness.
-
The main operational command center showing event health, judging progress,assignment gaps,normalization status and the current next action.
-
Role-based sign-in with reproducible demo accounts for organizers, admins, judges, and participants.
-
Event overview showing RUNBOOK's hackathon workspace, tracks, submissions, teams, and judging status in one place.
Inspiration
What it does
How I built it
Challenges I ran into## Inspiration
Running a hackathon involves much more than collecting project submissions. As the number of teams grows, organizers have to keep track of submissions, teams, judging assignments, reviews, deadlines, scores, and results.
The challenge is not only having this data, but understanding what the data means at any given moment.
We wanted to build a system that could help organizers quickly answer:
What is happening? What needs attention? Why? And what should happen next?
That idea led to RUNBOOK.
What it does
RUNBOOK is a self-hosted hackathon submission and judging platform with an operational command center for organizers.
It supports the workflow from participant submissions through judging, score normalization, and results.
The Runbook layer continuously derives the operational state of the event from its underlying data. Each stage can be identified as:
- UPCOMING
- ACTIVE
- COMPLETE
- BLOCKED
- STALE
Each state provides relevant context such as the reason, supporting evidence, next action, and the page where the action can be performed.
For example, if judging data has changed after normalization, RUNBOOK can identify the normalization result as STALE and indicate that normalization needs to be performed again.
The core idea is:
Event Data → Operational State → Reason → Next Action
How we built it
We built RUNBOOK as a lightweight, self-hosted web application.
The backend is built with Python and Flask, with SQLite used for persistent event data. The user interface uses server-rendered HTML templates with Jinja2, along with CSS and JavaScript.
The application is organized around separate components for:
- Authentication and role-based authorization
- Event, team, and project management
- Submission workflows
- Judge invitations and assignments
- Rubric-based judging
- Score normalization
- Publication and results
- CSV exports
- Operational state calculation
The Runbook engine uses deterministic rules and the current event data to calculate workflow states instead of relying on generated guesses.
The application is containerized using Docker and includes automated tests and acceptance checks for validating the main workflows.
Challenges we ran into
One of the biggest challenges was converting complex event data into a simple and useful operational state.
A workflow is not always simply "complete" or "incomplete". For example, judging may be active, a normalization result may become stale after a review changes, or a required dependency may prevent the next stage from progressing.
We therefore had to carefully define the conditions for each operational state and make sure that the system could explain why a state was produced.
Another challenge was maintaining proper separation between the operational view and actual system permissions. A Runbook status should describe what is happening without incorrectly changing what a user is allowed to do.
We also had to handle authentication, role isolation, submission deadlines, judge assignments, incomplete reviews, score normalization, duplicate fixture data, and reproducible testing.
Accomplishments that we're proud of
We are proud of building RUNBOOK as a complete hackathon workflow rather than only a submission dashboard.
The system brings together:
- Participant and team workflows
- Project submissions
- Judge assignment
- Rubric-based reviews
- Score normalization
- Results and exports
- Operational monitoring
We are especially proud of the Runbook operational layer, which turns the underlying event data into clear states, reasons, evidence, and next actions.
We also built the project to run locally in a self-contained Docker environment and added automated tests and acceptance checks to verify the important workflows.
What we learned
Building RUNBOOK taught us that useful automation is not just about adding more features.
The important part is connecting raw data to meaningful, explainable decisions.
We learned how to design deterministic business rules, handle workflow dependencies, enforce authorization on the backend, manage state changes, validate edge cases, and test complete user workflows.
We also learned the importance of designing around the questions users actually need answered rather than simply exposing the underlying database information.
What's next for RUNBOOK
We want to continue developing RUNBOOK into a more complete operational platform for hackathon organizers.
Some of the areas we would like to explore next are:
- More configurable workflow rules
- Better activity and stale-state detection
- Organizer notifications
- Improved event analytics
- More detailed audit history
- Stronger production security
- Support for larger and more complex events
Our long-term goal is simple:
When an organizer opens RUNBOOK, they should immediately understand what is happening, what needs attention, why it matters, and what they should do next.
Log in or sign up for Devpost to join the conversation.