Building JoBoEco, Part 4: the eligibility engine

The problem of “who can submit what”

It sounds simple: enrolled participants can submit papers. But then you start unpacking the real rules and realize it’s considerably more complex.

In JoBoEco, the eligibility rules for submission include:

1. Are submissions currently open? (global flag configurable by the admin)
2. Is the participant enrolled in the event? (basic check)
3. Is the participant’s registration paid? (or exempt from payment for some reason)
4. Does the participant’s category allow submission in this area?
5. If the category requires an enrollment proof, has it been submitted and approved?
6. Does the participant still have free submission quota available in their category?
7. If the free quota is exhausted, is there a submission fee for this area — and has it been paid?
8. Has the event’s global submission limit not yet been reached?

Eight verification dimensions. Each can be configured independently by the admin. And any change to the configuration needs to be reflected immediately, without a redeploy.

In the first version of the system, this code was scattered across the submission API handler — a series of nested ifs that mixed validation, database access, and HTTP responses. It worked, but was impossible to test and hard to modify without breaking some other rule.

The refactor to a pure service

The decision was to extract all eligibility logic into a separate module, src/lib/eligibility.ts, that:

1. Does not call the database directly — receives everything it needs as parameters
2. Has no side effects — doesn’t update anything, only evaluates
3. Returns a structured type — not an error string, but an object with full context
4. Is testable in isolation — you can write unit tests without database mocks

The contract ended up like this:

1
export type EligibilityStatus =
2
  | 'ELIGIBLE'
3
  | 'NOT_ENROLLED'
4
  | 'ENROLLMENT_PROOF_PENDING'
5
  | 'ENROLLMENT_PROOF_REJECTED'
6
  | 'FREE_QUOTA_EXHAUSTED_NO_PAID_OPTION'
7
  | 'NEEDS_SUBMISSION_PAYMENT'
8
  | 'SUBMISSIONS_CLOSED'
9
  | 'GLOBAL_LIMIT_REACHED'
10
  | 'CATEGORY_NOT_ALLOWED'
11

12
export interface EligibilityContext {
13
  status: EligibilityStatus
14
  eligible: boolean
15
  // additional context for the frontend to render the right message
16
  freeSubmissionsUsed?: number
17
  freeSubmissionsTotal?: number
18
  submissionFee?: number
19
  pendingPaymentId?: string
20
}
21

22
export function checkSubmissionEligibility(
23
  input: EligibilityInput,
24
): EligibilityContext {
25
  // all the logic here, no side effects
26
}

The eligible: boolean return is the quick answer for the frontend to decide whether to show the submission button. The status enum allows rendering a specific message for each case. The optional fields provide context for cases that need specific UX (like showing how many submissions are still available).

Why return context instead of throwing an exception

The first version threw an EligibilityError with a message. The problem: the message was a string, and the frontend needed to parse the text to decide how to display the error.

That’s a violation of the principle that contracts between layers should be typed, not based on magic strings. With the EligibilityStatus type, the frontend can do:

1
switch (eligibility.status) {
2
  case "ENROLLMENT_PROOF_PENDING":
3
    return <ProofPendingBanner />;
4
  case "NEEDS_SUBMISSION_PAYMENT":
5
    return <SubmissionPaymentFlow fee={eligibility.submissionFee} />;
6
  case "FREE_QUOTA_EXHAUSTED_NO_PAID_OPTION":
7
    return <QuotaExhaustedMessage used={eligibility.freeSubmissionsUsed} />;
8
  // ...
9
}

Each state produces a different component, with typed props. Zero string parsing.

Peer review: three modes, one table

JoBoEco supports three review modes:

• OPEN: the reviewer sees the author’s name, the author sees the reviewer’s name
• SINGLE_BLIND: the reviewer sees the author’s name, the author does not see who is reviewing
• DOUBLE_BLIND: neither the reviewer sees the author, nor the author sees the reviewer

This configuration lives in siteSettings.reviewMode and is enforced at the API layer — not the frontend. This is important: never trust the client to censor sensitive data.

1
const reviewMode = await getSiteConfig('reviewMode')
2

3
// If double blind, remove author data before returning to the reviewer
4
if (reviewMode === 'DOUBLE_BLIND' && userIsReviewer) {
5
  submission.authorName = null
6
  submission.authorEmail = null
7
  submission.authorInstitution = null
8
}

