# bibek198/biobridge-gateway architecture

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

- Interactive diagram: https://gitdiagram.com/bibek198/biobridge-gateway
- Repository: https://github.com/bibek198/biobridge-gateway

## Overview

BioBridge is a browser-based sensor gateway paired with ESP32 firmware and shared C signal-processing code. Its main workflow takes sensor byte streams through transport and descriptor decoding, aligns device clocks, computes derived measurements and alerts, then presents and records the results. Other major capabilities include configurable processing placement, recording replay, clock-sync evaluation, and AI-proposed descriptors checked against captured data. Some subsystem links below rely on the README because their implementation was not sampled.

Main entry points: [`app/src/session/sessionManager.ts`](https://github.com/bibek198/biobridge-gateway/blob/main/app/src/session/sessionManager.ts) (Session manager), [`firmware/src/node_a/main.cpp`](https://github.com/bibek198/biobridge-gateway/blob/main/firmware/src/node_a/main.cpp) (ECG node), [`firmware/src/node_b/main.cpp`](https://github.com/bibek198/biobridge-gateway/blob/main/firmware/src/node_b/main.cpp) (PPG node), [`app/src/drivers/descriptorDriver.ts`](https://github.com/bibek198/biobridge-gateway/blob/main/app/src/drivers/descriptorDriver.ts) (Descriptor driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hardware["Sensor firmware"]
  node_nodea["ECG node<br/>[main.cpp]"]
  node_nodeb["PPG node<br/>[main.cpp]"]
  node_syncnode["Sync node<br/>[main.cpp]"]
  node_framing["Frame protocol<br/>[bbframe.c]"]
  node_placement["Edge placement<br/>[placement.cpp]"]
end

subgraph group_gateway["Browser gateway"]
  node_gatewayapp["Gateway UI<br/>[App.tsx]"]
  node_manager["Session manager<br/>[sessionManager.ts]"]
  node_transports["Device transports"]
end

subgraph group_interpret["Decode and timing"]
  node_drivers["Descriptor driver"]
  node_descriptors["Descriptor compiler<br/>[compile.ts]"]
  node_clock["Clock mapping<br/>[clock.ts]"]
end

subgraph group_analysis["Compute and research"]
  node_dsp["Shared DSP<br/>[bbdsp.c]"]
  node_compute["Compute pipeline<br/>[pipeline.ts]"]
  node_wasmdsp["Browser DSP<br/>[edgeDsp.ts]"]
  node_sync["Sync evaluation<br/>[evaluate.ts]"]
  node_verifier["Descriptor verifier<br/>[verifier.ts]"]
end

subgraph group_records["Records and synthesis"]
  node_recording["Recording format<br/>[recording.ts]"]
  node_recordstore[("Recording storage<br/>[recordingStore.ts]")]
  node_synthesis["Descriptor synthesis<br/>[service.ts]"]
end

node_sensor(("Sensor boards"))
node_llm{{"LLM providers"}}

node_sensor -->|"samples ECG"| node_nodea
node_sensor -->|"samples PPG"| node_nodeb
node_syncnode -.->|"timing pulse"| node_nodea
node_syncnode -.->|"timing pulse"| node_nodeb
node_nodea -->|"encodes frames"| node_framing
node_nodeb -->|"encodes frames"| node_framing
node_nodea -->|"configures placement"| node_placement
node_nodeb -->|"configures placement"| node_placement
node_placement -->|"runs algorithms"| node_dsp
node_nodea -->|"streams serial"| node_transports
node_nodeb -->|"streams BLE"| node_transports
node_transports -->|"delivers bytes"| node_drivers
node_drivers -->|"decodes with"| node_descriptors
node_drivers -->|"maps timestamps"| node_clock
node_manager -->|"manages connections"| node_drivers
node_manager -->|"processes readings"| node_compute
node_compute -->|"runs DSP modules"| node_wasmdsp
node_manager -->|"feeds dashboard"| node_gatewayapp
node_manager -->|"serializes recordings"| node_recording
node_recording -->|"stores recordings"| node_recordstore
node_manager -->|"evaluates alignment"| node_sync
node_manager -->|"checks data"| node_verifier
node_synthesis -->|"validates proposals"| node_verifier
node_synthesis -->|"requests proposals"| node_llm
node_gatewayapp -->|"accesses session"| node_manager

click node_nodea "https://github.com/bibek198/biobridge-gateway/blob/main/firmware/src/node_a/main.cpp"
click node_nodeb "https://github.com/bibek198/biobridge-gateway/blob/main/firmware/src/node_b/main.cpp"
click node_syncnode "https://github.com/bibek198/biobridge-gateway/blob/main/firmware/src/node_sync/main.cpp"
click node_framing "https://github.com/bibek198/biobridge-gateway/blob/main/firmware/lib/bbframe/src/bbframe.c"
click node_placement "https://github.com/bibek198/biobridge-gateway/blob/main/firmware/src/common/placement.cpp"
click node_dsp "https://github.com/bibek198/biobridge-gateway/blob/main/firmware/lib/bbdsp/src/bbdsp.c"
click node_gatewayapp "https://github.com/bibek198/biobridge-gateway/blob/main/app/src/App.tsx"
click node_manager "https://github.com/bibek198/biobridge-gateway/blob/main/app/src/session/sessionManager.ts"
click node_transports "https://github.com/bibek198/biobridge-gateway/tree/main/app/src/transports"
click node_drivers "https://github.com/bibek198/biobridge-gateway/blob/main/app/src/drivers/descriptorDriver.ts"
click node_descriptors "https://github.com/bibek198/biobridge-gateway/blob/main/app/src/descriptors/compile.ts"
click node_clock "https://github.com/bibek198/biobridge-gateway/blob/main/app/src/time/clock.ts"
click node_compute "https://github.com/bibek198/biobridge-gateway/blob/main/app/src/compute/pipeline.ts"
click node_wasmdsp "https://github.com/bibek198/biobridge-gateway/blob/main/app/src/dsp/edgeDsp.ts"
click node_sync "https://github.com/bibek198/biobridge-gateway/blob/main/app/src/sync/evaluate.ts"
click node_verifier "https://github.com/bibek198/biobridge-gateway/blob/main/app/src/verify/verifier.ts"
click node_recording "https://github.com/bibek198/biobridge-gateway/blob/main/app/src/session/recording.ts"
click node_recordstore "https://github.com/bibek198/biobridge-gateway/blob/main/app/src/session/recordingStore.ts"
click node_synthesis "https://github.com/bibek198/biobridge-gateway/blob/main/app/src/synth/service.ts"

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_nodea,node_nodeb,node_syncnode,node_framing,node_placement toneBlue
class node_gatewayapp,node_manager,node_transports toneAmber
class node_drivers,node_descriptors,node_clock toneMint
class node_dsp,node_compute,node_wasmdsp,node_sync,node_verifier toneRose
class node_recording,node_recordstore,node_synthesis,node_sensor,node_llm toneIndigo
```

## Components

### Sensor firmware

- [ECG node](https://github.com/bibek198/biobridge-gateway/blob/main/firmware/src/node_a/main.cpp): `firmware/src/node_a/main.cpp`
- [PPG node](https://github.com/bibek198/biobridge-gateway/blob/main/firmware/src/node_b/main.cpp): `firmware/src/node_b/main.cpp`
- [Sync node](https://github.com/bibek198/biobridge-gateway/blob/main/firmware/src/node_sync/main.cpp): `firmware/src/node_sync/main.cpp`
- [Frame protocol](https://github.com/bibek198/biobridge-gateway/blob/main/firmware/lib/bbframe/src/bbframe.c): `firmware/lib/bbframe/src/bbframe.c`
- [Edge placement](https://github.com/bibek198/biobridge-gateway/blob/main/firmware/src/common/placement.cpp): `firmware/src/common/placement.cpp`

### Browser gateway

- [Gateway UI](https://github.com/bibek198/biobridge-gateway/blob/main/app/src/App.tsx): `app/src/App.tsx`
- [Session manager](https://github.com/bibek198/biobridge-gateway/blob/main/app/src/session/sessionManager.ts): `app/src/session/sessionManager.ts`
- [Device transports](https://github.com/bibek198/biobridge-gateway/tree/main/app/src/transports): `app/src/transports`

### Decode and timing

- [Descriptor driver](https://github.com/bibek198/biobridge-gateway/blob/main/app/src/drivers/descriptorDriver.ts): `app/src/drivers/descriptorDriver.ts`
- [Descriptor compiler](https://github.com/bibek198/biobridge-gateway/blob/main/app/src/descriptors/compile.ts): `app/src/descriptors/compile.ts`
- [Clock mapping](https://github.com/bibek198/biobridge-gateway/blob/main/app/src/time/clock.ts): `app/src/time/clock.ts`

### Compute and research

- [Shared DSP](https://github.com/bibek198/biobridge-gateway/blob/main/firmware/lib/bbdsp/src/bbdsp.c): `firmware/lib/bbdsp/src/bbdsp.c`
- [Compute pipeline](https://github.com/bibek198/biobridge-gateway/blob/main/app/src/compute/pipeline.ts): `app/src/compute/pipeline.ts`
- [Browser DSP](https://github.com/bibek198/biobridge-gateway/blob/main/app/src/dsp/edgeDsp.ts): `app/src/dsp/edgeDsp.ts`
- [Sync evaluation](https://github.com/bibek198/biobridge-gateway/blob/main/app/src/sync/evaluate.ts): `app/src/sync/evaluate.ts`
- [Descriptor verifier](https://github.com/bibek198/biobridge-gateway/blob/main/app/src/verify/verifier.ts): `app/src/verify/verifier.ts`

### Records and synthesis

- [Recording format](https://github.com/bibek198/biobridge-gateway/blob/main/app/src/session/recording.ts): `app/src/session/recording.ts`
- [Recording storage](https://github.com/bibek198/biobridge-gateway/blob/main/app/src/session/recordingStore.ts): `app/src/session/recordingStore.ts`
- [Descriptor synthesis](https://github.com/bibek198/biobridge-gateway/blob/main/app/src/synth/service.ts): `app/src/synth/service.ts`

### Other components

- **Sensor boards**
- **LLM providers**

## Connections

- Sensor boards → ECG node: samples ECG
- Sensor boards → PPG node: samples PPG
- Sync node → ECG node: timing pulse
- Sync node → PPG node: timing pulse
- ECG node → Frame protocol: encodes frames (evidence: `firmware/src/node_a/main.cpp`)
- PPG node → Frame protocol: encodes frames (evidence: `firmware/src/node_b/main.cpp`)
- ECG node → Edge placement: configures placement (evidence: `firmware/src/node_a/main.cpp`)
- PPG node → Edge placement: configures placement (evidence: `firmware/src/node_b/main.cpp`)
- Edge placement → Shared DSP: runs algorithms
- ECG node → Device transports: streams serial
- PPG node → Device transports: streams BLE
- Device transports → Descriptor driver: delivers bytes
- Descriptor driver → Descriptor compiler: decodes with (evidence: `app/src/descriptors/compile.ts`)
- Descriptor driver → Clock mapping: maps timestamps
- Session manager → Descriptor driver: manages connections (evidence: `app/src/session/sessionManager.ts`)
- Session manager → Compute pipeline: processes readings (evidence: `app/src/session/sessionManager.ts`)
- Compute pipeline → Browser DSP: runs DSP modules (evidence: `app/src/session/sessionManager.ts`)
- Session manager → Gateway UI: feeds dashboard
- Session manager → Recording format: serializes recordings (evidence: `app/src/session/sessionManager.ts`)
- Recording format → Recording storage: stores recordings
- Session manager → Sync evaluation: evaluates alignment
- Session manager → Descriptor verifier: checks data (evidence: `app/src/session/sessionManager.ts`)
- Descriptor synthesis → Descriptor verifier: validates proposals (evidence: `app/src/synth/service.ts`)
- Descriptor synthesis → LLM providers: requests proposals (evidence: `app/src/synth/service.ts`)
- Gateway UI → Session manager: accesses session