Feature request: Session-based play

[tickBit]

What do you want to see in the API?

(This plan is based on recent additions to the project, the plan may still change, though)

Add support for teacher-led class sessions integrated with OpeSivu.

A teacher should be able to log in through OpeSivu, create or open a class session, start the session, and share one session password/code with the whole class. Students should use that shared code to join the same isolated game environment.

The API should also support a session-based leaderboard, where results are stored on the server and shown only for that specific class/session.

How do you think this should work?

The existing Box / testing session architecture seems to match this use case well.

Suggested flow:

1. Teacher logs in through OpeSivu.
2. Backend validates the OpeSivu token, which is expected to be valid for 3 months.
3. Teacher creates or opens a class session.
4. Backend creates or uses a Box as the class session container.
5. Teacher configures the session:
   • class/session size
   • clans/teams
   • possible predefined tasks
6. Teacher starts the session.
7. Backend generates or stores a shared session password in Box.testersSharedPassword.
8. Teacher shares this code with students.
9. Students enter the code in the game client.
10. AccountClaimerService finds the matching Box by testersSharedPassword.
11. Backend creates a student profile/player and assigns the student to one of the session clans.
12. Backend returns a JWT containing box_id, player_id, profile_id, and clan_id.
13. All session data is isolated by box_id.

In testing/session mode, BoxAuthGuard and BoxIdFilterInterceptor already provide a good foundation for this: the token identifies the box_id, and API responses can be filtered so users only see data from the same session.

For leaderboards, the API should support a class/session-specific leaderboard. This could either be explicit:

GET /leaderboard/player?box_id={boxId}
GET /leaderboard/clan?box_id={boxId}

Or implicit in session mode:

player_leaderboard:box:{boxId}
clan_leaderboard:box:{boxId}

Redis cache keys must include the session scope, for example:

player_leaderboard:box:{boxId}
clan_leaderboard:box:{boxId}

This avoids mixing leaderboard results between different class sessions.

Any additional info?

Current related implementation areas:

• src/box/box.controller.ts
• src/box/schemas/box.schema.ts
• src/box/sessionStarter/sessionStarter.service.ts
• src/box/accountClaimer/accountClaimer.service.ts
• src/box/auth/boxAuth.guard.ts
• src/box/auth/BoxIdFilter.interceptor.ts
• src/leaderboard/leaderboard.service.ts
• Important existing concepts:
• Box can represent one class/session.
• Box.testersSharedPassword can act as the shared class code.
• box_id is the main isolation key.
• Students should not use the OpeSivu token directly.
• OpeSivu token should be used for teacher/session administration only.
• Student gameplay should continue using the session JWT returned by the backend.