Reviewer assignment to submissions is done by knowledge area — each reviewer is associated with one or more areas, and the admin assigns submissions within those areas. This prevents assigning an Ecology specialist to review a work on Systematic Botany.

The assignment data model ended up like this:

1
reviewerAreaAssignments {
2
  reviewerId,   -- user with REVIEWER role
3
  areaId,       -- knowledge area
4
  eventId       -- specific per event
5
}
6

7
submissionReviews {
8
  submissionId,
9
  reviewerId,
10
  score,           -- numeric
11
  recommendation,  -- APPROVED | REJECTED | REVISION
12
  comments,        -- feedback for the author
13
  createdAt
14
}

A decision I made consciously: not implementing auto-assignment of reviewers. The matching algorithm is tempting to automate (balance workload per reviewer, check for conflicts of interest, ensure at least N reviews per submission), but for JoBoEco’s volume, the complexity doesn’t justify the benefit. The admin makes assignments manually through the panel and has full control over the process. Simple wins.

The admin panel as the central axis

One of the best architectural decisions was making the admin panel the place where all behavior configuration is managed at runtime.

Things the admin can change without a redeploy:

• Open/close submissions (submissionsOpen)
• Open/close proceedings publication (proceedingsActive)
• Review mode (open / single-blind / double-blind)
• Global submission limit per event
• Free submission quotas per category
• Submission fee per area
• Certificate signatories (name and title)
• Call for papers content

This is implemented as siteSettings in the D1 database, with key-value pairs:

1
// Reading
2
const value = await getSiteConfig('reviewMode')
3

4
// Admin update
5
await setSiteConfig('reviewMode', 'DOUBLE_BLIND')

The practical benefit: during the event, the organization can change the review mode, close submissions, or update certificate signatories without needing to call me for a deploy. For a system used in formal academic contexts, that autonomy matters.

The anti-pattern I avoided

There’s a common anti-pattern in systems like this: putting business logic in React components or in API routes in a distributed way.

The result is that the same check — “can the user submit?” — gets duplicated across N places: the component that shows the button, the API that processes the submission, the listing component that shows the status. Any rule change needs to be propagated to all those places manually.

The solution is old and has nothing new about it: a pure domain function that knows everything about eligibility, called once. The component displays the result. The API validates again (you never trust just the client). The logic lives in one place.

1
Handler → checkSubmissionEligibility(input) → EligibilityContext → render UI
2
API     → checkSubmissionEligibility(input) → EligibilityContext → accept or reject

It sounds obvious on paper. It’s hard to maintain when you’re in a hurry.

Testing the eligibility engine

This was the module with the most unit tests in the project. Not out of dogma, but because the complexity justifies it: when you have 8 verification dimensions and any combination could be a real user’s situation, you need coverage to maintain confidence in changes.

The test pattern ended up like this:

1
describe('checkSubmissionEligibility', () => {
2
  it('returns ELIGIBLE when all conditions are met', () => {
3
    const result = checkSubmissionEligibility({
4
      submissionsOpen: true,
5
      isEnrolled: true,
6
      enrollmentPaid: true,
7
      categoryAllowsSubmission: true,
8
      enrollmentProofRequired: false,
9
      freeQuotaUsed: 0,
10
      freeQuotaTotal: 2,
11
      globalLimitReached: false,
12
    })
13

14
    expect(result.eligible).toBe(true)
15
    expect(result.status).toBe('ELIGIBLE')
16
  })
17

18
  it('returns ENROLLMENT_PROOF_PENDING when a pending proof blocks submission', () => {
19
    const result = checkSubmissionEligibility({
20
      // ...
21
      enrollmentProofRequired: true,
22
      enrollmentProofStatus: 'PENDING',
23
    })
24

25
    expect(result.eligible).toBe(false)
26
    expect(result.status).toBe('ENROLLMENT_PROOF_PENDING')
27
  })
28

29
  // ... one test per blockable path
30
})

Each blocking state has its own test. Any refactor of the rules breaks the tests before breaking production.

In the next — and last — part of the series, I talk about the two systems I’m most proud of in the project: certificates with offline verification via HMAC, and proceedings publication with full-text search and BibTeX export. Plus QR Code check-in and the lessons from the first real event.