FECOT

The problem and constraints

FECOT is the regional body that certifies who holds which taekwondo belt across four Brazilian states. That single fact (rank) is the whole point of a federation existing: it decides who can compete in which category, who is allowed to teach, and whether the federation’s own certificate means anything to the national league it answers to. Before this rewrite, that data lived in a system where the story of how a change happened wasn’t part of the design.

The client, Luciano Bezerra da Cunha, brought a working but aging Ruby on Rails monolith and one clear priority: rank could not be a field like any other. Everything else (modernizing the stack, typing both ends of the API) mattered, but the actual constraint shaping this project was that a federation’s authority rests entirely on people trusting its records, and a record anyone with admin access can quietly edit is only an opinion with a timestamp.

The second constraint was who actually uses this system and how. Athletes aren’t self-registering from a laptop; they’re teenagers and adults enrolled in bulk by their teacher, frequently right there on the training mat, with no email address handy and no moment where handing them a “click here to set your password” link makes sense. Any auth design that assumed a self-service signup flow would have been solving a problem this federation doesn’t have, while ignoring the one it does.

The third constraint was operational honesty about scale: one developer building for a regional sports federation on a single VPS, with no staging environment, no dedicated security function, and no platform team or venture funding behind any of it. Every control (password handling, authorization, upload safety) had to be something one person could reason about completely, because there’s no second reviewer and no incident-response team behind it.

The fourth constraint came from the domain’s own hierarchy: teachers, academy managers, and administrators, and every one of them is also, unavoidably, an athlete with their own belt and their own training history. A teacher without at least a first-degree black belt fails the sport’s own rules for the role, before the software ever gets involved. Whatever model got built had to represent that a manager or teacher is a specialization of “athlete,” the same underlying entity carrying an extra role.

The last constraint was continuity: the Rails system already encoded years of real business rules: which grade requires which rank to teach, how graduation levels are named and ordered, who is allowed to register whom. A rewrite that “modernized” the stack while quietly losing one of those rules would have been a worse outcome than not rewriting at all. Every rule visible in the old code needed a deliberate decision about whether it carried over.

Architecture

A teacher, an academy manager, or an admin opens the Next.js frontend and does everything through one typed API client. There is no other path from the browser to the backend, and no component reaches across that boundary with an untyped fetch call. That single chokepoint is what makes it possible to say, with confidence, that a contract change on one side is caught on the other: if the backend’s response shape moves, the frontend’s types stop compiling instead of quietly rendering undefined.

The FastAPI backend is the only process with write access to PostgreSQL. Two layers of authorization sit in front of every write: role guards at the endpoint level (an endpoint simply refuses a role that shouldn’t be there), and contextual rules evaluated in the domain model itself: a teacher can edit their own students, an academy manager can edit anyone at their academy, an admin can edit anyone. Both layers run in the backend, never in the frontend: enforcement has to live where a user can’t route around it by editing what’s rendered in the browser; the constitution of this project says so explicitly, and the test suite is what actually holds it to that.

The graduation flow is where this architecture is most visible in practice. Nothing in the system (no endpoint, no admin shortcut, no internal script) writes to an athlete’s graduation field directly. The only way that value changes is through a GraduationRequest: a teacher, manager, or admin creates one, which snapshots the athlete’s current grade automatically; only an admin can approve or reject it; and the decision, the reviewer, and the timestamp are all recorded permanently, whether the request was approved or turned down. An athlete can have at most one pending request at a time, which closes the one loophole that would otherwise let someone route around the single-pending-request audit trail by just filing another request before the first is resolved.

Authentication sits underneath all of this as a deliberately simple layer: a stateless JWT, cached in the browser, revalidated against the database on every request rather than trusted at face value. That revalidation step is what makes deactivating an account actually mean something. The token itself doesn’t expire for up to 24 hours, but the backend checks whether the athlete behind it is still active before honoring anything the token claims. Avatar uploads follow the same instinct for verifying rather than trusting: every image is decoded, flattened onto a white background, resized, and re-encoded to WebP before it’s ever written to disk, so nothing a user uploads is served back byte-for-byte. A renamed executable or an image with an embedded payload never survives that round-trip intact.