Skip to main content

Web App Setup

This guide walks you through setting up the Progressive Web App (PWA) frontend. Make sure you have completed the Installation steps first.

1. Build the PWA​

cd pwa
npm install
npm run build

The built output goes to pwa/dist/ and is automatically served as static files by the FastAPI server. No separate web server is needed.

tip

During development, you can use npm run dev in the pwa/ directory to run the Vite dev server with hot reload.

2. Configure Web App Variables​

VAPID Keys (for push notifications)​

Generate a VAPID key pair:

npx web-push generate-vapid-keys

Add the output to your .env file:

VAPID_PRIVATE_KEY=<your-private-key>
VAPID_PUBLIC_KEY=<your-public-key>
VAPID_CLAIMS_EMAIL=mailto:researcher@university.edu

These keys enable web push notifications to alert participants when surveys are available.

Access Password​

Set the password participants will enter during registration:

ACCESS_PASSWORD=your-study-password

The default is ssrc. Change this to something specific to your study.

3. Run the Server​

uv run python -m src.main

A single process starts three services:

ServiceRole
FastAPIHTTP API on port 8000 — serves the PWA, WebSocket connections, and REST endpoints
APSchedulerTimed survey delivery based on configured schedules
Telegram botAlso starts if TELEGRAM_BOT_TOKEN is set (both channels can run simultaneously)

Open http://localhost:8000 in your browser — you should see the PWA landing page.

note

In production, set BASE_URL in your .env to your public domain (e.g., https://your-study.example.com). This URL is used for cognitive assessment callbacks and wearable webhooks.

4. Register Your First Participant​

Open the PWA in a browser and follow the onboarding flow:

  1. Password — Enter the study access password.
  2. Study Information — Read the study details presented in sequence.
  3. Consent — Tap I Consent to agree to participate.
  4. Confirm — Tap Confirm to complete registration.

The app generates an authentication token that is stored locally in the browser. Participants use this token to reconnect on subsequent visits.

After registration, depending on your TUTORIAL_MODE setting (opt_in by default), the app may offer a tutorial walkthrough of example surveys.

5. Enable Push Notifications​

After the tutorial (or enrollment if tutorials are disabled), the app prompts participants to enable push notifications. This requires the VAPID keys configured in step 2.

Push notifications alert participants when new surveys are available, even when the browser tab is closed. Participants can manage their notification preferences in the app settings.

Next Steps​