# ritesh3280/hackumbc25 architecture

> Architecture diagram of the GitHub repository ritesh3280/hackumbc25, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ritesh3280/hackumbc25
- Repository: https://github.com/ritesh3280/hackumbc25

## Overview

This is a focus-session timer and analytics app with EEG-based focus monitoring. The main workflow runs from the browser’s timer and session store, through live EEG data and focus classification, back to the interface; saved sessions feed history, calendar, and insight views. The README documents starting a FastAPI backend, and the source index shows it imports EEG inference. Several EEG training and collection modules are present, but their runtime wiring is not established by the excerpts, so they are shown without speculative connections.

Main entry points: [`frontend/src/app/page.js`](https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/page.js) (Focus Dashboard), [`frontend/src/app/history/page.js`](https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/history/page.js) (History Page), [`frontend/src/app/store/sessionStore.js`](https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/store/sessionStore.js) (Session Store), [`eeg/eeg_websocket.py`](https://github.com/ritesh3280/hackumbc25/blob/main/eeg/eeg_websocket.py) (EEG WebSocket)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Focus App"]
  node_dashboard["Focus Dashboard<br/>[page.js]"]
  node_timer["Timer Controls<br/>[Timer.jsx]"]
  node_tasklist["Task List<br/>[TaskList.jsx]"]
  node_focusalarm["Focus Alarm UI<br/>[FocusAlarm.jsx]"]
  node_eeggraphs["EEG Displays<br/>[EEGGraphs.jsx]"]
end

subgraph group_sessions["Session Data"]
  node_sessionstore["Session Store<br/>[sessionStore.js]"]
  node_indexeddb[("Session Database<br/>[indexeddb.js]")]
  node_taskclassifier["Task Classifier<br/>[taskClassifier.js]"]
end

subgraph group_eeg["EEG Monitoring"]
  node_eegclient["EEG Client Hook<br/>[useRealEEG.js]"]
end

subgraph group_backend["EEG Services"]
  node_wsservice["EEG WebSocket<br/>[eeg_websocket.py]"]
  node_api["FastAPI Backend<br/>[backend.py]"]
  node_detector["EEG Mood Detector<br/>[inference.py]"]
  node_rfdetector["Random Forest Detector"]
  node_signal["Signal Processing"]
  node_alarm["Alarm Smoothing<br/>[alarm.py]"]
end

subgraph group_analysis["History &amp; Insights"]
  node_history["History Page<br/>[page.js]"]
  node_analytics["Session Analytics"]
  node_visualization["Session Visualizations"]
  node_calendar["Calendar Views<br/>[CalendarView.jsx]"]
  node_insights["Focus Insights<br/>[geminiInsights.js]"]
end

node_user(("User"))
node_eegdevice(("EEG Device"))
node_browsermodel(("Remote Model Host"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"renders"| node_timer
node_dashboard -->|"renders"| node_tasklist
node_dashboard -->|"renders"| node_focusalarm
node_dashboard -->|"renders"| node_eeggraphs
node_dashboard -->|"uses"| node_sessionstore
node_dashboard -->|"reads live data"| node_eegclient
node_timer -.->|"updates sessions"| node_sessionstore
node_sessionstore -->|"saves sessions"| node_indexeddb
node_sessionstore -->|"classifies tasks"| node_taskclassifier
node_eegclient -->|"opens WebSocket"| node_wsservice
node_eegdevice -.->|"streams EEG"| node_wsservice
node_wsservice -->|"uses detector"| node_rfdetector
node_api -->|"imports inference"| node_detector
node_detector -->|"uses processing"| node_signal
node_rfdetector -->|"uses processing"| node_signal
node_taskclassifier -->|"fetches model"| node_browsermodel
node_history -->|"calculates metrics"| node_analytics
node_history -->|"renders charts"| node_visualization
node_history -->|"renders calendar"| node_calendar
node_history -->|"requests insights"| node_insights
node_calendar -->|"uses analytics"| node_analytics
node_visualization -->|"formats metrics"| node_analytics
node_history -.->|"loads sessions"| node_indexeddb

click node_dashboard "https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/page.js"
click node_timer "https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/components/Timer.jsx"
click node_tasklist "https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/components/TaskList.jsx"
click node_focusalarm "https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/components/FocusAlarm.jsx"
click node_eeggraphs "https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/components/EEGGraphs.jsx"
click node_sessionstore "https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/store/sessionStore.js"
click node_indexeddb "https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/db/indexeddb.js"
click node_taskclassifier "https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/utils/taskClassifier.js"
click node_eegclient "https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/hooks/useRealEEG.js"
click node_wsservice "https://github.com/ritesh3280/hackumbc25/blob/main/eeg/eeg_websocket.py"
click node_api "https://github.com/ritesh3280/hackumbc25/blob/main/backend.py"
click node_detector "https://github.com/ritesh3280/hackumbc25/blob/main/eeg/inference.py"
click node_rfdetector "https://github.com/ritesh3280/hackumbc25/blob/main/eeg/randomforestinference.py"
click node_signal "https://github.com/ritesh3280/hackumbc25/blob/main/eeg/signal_processing.py"
click node_alarm "https://github.com/ritesh3280/hackumbc25/blob/main/alarm.py"
click node_history "https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/history/page.js"
click node_analytics "https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/utils/sessionAnalytics.js"
click node_visualization "https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/components/SessionVisualization.jsx"
click node_calendar "https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/components/CalendarView.jsx"
click node_insights "https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/utils/geminiInsights.js"

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_dashboard,node_timer,node_tasklist,node_focusalarm,node_eeggraphs,node_user toneBlue
class node_sessionstore,node_indexeddb,node_taskclassifier toneAmber
class node_eegclient toneMint
class node_wsservice,node_api,node_detector,node_rfdetector,node_signal,node_alarm toneRose
class node_history,node_analytics,node_visualization,node_calendar,node_insights,node_eegdevice,node_browsermodel toneIndigo
```

## Components

### Focus App

- [Focus Dashboard](https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/page.js): `frontend/src/app/page.js`
- [Timer Controls](https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/components/Timer.jsx): `frontend/src/app/components/Timer.jsx`
- [Task List](https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/components/TaskList.jsx): `frontend/src/app/components/TaskList.jsx`
- [Focus Alarm UI](https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/components/FocusAlarm.jsx): `frontend/src/app/components/FocusAlarm.jsx`
- [EEG Displays](https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/components/EEGGraphs.jsx): `frontend/src/app/components/EEGGraphs.jsx`

### Session Data

- [Session Store](https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/store/sessionStore.js): `frontend/src/app/store/sessionStore.js`
- [Session Database](https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/db/indexeddb.js): `frontend/src/app/db/indexeddb.js`
- [Task Classifier](https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/utils/taskClassifier.js): `frontend/src/app/utils/taskClassifier.js`

### EEG Monitoring

- [EEG Client Hook](https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/hooks/useRealEEG.js): `frontend/src/app/hooks/useRealEEG.js`

### EEG Services

- [EEG WebSocket](https://github.com/ritesh3280/hackumbc25/blob/main/eeg/eeg_websocket.py): `eeg/eeg_websocket.py`
- [FastAPI Backend](https://github.com/ritesh3280/hackumbc25/blob/main/backend.py): `backend.py`
- [EEG Mood Detector](https://github.com/ritesh3280/hackumbc25/blob/main/eeg/inference.py): `eeg/inference.py`
- [Random Forest Detector](https://github.com/ritesh3280/hackumbc25/blob/main/eeg/randomforestinference.py): `eeg/randomforestinference.py`
- [Signal Processing](https://github.com/ritesh3280/hackumbc25/blob/main/eeg/signal_processing.py): `eeg/signal_processing.py`
- [Alarm Smoothing](https://github.com/ritesh3280/hackumbc25/blob/main/alarm.py): `alarm.py`

### History & Insights

- [History Page](https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/history/page.js): `frontend/src/app/history/page.js`
- [Session Analytics](https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/utils/sessionAnalytics.js): `frontend/src/app/utils/sessionAnalytics.js`
- [Session Visualizations](https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/components/SessionVisualization.jsx): `frontend/src/app/components/SessionVisualization.jsx`
- [Calendar Views](https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/components/CalendarView.jsx): `frontend/src/app/components/CalendarView.jsx`
- [Focus Insights](https://github.com/ritesh3280/hackumbc25/blob/main/frontend/src/app/utils/geminiInsights.js): `frontend/src/app/utils/geminiInsights.js`

### Other components

- **User**
- **EEG Device**
- **Remote Model Host**

## Connections

- User → Focus Dashboard: uses (evidence: `frontend/src/app/page.js`)
- Focus Dashboard → Timer Controls: renders (evidence: `frontend/src/app/page.js`)
- Focus Dashboard → Task List: renders (evidence: `frontend/src/app/page.js`)
- Focus Dashboard → Focus Alarm UI: renders (evidence: `frontend/src/app/page.js`)
- Focus Dashboard → EEG Displays: renders (evidence: `frontend/src/app/page.js`)
- Focus Dashboard → Session Store: uses (evidence: `frontend/src/app/page.js`)
- Focus Dashboard → EEG Client Hook: reads live data (evidence: `frontend/src/app/page.js`)
- Timer Controls → Session Store: updates sessions
- Session Store → Session Database: saves sessions (evidence: `frontend/src/app/store/sessionStore.js`)
- Session Store → Task Classifier: classifies tasks (evidence: `frontend/src/app/store/sessionStore.js`)
- EEG Client Hook → EEG WebSocket: opens WebSocket (evidence: `frontend/src/app/hooks/useRealEEG.js`)
- EEG Device → EEG WebSocket: streams EEG
- EEG WebSocket → Random Forest Detector: uses detector (evidence: `eeg/eeg_websocket.py`)
- FastAPI Backend → EEG Mood Detector: imports inference (evidence: `backend.py`)
- EEG Mood Detector → Signal Processing: uses processing (evidence: `eeg/inference.py`)
- Random Forest Detector → Signal Processing: uses processing (evidence: `eeg/randomforestinference.py`)
- Task Classifier → Remote Model Host: fetches model (evidence: `frontend/src/app/utils/taskClassifier.js`)
- History Page → Session Analytics: calculates metrics (evidence: `frontend/src/app/history/page.js`)
- History Page → Session Visualizations: renders charts (evidence: `frontend/src/app/history/page.js`)
- History Page → Calendar Views: renders calendar (evidence: `frontend/src/app/history/page.js`)
- History Page → Focus Insights: requests insights (evidence: `frontend/src/app/history/page.js`)
- Calendar Views → Session Analytics: uses analytics (evidence: `frontend/src/app/components/CalendarView.jsx`)
- Session Visualizations → Session Analytics: formats metrics (evidence: `frontend/src/app/components/SessionVisualization.jsx`)
- History Page → Session Database: loads sessions
