# kanishk1420/eeg-signal-processing architecture

> Architecture diagram of the GitHub repository kanishk1420/eeg-signal-processing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kanishk1420/eeg-signal-processing
- Repository: https://github.com/kanishk1420/eeg-signal-processing

## Overview

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: [`frontend/src/App.js`](https://github.com/kanishk1420/eeg-signal-processing/blob/main/frontend/src/App.js) (React SPA), [`backend/app.py`](https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/app.py) (Flask API), [`backend/utils.py`](https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/utils.py) (Preprocess), [`models/Epileptic Seizure Recognition reaper.csv`](https://github.com/kanishk1420/eeg-signal-processing/blob/HEAD/models/Epileptic%20Seizure%20Recognition%20reaper.csv) (EEG Dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_frontend["Frontend SPA"]
  node_spa["React SPA<br/>react app<br/>[App.js]"]
  node_eeg_form["EEG Form<br/>ui component<br/>[EEGForm.js]"]
  node_ui_kit["UI Layer<br/>shared components<br/>[card.jsx]"]
  node_theme_state(("Theme State<br/>client state<br/>[index.js]"))
  node_charts["Charts<br/>visualization layer<br/>[App.js]"]
end

subgraph group_group_backend["Backend API"]
  node_api_boundary["Flask API<br/>http service<br/>[app.py]"]
  node_cors(("CORS<br/>cross-origin setup<br/>[app.py]"))
  node_health(("Health Check<br/>endpoint<br/>[app.py]"))
  node_predict_api(("Predict API<br/>endpoint<br/>[app.py]"))
  node_preprocess["Preprocess<br/>signal pipeline<br/>[utils.py]"]
  node_bands["Band Features<br/>feature extraction<br/>[utils.py]"]
  node_inference["Inference<br/>model runtime<br/>[app.py]"]
end

subgraph group_group_models["Model Assets"]
  node_dt_model[("Decision Tree<br/>production model")]
  node_alt_models[("Alternative Models<br/>serialized artifacts<br/>[eeg_model.joblib]")]
  node_dataset[("EEG Dataset<br/>training data")]
  node_notebook["Training Notebook<br/>model development"]
end

node_browser(("Browser<br/>user client"))

node_browser -->|"opens UI"| node_spa
node_spa -->|"uses"| node_eeg_form
node_spa -->|"renders"| node_ui_kit
node_spa -->|"updates"| node_theme_state
node_spa -->|"draws"| node_charts
node_spa -->|"POST EEG"| node_api_boundary
node_api_boundary -->|"enables"| node_cors
node_api_boundary -->|"exposes"| node_health
node_api_boundary -->|"exposes"| node_predict_api
node_predict_api -->|"calls"| node_preprocess
node_preprocess -->|"extracts"| node_bands
node_bands -->|"feeds"| node_inference
node_inference -->|"loads"| node_dt_model
node_inference -.->|"may use"| node_alt_models
node_predict_api -->|"returns result"| node_spa
node_spa -->|"updates status"| node_browser
node_notebook -.->|"trains on"| node_dataset
node_dataset -.->|"produces"| node_dt_model

click node_spa "https://github.com/kanishk1420/eeg-signal-processing/blob/main/frontend/src/App.js"
click node_eeg_form "https://github.com/kanishk1420/eeg-signal-processing/blob/main/frontend/src/components/EEGForm.js"
click node_ui_kit "https://github.com/kanishk1420/eeg-signal-processing/blob/main/frontend/src/ui/card.jsx"
click node_theme_state "https://github.com/kanishk1420/eeg-signal-processing/blob/main/frontend/src/index.js"
click node_charts "https://github.com/kanishk1420/eeg-signal-processing/blob/main/frontend/src/App.js"
click node_api_boundary "https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/app.py"
click node_cors "https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/app.py"
click node_health "https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/app.py"
click node_predict_api "https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/app.py"
click node_preprocess "https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/utils.py"
click node_bands "https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/utils.py"
click node_inference "https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/app.py"
click node_dt_model "https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/decision_tree_model.joblib"
click node_alt_models "https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/eeg_model.joblib"
click node_dataset "https://github.com/kanishk1420/eeg-signal-processing/blob/main/models/Epileptic Seizure Recognition reaper.csv"
click node_notebook "https://github.com/kanishk1420/eeg-signal-processing/blob/main/models/epilepsykagel.ipynb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spa,node_eeg_form,node_ui_kit,node_theme_state,node_charts toneBlue
class node_api_boundary,node_cors,node_health,node_predict_api,node_preprocess,node_bands,node_inference toneAmber
class node_dt_model,node_alt_models,node_dataset,node_notebook toneMint
class node_browser toneNeutral
```

## Components

### Frontend SPA

React dashboard and local UI state

- [React SPA](https://github.com/kanishk1420/eeg-signal-processing/blob/main/frontend/src/App.js): react app · Single-page EEG dashboard and control surface · `frontend/src/App.js`
- [EEG Form](https://github.com/kanishk1420/eeg-signal-processing/blob/main/frontend/src/components/EEGForm.js): ui component · Collects samples, controls playback, and triggers requests · `frontend/src/components/EEGForm.js`
- [UI Layer](https://github.com/kanishk1420/eeg-signal-processing/blob/main/frontend/src/ui/card.jsx): shared components · Small custom presentation primitives used by the dashboard · `frontend/src/ui/card.jsx`
- [Theme State](https://github.com/kanishk1420/eeg-signal-processing/blob/main/frontend/src/index.js): client state · Local theme and interaction state for the SPA · `frontend/src/index.js`
- [Charts](https://github.com/kanishk1420/eeg-signal-processing/blob/main/frontend/src/App.js): visualization layer · Renders raw EEG and band views for monitoring · `frontend/src/App.js`

### Backend API

Flask service and runtime inference

- [Flask API](https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/app.py): http service · REST boundary between the UI and inference pipeline · `backend/app.py`
- [CORS](https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/app.py): cross-origin setup · Allows browser access from local and GitHub Pages deployments · `backend/app.py`
- [Health Check](https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/app.py): endpoint · Readiness and liveness probe for the service · `backend/app.py`
- [Predict API](https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/app.py): endpoint · Receives EEG windows and returns classification results · `backend/app.py`
- [Preprocess](https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/utils.py): signal pipeline · Normalizes and prepares EEG samples before inference · `backend/utils.py`
- [Band Features](https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/utils.py): feature extraction · Derives Delta, Theta, Alpha, Beta, and Gamma features · `backend/utils.py`
- [Inference](https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/app.py): model runtime · Loads the active model and produces seizure or normal output · `backend/app.py`

### Model Assets

Serialized models and training artifacts

- [Decision Tree](https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/decision_tree_model.joblib): production model · Primary runtime artifact used for classification · `backend/decision_tree_model.joblib`
- [Alternative Models](https://github.com/kanishk1420/eeg-signal-processing/blob/main/backend/eeg_model.joblib): serialized artifacts · Additional trained model variants kept alongside the main artifact · `backend/eeg_model.joblib`
- [EEG Dataset](https://github.com/kanishk1420/eeg-signal-processing/blob/HEAD/models/Epileptic%20Seizure%20Recognition%20reaper.csv): training data · Source dataset used for offline model development · `models/Epileptic Seizure Recognition reaper.csv`
- [Training Notebook](https://github.com/kanishk1420/eeg-signal-processing/blob/main/models/epilepsykagel.ipynb): model development · Exploration and experimentation used to build the runtime model · `models/epilepsykagel.ipynb`

### Other components

- **Browser**: user client · Runs the monitoring session and displays seizure status

## Connections

- 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
