How kanishk1420/eeg-signal-processing works
1. This repository has two runtime subsystems: a React frontend in frontend/ and a Flask backend in backend/. The frontend is the interactive monitoring UI; the backend is the prediction and signal-processing service.
2. The frontend is a single-page application built with React 19 and Tailwind. It renders the EEG dashboard, control widgets, theme toggling, and charts. The components are centered around src/App.js and src/components/EEGForm.js, with a small custom UI layer in src/ui/.
3. The visualization layer uses charting and icon libraries to show raw EEG activity and derived frequency-band views. From an architecture standpoint, the frontend is responsible for presentation, user interaction, and local playback/state, not for model inference.
4. The backend is a Flask API that acts as the boundary between the UI and the ML pipeline. It exposes REST endpoints for predictions and a /healthz health check, and it enables CORS so the app can be used from localhost and GitHub Pages deployments.
5. Signal processing lives on the backend side. The README describes decomposition into Delta, Theta, Alpha, Beta, and Gamma bands, and backend/utils.py is the likely home for preprocessing and feature-engineering helpers used before inference.
6. Model inference is done with pre-trained artifacts bundled in backend/. The runtime model described in the README is a decision tree classifier, with decision_tree_model.joblib as the clearest production artifact. Additional serialized files (eeg_model.joblib, eeg_model.keras, eeg_lstm_model.h5) suggest experimentation or alternative model versions, but they are separate from the UI layer.
7. The key data flow is: EEG samples are produced or simulated in the frontend, batched/windowed, and periodically sent to the backend. The backend preprocesses those samples, extracts features, runs inference, and returns a seizure/normal classification that the frontend turns into status indicators and UI updates.
8. There is a clean boundary between runtime and training assets. The models/ directory contains the dataset, notebook, and scratch files used for model development, while backend/ contains the artifacts and code used at runtime. Training is not part of the deployed request path.
9. Error handling is split across the boundary as well. The frontend surfaces connection and processing failures in the UI, while the backend is expected to validate inputs and fall back to safe responses. That makes the diagram clearer if you show failure states originating from the API layer back to the dashboard.
10. Deployment is frontend-first on the UI side and containerized on the backend side. The backend has a Dockerfile, while the frontend is set up for GitHub Pages deployment. In a diagram, treat the frontend as a static SPA served separately from the Flask service.
11. The most important architecture boxes to draw are: user/browser, React SPA, Flask API, preprocessing/model-inference pipeline, and persisted model/data artifacts. The browser communicates with the API over HTTP; the API reads local serialized models and returns classification results that drive the dashboard state.
Main entry points: App.js React SPA · app.py Flask API · utils.py Preprocess · Epileptic Seizure Recognition reaper.csv EEG Dataset
Components 17
Frontend SPA
React dashboard and local UI state
- React SPA · Single-page EEG dashboard and control surface
frontend/src/App.js - EEG Form · Collects samples, controls playback, and triggers requests
frontend/src/components/EEGForm.js - UI Layer · Small custom presentation primitives used by the dashboard
frontend/src/ui/card.jsx - Theme State · Local theme and interaction state for the SPA
frontend/src/index.js - Charts · Renders raw EEG and band views for monitoring
frontend/src/App.js
Backend API
Flask service and runtime inference
- Flask API · REST boundary between the UI and inference pipeline
backend/app.py - CORS · Allows browser access from local and GitHub Pages deployments
backend/app.py - Health Check · Readiness and liveness probe for the service
backend/app.py - Predict API · Receives EEG windows and returns classification results
backend/app.py - Preprocess · Normalizes and prepares EEG samples before inference
backend/utils.py - Band Features · Derives Delta, Theta, Alpha, Beta, and Gamma features
backend/utils.py - Inference · Loads the active model and produces seizure or normal output
backend/app.py
Model Assets
Serialized models and training artifacts
- Decision Tree · Primary runtime artifact used for classification
backend/decision_tree_model.joblib - Alternative Models · Additional trained model variants kept alongside the main artifact
backend/eeg_model.joblib - EEG Dataset · Source dataset used for offline model development
models/Epileptic Seizure Recognition reaper.csv - Training Notebook · Exploration and experimentation used to build the runtime model
models/epilepsykagel.ipynb
Other components
- Browser · Runs the monitoring session and displays seizure status
Connections 18
- Browser → React SPA: opens UI · User interacts with the dashboard in the browser
- React SPA → EEG Form: uses · Main dashboard delegates control and capture to the EEG form
- React SPA → UI Layer: renders · Shared UI primitives support the visual layout
- React SPA → Theme State: updates · Client-side state drives theme and interaction behavior
- React SPA → Charts: draws · Visualization layer presents raw and derived EEG views
- React SPA → Flask API: POST EEG · Browser sends batched samples to the backend over HTTP
- Flask API → CORS: enables · Cross-origin access is configured at the service boundary
- Flask API → Health Check: exposes · Service readiness and liveness endpoint
- Flask API → Predict API: exposes · Prediction endpoint receives signal windows
- Predict API → Preprocess: calls · Incoming samples are validated and prepared
- Preprocess → Band Features: extracts · Feature engineering produces frequency-band representations
- Band Features → Inference: feeds · Engineered features are passed to the model runtime
- Inference → Decision Tree: loads · Primary production artifact is used for classification
- Inference → Alternative Models: may use · Additional serialized artifacts represent alternative model paths
- Predict API → React SPA: returns result · Classification and errors flow back to the dashboard
- React SPA → Browser: updates status · UI reflects seizure/normal state and failures
- Training Notebook → EEG Dataset: trains on · Offline experimentation uses the EEG dataset
- EEG Dataset → Decision Tree: produces · Training output becomes the runtime decision tree artifact