AI-EEG Study - Business-Case Stimulus Web App

Web-based stimulus presentation for an EEG/eye-tracking study on AI scaffolding intensity in business-case decision tasks. The app is designed to run inside iMotions Web Stimulus on the lab PC; iMotions handles EEG and eye-tracking synchronization.

• Repo conventions and editing constraints: AGENTS.md
• Study background and open design decisions: CONCEPT.md

Current Experiment

The active experiment mode is business_case. Participants choose the stimulus language (de or en) on the start page.

• 4 randomized business mini-case rounds
• Round 3 is always the no-AI baseline slot
• Rounds 1, 2, and 4 receive pre-authored AI support
• AI-supported rounds receive 1, 2, and 3 AI turns exactly once
• Case-to-condition exposure is counterbalanced with persisted assignment counts
• Participant information is collected before the task flow
• Global pre-knowledge test before the rounds
• Per-round Cognitive Load Theory questionnaire after each task
• Global post-knowledge test after the final round CLT questionnaire

Stimulus and questionnaire files:

• German business cases: backend/stimuli/business_cases.json
• English business cases: backend/stimuli/business_cases.en.json
• German CLT questionnaire: backend/stimuli/clt_questionnaire.de.json
• English CLT questionnaire: backend/stimuli/clt_questionnaire.en.json

Stimuli are experimental material. Do not silently edit wording after pilot lock-in; flag content issues for human review instead.

Stack

• Frontend: Next.js 15 App Router, React 19, TypeScript strict
• Backend: FastAPI, Python 3.11+
• Local persistence: file storage under backend/data/
• Deployment persistence: MongoDB, selected automatically when MONGO_URI or MONGODB_URI is configured
• iMotions markers: browser-side HTTP events via NEXT_PUBLIC_IMOTIONS_EVENT_ENDPOINT

Local Setup

Backend:

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload

The backend defaults to http://localhost:8000 and file storage at backend/data/. Check it with:

curl http://localhost:8000/health

Frontend:

cd frontend
npm install
npm run dev

The frontend defaults to http://localhost:3000 and calls the backend at http://localhost:8000.

Configuration

Backend environment variables:

Variable	Default	Purpose
FRONTEND_ORIGIN	http://localhost:3000	CORS allow-list, comma-separated
STORAGE_BACKEND	mongo if Mongo URI exists, else file	Persistence backend
STORAGE_PATH	./data	File storage root relative to backend/
MONGO_URI / MONGODB_URI	unset	MongoDB connection string
MONGO_DB_NAME / MONGODB_DATABASE	ai_eeg	MongoDB database
MONGO_EVENT_COLLECTION / MONGODB_COLLECTION	events	MongoDB event collection
STIMULUS_LANG	de	Backend default language if omitted
BUSINESS_BASELINE_ROUND_INDEX	2	Fixed zero-based baseline slot; must remain round 3

Frontend environment variables:

Variable	Default	Purpose
NEXT_PUBLIC_API_URL	http://localhost:8000	Backend API base URL
NEXT_PUBLIC_IMOTIONS_EVENT_ENDPOINT	unset	iMotions HTTP marker endpoint

Example local frontend config:

cd frontend
printf 'NEXT_PUBLIC_API_URL=http://localhost:8000\n' > .env.local

On the lab PC, add the iMotions event endpoint to .env.local as provided by the Web Stimulus setup.

Flow

Start
  -> Participant information
  -> Pre-knowledge test
  -> Round 1, AI-supported
  -> Round 2, AI-supported
  -> Round 3, no-AI baseline
  -> Round 4, AI-supported
  -> Post-knowledge test
  -> Debrief

Per AI-supported round:

Scenario reading, fixed 50 s
  -> decision question, fixed 5 s
  -> initial no-input thinking, fixed 20 s
  -> initial answer selection
  -> AI support turn 1
  -> answer revision
  -> AI support turn 2, if assigned
  -> answer revision
  -> AI support turn 3, if assigned
  -> answer revision
  -> final short rationale
  -> Cognitive Load Theory questionnaire

Per baseline round:

Scenario reading, fixed 50 s
  -> decision question, fixed 5 s
  -> initial no-input thinking, fixed 20 s
  -> answer selection
  -> final short rationale
  -> Cognitive Load Theory questionnaire

Event Logging

Events are emitted from the participant's browser. The primary path is the configured iMotions endpoint, and the secondary path is the backend /events log. Event delivery is fire-and-forget so network latency does not block trial progress or shift stimulus timing.

For local file storage, generated data is written under:

• backend/data/sessions/
• backend/data/participant_info/
• backend/data/knowledge_tests/
• backend/data/responses/
• backend/data/events/
• backend/data/meta/counterbalance.json

Checks

Backend smoke check:

cd backend
python -m compileall .

Frontend checks:

cd frontend
npm run typecheck
npm run build