LabSim

LabSim is a browser-based science investigation workspace. Students can choose a trusted interactive simulation or describe their own question, adjust variables, record trials, and complete a guided evidence worksheet.

---

What is included

• 31 interactive labs across physics, chemistry, biology, Earth and environmental science, and engineering and materials
• Dedicated simulations for Newton's first, second, and third laws
• Grade-band selection for elementary, middle-school, and high-school investigations
• Built-in, validated simulation templates plus constrained exploratory models for custom questions
• Trial recording and claim-evidence-reasoning worksheets
• Browser-session previews for signed-out users
• Google sign-in with persisted labs, trials, and worksheet responses for signed-in users

Run locally

Requirements: Node.js, pnpm, and PostgreSQL.

pnpm install
cp .env.example .env
pnpm db:generate
pnpm db:migrate
pnpm dev

Open http://localhost:3000. The health endpoint is available at http://localhost:3000/api/health.

Configuration

Set these required values in .env:

• DATABASE_URL — PostgreSQL connection string
• JWT_SECRET — long, random secret used to sign session tokens
• GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET — Google OAuth web-client credentials
• GOOGLE_CALLBACK_URL — use http://localhost:3000/api/auth/google/callback locally

In Google Cloud Console, add the same callback URL as an authorized redirect URI. The frontend starts sign-in at /api/auth/google; authentication uses a signed, HTTP-only cookie.

Optional AI provider

AI_PROVIDER_URL must be the provider adapter's exact POST endpoint, not a base URL. The endpoint receives the labsim-json-v1 contract. Configure it with AI_PROVIDER_API_KEY and, when required, AI_PROVIDER_MODEL.

If the provider is not configured—or returns a network, HTTP, or validation error—LabSim automatically uses its built-in validated templates and records the fallback in the lab's generation trace. Model output is treated as structured data; LabSim does not execute model-generated code.

Useful commands

pnpm dev          # start the development server
pnpm build        # create a production build
pnpm start        # run the production build
pnpm lint         # run TypeScript checks
pnpm db:generate  # regenerate the Prisma client
pnpm db:migrate   # apply development database migrations

Screenshots

Home	Adjust variables
Record a trial	Evidence worksheet

See the system design for the architecture and safety model.