# doppalapudinagavenkatasai/aqua-pulse architecture

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

- Interactive diagram: https://gitdiagram.com/doppalapudinagavenkatasai/aqua-pulse
- Repository: https://github.com/doppalapudinagavenkatasai/aqua-pulse

## Overview

AQUAPULSE combines an embedded adaptive sonar payload with a browser-based ground station and a Python telemetry/RAG service. The payload workflow samples environmental sensors, selects sonar parameters with TinyML, transmits a synthesized chirp, classifies echoes, and emits telemetry; the console visualizes acoustic propagation and mission data. The backend exposes telemetry, persistence, simulation, and mission-rationale endpoints. Several UI capabilities are documented or indexed but their wiring is not fully shown, so relationships are limited to visible imports, calls, or README statements.

Main entry points: [`src/App.tsx`](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/App.tsx) (Ground station app), [`backend/server.py`](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/backend/server.py) (Ground station API), [`firmware/src/main.cpp`](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/firmware/src/main.cpp) (Payload runtime), [`src/physics/oceanAcoustics.ts`](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/physics/oceanAcoustics.ts) (Ocean acoustics model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_payload["Embedded payload"]
  node_firmware_entry["Payload runtime<br/>[main.cpp]"]
  node_sensors["Environmental sensing<br/>[sensor_adc.c]"]
  node_policy["TinyML policy<br/>[tinyml_policy.cpp]"]
  node_wave["DMA chirp engine<br/>[dma_dac_engine.c]"]
  node_config["Channel configuration<br/>[config.h]"]
  node_front_end["Analog front end"]
end

subgraph group_console["Ground station"]
  node_web_app["Ground station app<br/>[App.tsx]"]
  node_nav["Mode and scenario controls<br/>[Navbar.tsx]"]
  node_boot["Boot sequence<br/>[BootSequence.tsx]"]
  node_ocean_view["Ocean propagation view<br/>[OceanCanvas.tsx]"]
  node_comparison["Sonar comparison<br/>[ComparisonView.tsx]"]
  node_bathymetry["Bathymetry mapping<br/>[BathymetryMap.tsx]"]
  node_telemetry_views["Telemetry visualizations"]
  node_live_bridge["Hardware bridge"]
  node_rag_modal["RAG assistant UI"]
end

subgraph group_service["Telemetry services"]
  node_api["Ground station API<br/>[server.py]"]
  node_database[("Telemetry persistence<br/>[database.py]")]
  node_simulator["Telemetry simulator<br/>[simulator.py]"]
  node_rag_engine["Oceanographic RAG<br/>[rag_engine.py]"]
end

subgraph group_physics["Acoustic modeling"]
  node_domain_types["Sonar data types<br/>[sonar.ts]"]
  node_acoustic_model["Ocean acoustics model<br/>[oceanAcoustics.ts]"]
  node_presets["Scenario presets<br/>[presets.ts]"]
end

node_operator(("Console operator"))
node_auv(("AUV and sonar environment"))

node_operator -->|"uses"| node_web_app
node_web_app -->|"renders"| node_nav
node_web_app -->|"renders"| node_boot
node_web_app -->|"renders"| node_ocean_view
node_web_app -->|"renders"| node_comparison
node_web_app -->|"renders"| node_bathymetry
node_web_app -->|"renders"| node_telemetry_views
node_web_app -->|"renders"| node_rag_modal
node_web_app -->|"renders"| node_live_bridge
node_ocean_view -->|"uses"| node_acoustic_model
node_bathymetry -->|"uses"| node_acoustic_model
node_telemetry_views -->|"uses"| node_acoustic_model
node_telemetry_views -->|"uses"| node_domain_types
node_acoustic_model -->|"uses"| node_domain_types
node_presets -->|"uses"| node_domain_types
node_firmware_entry -->|"reads"| node_sensors
node_firmware_entry -->|"invokes"| node_policy
node_firmware_entry -->|"initializes"| node_wave
node_wave -->|"uses"| node_config
node_firmware_entry -.->|"streams telemetry"| node_auv
node_wave -.->|"drives signal"| node_front_end
node_live_bridge -.->|"exchanges telemetry"| node_api
node_api -->|"reads and writes"| node_database
node_api -->|"requests samples"| node_simulator
node_api -->|"requests rationale"| node_rag_engine
node_rag_modal -.->|"submits questions"| node_api

click node_firmware_entry "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/firmware/src/main.cpp"
click node_sensors "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/firmware/src/sensor_adc.c"
click node_policy "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/firmware/src/tinyml_policy.cpp"
click node_wave "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/firmware/src/dma_dac_engine.c"
click node_config "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/firmware/include/config.h"
click node_front_end "https://github.com/doppalapudinagavenkatasai/aqua-pulse/tree/main/hardware/simulation"
click node_web_app "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/App.tsx"
click node_nav "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/components/common/Navbar.tsx"
click node_boot "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/components/common/BootSequence.tsx"
click node_ocean_view "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/components/simulations/OceanCanvas.tsx"
click node_comparison "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/components/simulations/ComparisonView.tsx"
click node_bathymetry "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/components/simulations/BathymetryMap.tsx"
click node_telemetry_views "https://github.com/doppalapudinagavenkatasai/aqua-pulse/tree/main/src/components/telemetry"
click node_live_bridge "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/components/telemetry/LiveHardwareBridge.tsx"
click node_rag_modal "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/components/common/RagAssistantModal.tsx"
click node_domain_types "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/types/sonar.ts"
click node_acoustic_model "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/physics/oceanAcoustics.ts"
click node_presets "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/physics/presets.ts"
click node_api "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/backend/server.py"
click node_database "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/backend/database.py"
click node_simulator "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/backend/simulator.py"
click node_rag_engine "https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/backend/rag_engine.py"

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_firmware_entry,node_sensors,node_policy,node_wave,node_config,node_front_end toneBlue
class node_web_app,node_nav,node_boot,node_ocean_view,node_comparison,node_bathymetry,node_telemetry_views,node_live_bridge,node_rag_modal toneAmber
class node_api,node_database,node_simulator,node_rag_engine toneMint
class node_domain_types,node_acoustic_model,node_presets toneRose
class node_operator,node_auv toneIndigo
```

## Components

### Embedded payload

- [Payload runtime](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/firmware/src/main.cpp): `firmware/src/main.cpp`
- [Environmental sensing](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/firmware/src/sensor_adc.c): `firmware/src/sensor_adc.c`
- [TinyML policy](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/firmware/src/tinyml_policy.cpp): `firmware/src/tinyml_policy.cpp`
- [DMA chirp engine](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/firmware/src/dma_dac_engine.c): `firmware/src/dma_dac_engine.c`
- [Channel configuration](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/firmware/include/config.h): `firmware/include/config.h`
- [Analog front end](https://github.com/doppalapudinagavenkatasai/aqua-pulse/tree/main/hardware/simulation): `hardware/simulation`

### Ground station

- [Ground station app](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/App.tsx): `src/App.tsx`
- [Mode and scenario controls](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/components/common/Navbar.tsx): `src/components/common/Navbar.tsx`
- [Boot sequence](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/components/common/BootSequence.tsx): `src/components/common/BootSequence.tsx`
- [Ocean propagation view](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/components/simulations/OceanCanvas.tsx): `src/components/simulations/OceanCanvas.tsx`
- [Sonar comparison](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/components/simulations/ComparisonView.tsx): `src/components/simulations/ComparisonView.tsx`
- [Bathymetry mapping](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/components/simulations/BathymetryMap.tsx): `src/components/simulations/BathymetryMap.tsx`
- [Telemetry visualizations](https://github.com/doppalapudinagavenkatasai/aqua-pulse/tree/main/src/components/telemetry): `src/components/telemetry`
- [Hardware bridge](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/components/telemetry/LiveHardwareBridge.tsx): `src/components/telemetry/LiveHardwareBridge.tsx`
- [RAG assistant UI](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/components/common/RagAssistantModal.tsx): `src/components/common/RagAssistantModal.tsx`

### Telemetry services

- [Ground station API](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/backend/server.py): `backend/server.py`
- [Telemetry persistence](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/backend/database.py): `backend/database.py`
- [Telemetry simulator](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/backend/simulator.py): `backend/simulator.py`
- [Oceanographic RAG](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/backend/rag_engine.py): `backend/rag_engine.py`

### Acoustic modeling

- [Sonar data types](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/types/sonar.ts): `src/types/sonar.ts`
- [Ocean acoustics model](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/physics/oceanAcoustics.ts): `src/physics/oceanAcoustics.ts`
- [Scenario presets](https://github.com/doppalapudinagavenkatasai/aqua-pulse/blob/main/src/physics/presets.ts): `src/physics/presets.ts`

### Other components

- **Console operator**
- **AUV and sonar environment**

## Connections

- Console operator → Ground station app: uses (evidence: `README.md`)
- Ground station app → Mode and scenario controls: renders (evidence: `src/App.tsx`)
- Ground station app → Boot sequence: renders (evidence: `src/App.tsx`)
- Ground station app → Ocean propagation view: renders (evidence: `src/App.tsx`)
- Ground station app → Sonar comparison: renders (evidence: `src/App.tsx`)
- Ground station app → Bathymetry mapping: renders (evidence: `src/App.tsx`)
- Ground station app → Telemetry visualizations: renders (evidence: `src/App.tsx`)
- Ground station app → RAG assistant UI: renders (evidence: `src/App.tsx`)
- Ground station app → Hardware bridge: renders (evidence: `src/App.tsx`)
- Ocean propagation view → Ocean acoustics model: uses (evidence: `src/components/simulations/OceanCanvas.tsx`)
- Bathymetry mapping → Ocean acoustics model: uses (evidence: `src/components/simulations/BathymetryMap.tsx`)
- Telemetry visualizations → Ocean acoustics model: uses (evidence: `src/components/telemetry/PhysicsPanel.tsx`)
- Telemetry visualizations → Sonar data types: uses (evidence: `src/components/telemetry/PhysicsPanel.tsx`)
- Ocean acoustics model → Sonar data types: uses (evidence: `src/physics/oceanAcoustics.ts`)
- Scenario presets → Sonar data types: uses (evidence: `src/physics/presets.ts`)
- Payload runtime → Environmental sensing: reads (evidence: `firmware/src/main.cpp`)
- Payload runtime → TinyML policy: invokes (evidence: `firmware/src/main.cpp`)
- Payload runtime → DMA chirp engine: initializes (evidence: `firmware/src/main.cpp`)
- DMA chirp engine → Channel configuration: uses
- Payload runtime → AUV and sonar environment: streams telemetry (evidence: `README.md`)
- DMA chirp engine → Analog front end: drives signal (evidence: `README.md`)
- Hardware bridge → Ground station API: exchanges telemetry (evidence: `README.md`)
- Ground station API → Telemetry persistence: reads and writes (evidence: `backend/server.py`)
- Ground station API → Telemetry simulator: requests samples (evidence: `backend/server.py`)
- Ground station API → Oceanographic RAG: requests rationale (evidence: `backend/server.py`)
- RAG assistant UI → Ground station API: submits questions
