Learner contributions
Students can propose a new item for your course: a quiz, a "spot the flaw" or an "explain back" scene. You see each proposal with its answer key, approve, reject or ask for a revision, and only what you approve becomes available to the class, as a separate community lesson. Your original course is never modified. Learners can never publish on their own: that is rule 003 applied to contributions.
| Step | Who | Where | Result |
|---|---|---|---|
| Draft and self-test | Learner | /studio in the author web app (localhost:3000) |
A scene that passes validation |
| Submit | Learner | Same page, after consent | An item in state submitted |
| Peer test (optional) | Learners | /peer in the author web app |
Rating aggregates, shown from 3 raters |
| Sign in | You | /login in the dashboard (localhost:3001) |
A teacher session for 12 hours |
| Decide | You | /courses/<course_id>/submissions in the dashboard (localhost:3001) |
Approved, rejected or revision requested |
| Play | Class | Assistant (list_community_bundles) or VS Code ("Studium: Community contributions") |
A single-scene community lesson |
Start the services
Decisions need a teacher review token: a secret of at least 32 characters, set to the same value
in STUDIUM_REVIEW_TOKEN for scene-synth and for the dashboard's server, and never given to a
learner. Generate one per deployment, for example in a shell you then use for both commands:
export STUDIUM_REVIEW_TOKEN="$(openssl rand -hex 32)"
The dashboard also needs an access code, which you type to sign in: at least 16 characters in
STUDIUM_DASHBOARD_ACCESS_CODE, on the dashboard's server only. Without it the dashboard refuses
every decision (503).
export STUDIUM_DASHBOARD_ACCESS_CODE="$(openssl rand -hex 16)"
Three terminals, from the repository root (the first and the third need the token):
.venv/bin/python -m uvicorn scene_synth_app:app --app-dir services/scene-synth --port 8002
pnpm --filter @studium/author-web dev
pnpm --filter @studium/teacher-dashboard dev
Without the token, scene-synth refuses every decision (approve, reject, request revision) with
503 and says which variable to set; learners can still draft and submit.
The service reads each course from BUNDLES_ROOT/<course_id>/lesson.json (default: the
repository's fixtures/) and keeps submissions in LEARNER_DATA_ROOT (default
/tmp/studium-learner-items). The web apps reach it on port 8002 (NEXT_PUBLIC_SCENE_SYNTH_SERVICE_URL
for the learner app, SCENE_SYNTH_BASE_URL for the dashboard). No API key is needed.
The learner form lives in the author web app, which is marked legacy, and is wired to the demo
course atomistique-l1 (concept c-orbitales-formes). For another course, a client submits through
the same service (POST /learner-items) with that course's id.
What the learner does
- Fills a guided form (no JSON): title, question, two to six choices with exactly one correct, feedback for right and wrong answers, hints. "Spot the flaw" and "explain back" have their own editors.
- Watches the validation badge: every edit is checked against the schema and the course's concepts.
- Answers their own item in the self-test panel, with a local grader and no network call.
- Ticks consent; with a green badge, Submit sends the item, which arrives as
submitted.
Decide on a submission
Sign in first. Open http://localhost:3001/courses/atomistique-l1/submissions (the course id is the
token): the dashboard sends you to its sign-in page, you type the access code, and it brings you back
to the queue. The session lasts 12 hours; Sign out in the header ends it. If it expires while the
page is open, a decision answers that you must sign in again. The session does not record who you are:
the name learners read is the one you type below. Each
item shows the scene, its answer key (correct answers marked), the validation result and a
de-identified author label, so you never approve blind.
Above the queue, type Your name, as learners will read it. Approve stays disabled until the field
holds a name, and the page shows the sentence learners will read: "Lesson contributed by a classmate,
validated by
| Decision | Effect |
|---|---|
| Approve | A single-scene community lesson community-<id>.zip is written under BUNDLES_ROOT/<course_id>/community/, with your name in validated_by, an approval.json record next to its lesson.json, and the author pseudonym removed |
| Reject | Nothing is published |
| Request revision | Nothing is published; the decision is recorded on the item |
How a decision is recorded
A decision is a teacher act, and the service checks it as one:
- Your browser posts the decision to the dashboard's own server, which calls scene-synth with
Authorization: Bearer $STUDIUM_REVIEW_TOKEN. The token stays on the two servers: it never reaches a browser, a response, a log or a file. A missing or wrong token gets401. - scene-synth refuses any decision coming straight from a browser (
403) and grants no CORS access to the decision route, so the learner app onlocalhost:3000cannot decide, even for its own items. - On approval the reviewer is the name you typed, trimmed: the dashboard refuses an empty name, one
longer than 200 characters, one with a control character, or an identifier starting with
urn:, and scene-synth refuses an empty or overlong name, an identifier starting withurn:, and the item author's own handle or pseudonym (400). A rejection or a revision request, which publishes nothing, records your name when you typed one and the course identifierurn:studium:teacher:<course_id>otherwise. - On approval the archive holds
approval.json, the samestudium-approval/1record thatexperience_packet.py approvewrites for a teacher lesson:bundle_sha256(the sha256 of the exactlesson.jsonbytes in the archive),reviewer,reviewed_at,tool, anddecision_route: "learner-contribution". Any change tolesson.jsonbreaks the match. - The lesson says who wrote it:
metadata.authoringis{mode: "teacher", author_is_learner: true, drafted_by: "learner"}, a learner's draft validated by you. - Every decision adds one line to
learner_decisions.jsonlinLEARNER_DATA_ROOT: item, course, decision, reviewer, the declaredreviewed_at, the server'srecorded_atand, on approval, the sha256 of the publishedlesson.jsonand of the archive.
Learners and their assistants find approved items with the list_community_bundles MCP tool, whose
references pass unchanged to start_lesson_session, or with the VS Code command "Studium: Community
contributions".
Peer rating in class
Two optional ways to let students test each other's work:
- The
/peerpage of the author web app lets learners take a submitted item and rate it. The ratings carry no text and no identity; you see the aggregate only once three learners have rated. - A live PeerStudio room: your assistant calls
open_peer_roomfor a lesson and gives students a six-character join code; they calljoin_peer_roomandsubmit_peer_rating. You readget_peer_room_stateand end withclose_peer_room, which returns the aggregates of targets with at least three independent ratings. The room lives in memory and disappears when closed. The dashboard page/roomoffers the same controls through the lesson server (LESSON_SERVER_BASE_URL, defaulthttp://localhost:8010).
Ratings inform your decision; they never publish anything by themselves.
Privacy
- The learner's text stays on their device until they submit; it never enters telemetry.
- The author pseudonym is computed on the server and never returned to any client or shown to peers.
- Self-test makes no network or model call.
Not the same as a self-study lesson
A lesson a learner builds for themself with their assistant (see
learn with your assistant) stays in their own library,
marked self-study. experience_packet.py approve refuses self-study lessons; to give that material
to a class, rebuild it through the teacher route.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| CORS error in the browser console | The service is not running, or the learner page is not on localhost:3000; the dashboard never calls scene-synth from the browser |
"Les décisions sont désactivées" in the dashboard, or 503 on a decision |
STUDIUM_REVIEW_TOKEN (at least 32 characters) is missing on scene-synth or on the dashboard's server: set the same value on both and restart them |
| "Decisions unavailable" above the queue | The dashboard's server lacks STUDIUM_DASHBOARD_ACCESS_CODE (at least 16 characters) or STUDIUM_REVIEW_TOKEN; the line names the one to set |
401 on a decision, with "connectez-vous" |
Your dashboard session is missing or expired: sign in again |
401 on a decision, from scene-synth |
The two servers hold different STUDIUM_REVIEW_TOKEN values |
400 "the reviewer cannot be the item's author" |
The reviewer named is the learner who wrote the item; a learner never decides on their own item |
400 or 404 on submit |
The course id is malformed, or BUNDLES_ROOT/<course_id>/lesson.json does not exist |
422 on submit |
The scene failed validation; the response lists the errors |
| Empty queue | No item is in state submitted; do the learner step first |
Connection refused on port 8002 |
Start the scene-synth service |
Code: services/scene-synth/scene_synth_app.py,
services/scene-synth/learner_review.py,
apps/teacher-dashboard/lib/decide-route.ts,
apps/author-web/app/studio/.