An easy-to-use platform for EEG experimentation in the classroom
add claude context
authored by
Dano Morrison
and committed by
Teon L Brooks
9e5392ac
da96bd3d
+73
+5
.claude/settings.json
+5
.claude/settings.json
+56
.llms/CLAUDE.md
+56
.llms/CLAUDE.md
···
1
+
# BrainWaves — Claude Code Rules
2
+
3
+
## Project Overview
4
+
BrainWaves is an Electron + React desktop application for running EEG experiments. It uses electron-vite for bundling, Redux + redux-observable for state management, and Pyodide (WASM) for in-app Python data analysis. Its primary usecase is making EEG data collection and analysis easy for students
5
+
6
+
## Background
7
+
This app is fairly complex in that it involves communicating with external EEG devices over bluetooth, with high precision and speed goals, and doing scientific computing within a frontier python-in-the-browser environment.
8
+
Reliability and visibility of these different sources of complexity is thus most important for developers.
9
+
The UI of the app should have a lighthearted and fun feel, since its target audience is students.
10
+
Redux Observables are hard to learn, but powerful. They help encapsulate complex temporally sensitive logic into functions. They should be maintained as an approach going forward, at least until a refactor is made.
11
+
A priority for this codebase is extensibility modularity and hackability. There are many features on the horizon such as swapping out hard-coded analysis for block-based programming, or even an embedd notebook environment. As such, effort should be taken not to hard-code things or cut corners by leaking abstractions.
12
+
13
+
## Stack
14
+
- **Runtime**: Electron (main) + React 18 (renderer)
15
+
- **Bundler**: electron-vite / Vite
16
+
- **State**: Redux Toolkit + redux-observable (RxJS epics)
17
+
- **Language**: TypeScript (strict)
18
+
- **Styling**: Semantic UI React + SCSS
19
+
- **Testing**: Jest
20
+
- **Linting**: ESLint + Prettier (single quotes, ES5 trailing commas)
21
+
22
+
## Key Directories
23
+
- `src/main/` — Electron main process
24
+
- `src/renderer/` — React renderer process
25
+
- `src/preload/` — Electron preload scripts
26
+
- `src/renderer/experiments/` — Lab.js experiment files
27
+
- `src/renderer/utils/pyodide/` — Pyodide WASM Python runtime
28
+
29
+
## Dev Workflow
30
+
```bash
31
+
npm run dev # Start dev server (patches deps first)
32
+
npm run build # Build all processes
33
+
npm test # Run Jest tests
34
+
npm run typecheck # TypeScript check (no emit)
35
+
npm run lint # ESLint
36
+
npm run lint-fix # ESLint + Prettier auto-fix
37
+
npm run package # Build + package for current platform
38
+
```
39
+
40
+
## Conventions
41
+
- Use TypeScript; avoid `any` unless strictly necessary
42
+
- Redux state changes go through RTK slices or typed actions via `typesafe-actions`
43
+
- Side effects belong in RxJS epics (`redux-observable`)
44
+
- Do not commit secrets or device credentials
45
+
- Keep Electron main/renderer separation strict — use preload IPC bridges
46
+
47
+
## Out of Scope
48
+
- Do not modify `src/renderer/utils/pyodide/src/` directly; it is managed by `InstallPyodide.js`
49
+
- Do not alter `electron-builder` publish config without confirming release intent
50
+
51
+
## LLM Context
52
+
Shared context for agents and developers lives in `.llms/`:
53
+
- `.llms/CLAUDE.md` — this file; stable conventions and architecture
54
+
- `.llms/learnings.md` — accumulated codebase insights from agents and developers
55
+
56
+
When you discover something non-obvious about the codebase (a gotcha, a hidden dependency, a tricky pattern), add it to `.llms/learnings.md` so future agents and developers benefit.
+10
.llms/learnings.md
+10
.llms/learnings.md
···
1
+
# BrainWaves — Codebase Learnings
2
+
3
+
Accumulated insights from agents and developers working on this codebase.
4
+
Add entries here when you discover something non-obvious — gotchas, hidden dependencies, tricky patterns, debugging tips.
5
+
6
+
Format: brief heading + explanation + (optional) relevant file paths.
7
+
8
+
---
9
+
10
+
<!-- Add entries below this line -->