CampusCup Schema

Shared Convex backend contract for the CampusCup Judge IT system. Keeping the schema and server functions in one repository lets each consumer use the same data model without duplicating backend code.

Consumers

• judge-it mounts this repository as its convex/ submodule and provides the authenticated judging interface.
• judge-it-stats mounts it as its schema/ submodule and reads competition data through the protected statistics endpoint.

Each consumer pins an exact schema commit. Schema changes are therefore not active in a consumer until its submodule reference is updated.

Repository layout

File	Responsibility
schema.ts	Convex tables, fields, and indexes
queries.ts	Authenticated application queries and internal statistics export
mutations.ts	Authenticated competition mutations
statsApi.ts	Bearer-protected statistics HTTP handler
http.ts	Convex Auth and /stats HTTP routes
auth.ts, auth.config.ts	Convex Auth configuration
authHelpers.ts	Authentication and user-approval checks
admin.ts	Administrative user operations

Files in _generated/ are generated by Convex.

Security boundary

Application queries and mutations require an authenticated, approved Judge IT user. Administrative operations enforce their own authorization requirements.

The statistics consumer does not call application queries directly. It requests GET /stats with Authorization: Bearer <STATS_API_KEY>. The HTTP action validates the bearer secret before invoking the internal statistics query.

Never commit deployment credentials, auth secrets, or STATS_API_KEY.

Heat-start invariant

mutations.startHeat starts a heat as one Convex transaction. It:

1. verifies the caller is approved;
2. validates both teams and players by document ID;
3. verifies that each player belongs to the selected team;
4. resolves the Sail time type;
5. unsets the previous current heat;
6. creates the new current heat; and
7. creates one initial Sail log for each selected team using the same server timestamp.

A failed mutation writes nothing. Team and player names are not identity keys, so separate records may share a name. Partial team rosters are supported.

Local development

This repository is normally developed through a consumer checkout so Convex can generate types and run alongside the application.

git clone --recurse-submodules https://github.com/itu-campuscup/judge-it.git
cd judge-it
bun install --backend copyfile
bun dev

Run the schema regression tests from the Judge IT root:

bun test convex/queries.test.ts convex/mutations.test.ts

Run a production application build before updating the consumer reference:

bun next build

Updating consumers

Schema and consumer changes must be coordinated in this order:

1. merge the schema change;
2. deploy that schema revision to the target Convex deployment;
3. update and merge each consumer's submodule reference; and
4. deploy the consumer application.

Deploying a consumer before its required Convex functions are available can cause runtime mutation or query failures. Deploying an additive schema change first is safe because existing functions remain available to the old consumer.

Contributing

Open a pull request against main. Use Conventional Commits, for example:

feat(mutations): start heats atomically
fix(queries): require approved users

When behavior changes, update the relevant tests and every affected consumer in the same rollout.

License

Licensed under the MIT License.