Knoxis

The problem and constraints

Knoxis exists to run a specific, high-stakes ritual: a church electing presbyters and deacons by secret ballot, the way Presbyterian churches have done it for generations, with a paper ballot and multiple rounds of counting until every seat is filled by a real majority. The client wanted that ritual on a computer, and the one requirement that shaped everything else was that “secret” had to mean something stronger than “we promise not to look.”

That’s a sharper constraint than it sounds. A typical web form can log every request, keep every database row forever, and nobody outside the team ever notices. The cost of that carelessness is usually a slow query or a slightly bloated table. Here, the same carelessness (storing who voted next to what they voted for, even briefly, even “just for debugging”) is the one failure that would make the whole system worthless to a church that exists specifically because it doesn’t trust informal, undocumented processes to handle something this sensitive.

The second constraint was the shape of church governance itself, which doesn’t map onto a flat list of interchangeable “users.” A presbytery has multiple offices up for election at once, each with its own number of open seats; the rule for winning is a simple majority of votes cast, which routinely takes more than one round when nobody clears 50%; and the very last round can switch to “whoever got the most votes wins,” specifically to guarantee the process actually ends. None of that is exotic, but all of it needed to be represented faithfully: a “majority” calculation that’s off by one seat, or a system that can’t cleanly carry the same remaining candidates into a second round, would undermine the same trust the secrecy design was protecting.

The third constraint was scope discipline against real pressure to add things. The client was open to infrastructure like Redis if the system needed it (a real-time push notification, a background job queue, a distributed cache), and the honest answer, checked case by case, was that at the expected scale of a single congregation’s election, none of those needs were real yet. Adding Redis “to be safe” would have meant a fourth moving part in production, a bigger attack surface, and more to reason about for a system whose core promise is trustworthiness through simplicity; raw throughput was never the point.

The fourth constraint was that a CPF (the Brazilian national identifier used to check a voter against the church’s membership roll) is itself sensitive personal data under Brazilian law, and the system’s only real need for it is a yes-or-no match at the door. Anything beyond that minimum, including the temptation to just keep it around “in case it’s useful later,” was a liability with no corresponding feature to justify it.

The last constraint was multi-tenancy from day one: a platform where any number of congregations run their own elections, completely isolated from each other, without each one needing its own database, its own deployment, or its own migration history to keep in sync.

Architecture

A voter opens the ballot flow and identifies with a CPF. The backend normalizes it, validates the check digits, computes a keyed HMAC hash, and looks it up against the church’s voter roll for that specific election: a single indexed comparison, no different in speed from comparing plain text, except that the plaintext CPF is never the thing sitting in the database. A match issues a ballot_session: a short-lived token, handed back in an httpOnly cookie, that represents “this specific person is now allowed to cast this specific ballot” without yet saying anything about what they’ll choose.

Submitting the ballot is where the architecture’s real promise gets kept. In a single database transaction, the backend locks the ballot session row, confirms it hasn’t already been used and hasn’t expired, marks it used, and then writes to two separate tables: voter_attendance records that this voter participated in this round (it has a voter ID, because knowing turnout and preventing double-voting both require it), and votes records the actual choices, for each open office, with no voter ID, no CPF, no reference back to the ballot session at all. There is no foreign key a query could follow from one table to the other. The vote timestamp itself is truncated to the minute, which quietly reduces the value of trying to correlate “who was active at 7:42:03” with “what got recorded at 7:42:03,” an imperfect defense in a tiny election with long gaps between voters, but a real one at the scale this system actually runs at.

Every one of those tables, and every table in the system, carries an organization_id: the boundary that keeps one church’s election completely invisible to another. That boundary is enforced by a mixin that every API viewset in the system is required to inherit, which filters every read by the logged-in organization and silently injects the tenant on every write, ignoring anything a client might try to send instead, no separate database or Postgres row-level security policy involved. Because that guarantee lives in application code rather than the database engine itself, it’s backed by a second guarantee at the test level: a single regression test walks every registered viewset in the project and fails the build if any of them was written without the mixin.

While a ballot round is open, the organizer watches a live tally in a separate, admin-only view (never visible to voters), updated by polling the backend every three seconds rather than any push mechanism. An ETag built from the round’s ID, its status, and its current vote count means an unchanged tally costs the server almost nothing to answer: a 304 Not Modified and no query. When the round closes, the same aggregation query determines who cleared a real majority of the votes cast, and whoever remains short of a seat carries straight into the next round automatically, with the same candidates and the same open seats, until every position is filled, on the last round, by whoever received the most votes, exactly as the church’s own printed rules require.