A study platform with payments, access control and timed exams

+-------------+  +-------------+  +------------------------+
| sales       |  | student     |  | operations panel       |
| site        |  | app         |  | with mandatory 2FA     |
+------+------+  +------+------+  +-----------+------------+
       |                |                     |
       +----------------+---------------------+
                        | Server Actions
                        v
+----------------------------------------------------------+
| shared packages, on the server: pricing, access,         |
| billing, security, question generation and tax           |
+------+--------------------+---------------------+--------+
       |                    ^                     |
       v                    | signed webhook      v
+-------------+  +----------+---------+  +-----------------+
| PostgreSQL  |  | checkout hosted by |  | language model, |
| with RLS    |  | the payment        |  | schema-checked  |
|             |  | provider           |  | output          |
+-------------+  +--------------------+  +--------+--------+
                                                  v
                              +-------------------+--------+
                              | a question stays inactive  |
                              | until human review         |
                              +----------------------------+

Context and problem

People preparing for Brazilian civil-service exams buy generic material and can’t tell whether they’re ready for their specific exam. The product sells access per exam and runs timed mock exams that are comparable across students. To do that it has to charge without trusting the browser, grant and revoke access without money mistakes, and use AI to produce questions without publishing anything a person hasn’t reviewed.

Architecture

A monorepo with three Next.js apps (sales and content site, student app, operations panel) and shared packages. Critical rules (pricing, access, billing, security, content generation, tax) live in the packages, so all three surfaces run exactly the same logic.

• Data: PostgreSQL with versioned migrations. New sensitive tables ship with RLS and with anonymous-role privileges revoked.
• Identity: separate authentication instances for students and admins, with distinct secrets and cookies, lockout after failed attempts and mandatory 2FA for admins.
• Money: prices computed on the server, provider-hosted checkout, signed and idempotent webhooks, and refunds or chargebacks revoking access in the same transaction.
• Timed exams: timer, question draw and grading on the server, with a transactional lock so two simultaneous exams can’t award two ranking credits.
• Question generation and exam reading: question generation and PDF exam extraction with structured output re-validated against a schema; PDF text is treated as untrusted data; the maximum cost is reserved before every call.
• Jobs: idempotent routines for LGPD (Brazil’s data protection law), batched campaigns and a tax queue with leases, each with a heartbeat that alerts on absence.

Challenges

• Optimistic documentation. The docs said all nine critical business rules held. A line-by-line audit showed only two held without caveats. The four money and access gaps were fixed in six days, with an ADR for each.
• A green CI that checked little. Type-checking didn’t run on the apps and the e2e suite executed nothing. At the same time the compiler overflowed its stack on an ORM-generated type and hid 45 errors; the cause was isolated by testing variants one by one.
• Latency no code change would fix. The measurement pointed at the distance between function and database, not at the queries.
• Selling without delivering. Checkout accepted an item with no published material. The fix was a single “deliverable offer” predicate used by publishing, checkout and the catalog.

Solution

Money, access and personal-data rules moved out of the screens into packages tested against a real Postgres. Each became an invariant with an owner, a test and a mandatory review gate that can block the change. Where the failure was a race, the fix used a database primitive (conditional write, transactional lock, re-read inside the transaction) instead of an external lock. Delivery is now controlled by CI and by a local gate that requires checks on the exact commit and a review kept separate from the implementation.

What I would do differently

I’d write the concurrency tests before the screens, not after the audit. And I’d treat status documentation as something that needs proof and a date from day one: it was what hid the gaps the longest.