# rishu07368/basinwatch architecture

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

- Interactive diagram: https://gitdiagram.com/rishu07368/basinwatch
- Repository: https://github.com/rishu07368/basinwatch

## Overview

BasinWatch is an offline desktop floodplain operations simulation. Operators advance or observe a scenario, review zone risk and resources, dispatch response missions, follow progress, and save or report on the session. The documented runtime separates sensor production, intake, buffered event processing, and model updates; immutable snapshots return to the Swing interface. File-based session, archive, journal, and report capabilities remain independent of optional SQLite history. The graph preserves README capabilities, but some subsystem links are documented rather than confirmed in sampled implementation excerpts.

Main entry points: [`src/main/java/com/basinwatch/engine/BasinEngine.java`](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/engine/BasinEngine.java) (Engine lifecycle), [`src/main/java/com/basinwatch/app/MainFrame.java`](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/app/MainFrame.java) (Swing console), [`src/main/java/com/basinwatch/domain/BasinModel.java`](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/domain/BasinModel.java) (Basin model), [`src/main/java/com/basinwatch/domain`](https://github.com/rishu07368/basinwatch/tree/main/src/main/java/com/basinwatch/domain) (Domain snapshots and events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Operator interface"]
  node_desktop["Swing console<br/>[MainFrame.java]"]
  node_basinmap["Basin map<br/>[BasinMapPanel.java]"]
  node_dbhistoryui["History viewer"]
  node_learning["Architecture inspector"]
end

subgraph group_runtime["Simulation runtime"]
  node_engine["Engine lifecycle<br/>[BasinEngine.java]"]
  node_feed["Sensor feed<br/>[SensorFeed.java]"]
  node_intake["Sensor intake<br/>[SensorIntake.java]"]
  node_buffer["Event buffer<br/>[EventBuffer.java]"]
  node_responseworkers["Response workers<br/>[BasinEngine.java]"]
  node_archiveworker["Archive worker<br/>[ArchiveWorker.java]"]
end

subgraph group_domain["Basin operations"]
  node_basinmodel["Basin model<br/>[BasinModel.java]"]
  node_domainvalues["Domain snapshots and events"]
  node_allocator["Resource allocator"]
end

subgraph group_persistence["Persistence and history"]
  node_sessionstore["Session saves<br/>[SnapshotStore.java]"]
  node_savecatalog["Save catalog<br/>[SaveCatalog.java]"]
  node_archive[("Sensor archive<br/>[SensorArchive.java]")]
  node_journal["Operational journal"]
  node_reports["Operational reports<br/>[ReportWriter.java]"]
  node_dbservice["SQLite history service"]
  node_dbmanager["SQLite connection manager"]
  node_dbrepos["History repositories"]
end

node_operator(("Operator"))

node_operator -->|"operates"| node_desktop
node_desktop -->|"controls"| node_engine
node_desktop -->|"updates view"| node_basinmap
node_engine -->|"starts feed"| node_feed
node_feed -->|"pipes observations"| node_intake
node_intake -->|"queues events"| node_buffer
node_buffer -->|"supplies work"| node_responseworkers
node_responseworkers -->|"processes events"| node_basinmodel
node_basinmodel -->|"reserves resources"| node_allocator
node_basinmodel -->|"produces snapshots"| node_domainvalues
node_engine -->|"publishes snapshots"| node_domainvalues
node_domainvalues -->|"renders basin state"| node_basinmap
node_engine -->|"archives readings"| node_archiveworker
node_archiveworker -->|"writes measurements"| node_archive
node_engine -->|"records events"| node_journal
node_desktop -->|"saves sessions"| node_sessionstore
node_desktop -->|"lists saves"| node_savecatalog
node_engine -.->|"generates reports"| node_reports
node_engine -->|"records history"| node_dbservice
node_dbhistoryui -.->|"requests history"| node_engine
node_dbservice -->|"dispatches queries"| node_dbrepos
node_dbrepos -->|"opens connections"| node_dbmanager
node_desktop -->|"shows inspector"| node_learning

click node_desktop "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/app/MainFrame.java"
click node_basinmap "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/app/BasinMapPanel.java"
click node_dbhistoryui "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/app/DatabaseHistoryPanel.java"
click node_engine "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/engine/BasinEngine.java"
click node_feed "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/engine/SensorFeed.java"
click node_intake "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/engine/SensorIntake.java"
click node_buffer "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/engine/EventBuffer.java"
click node_responseworkers "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/engine/BasinEngine.java"
click node_archiveworker "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/engine/ArchiveWorker.java"
click node_basinmodel "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/domain/BasinModel.java"
click node_domainvalues "https://github.com/rishu07368/basinwatch/tree/main/src/main/java/com/basinwatch/domain"
click node_allocator "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/domain/ResourceAllocator.java"
click node_sessionstore "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/io/SnapshotStore.java"
click node_savecatalog "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/io/SaveCatalog.java"
click node_archive "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/io/SensorArchive.java"
click node_journal "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/io/OperationalJournal.java"
click node_reports "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/io/ReportWriter.java"
click node_dbservice "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/db/DatabaseService.java"
click node_dbmanager "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/db/DatabaseManager.java"
click node_dbrepos "https://github.com/rishu07368/basinwatch/tree/main/src/main/java/com/basinwatch/db"
click node_learning "https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/learning/LearningCatalog.java"

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_desktop,node_basinmap,node_dbhistoryui,node_learning toneBlue
class node_engine,node_feed,node_intake,node_buffer,node_responseworkers,node_archiveworker toneAmber
class node_basinmodel,node_domainvalues,node_allocator toneMint
class node_sessionstore,node_savecatalog,node_archive,node_journal,node_reports,node_dbservice,node_dbmanager,node_dbrepos toneRose
class node_operator toneIndigo
```

## Components

### Operator interface

- [Swing console](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/app/MainFrame.java): `src/main/java/com/basinwatch/app/MainFrame.java`
- [Basin map](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/app/BasinMapPanel.java): `src/main/java/com/basinwatch/app/BasinMapPanel.java`
- [History viewer](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/app/DatabaseHistoryPanel.java): `src/main/java/com/basinwatch/app/DatabaseHistoryPanel.java`
- [Architecture inspector](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/learning/LearningCatalog.java): `src/main/java/com/basinwatch/learning/LearningCatalog.java`

### Simulation runtime

- [Engine lifecycle](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/engine/BasinEngine.java): `src/main/java/com/basinwatch/engine/BasinEngine.java`
- [Sensor feed](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/engine/SensorFeed.java): `src/main/java/com/basinwatch/engine/SensorFeed.java`
- [Sensor intake](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/engine/SensorIntake.java): `src/main/java/com/basinwatch/engine/SensorIntake.java`
- [Event buffer](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/engine/EventBuffer.java): `src/main/java/com/basinwatch/engine/EventBuffer.java`
- [Response workers](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/engine/BasinEngine.java): `src/main/java/com/basinwatch/engine/BasinEngine.java`
- [Archive worker](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/engine/ArchiveWorker.java): `src/main/java/com/basinwatch/engine/ArchiveWorker.java`

### Basin operations

- [Basin model](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/domain/BasinModel.java): `src/main/java/com/basinwatch/domain/BasinModel.java`
- [Domain snapshots and events](https://github.com/rishu07368/basinwatch/tree/main/src/main/java/com/basinwatch/domain): `src/main/java/com/basinwatch/domain`
- [Resource allocator](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/domain/ResourceAllocator.java): `src/main/java/com/basinwatch/domain/ResourceAllocator.java`

### Persistence and history

- [Session saves](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/io/SnapshotStore.java): `src/main/java/com/basinwatch/io/SnapshotStore.java`
- [Save catalog](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/io/SaveCatalog.java): `src/main/java/com/basinwatch/io/SaveCatalog.java`
- [Sensor archive](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/io/SensorArchive.java): `src/main/java/com/basinwatch/io/SensorArchive.java`
- [Operational journal](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/io/OperationalJournal.java): `src/main/java/com/basinwatch/io/OperationalJournal.java`
- [Operational reports](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/io/ReportWriter.java): `src/main/java/com/basinwatch/io/ReportWriter.java`
- [SQLite history service](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/db/DatabaseService.java): `src/main/java/com/basinwatch/db/DatabaseService.java`
- [SQLite connection manager](https://github.com/rishu07368/basinwatch/blob/main/src/main/java/com/basinwatch/db/DatabaseManager.java): `src/main/java/com/basinwatch/db/DatabaseManager.java`
- [History repositories](https://github.com/rishu07368/basinwatch/tree/main/src/main/java/com/basinwatch/db): `src/main/java/com/basinwatch/db`

### Other components

- **Operator**

## Connections

- Operator → Swing console: operates (evidence: `README.md`)
- Swing console → Engine lifecycle: controls (evidence: `src/main/java/com/basinwatch/app/MainFrame.java`)
- Swing console → Basin map: updates view (evidence: `src/main/java/com/basinwatch/app/MainFrame.java`)
- Engine lifecycle → Sensor feed: starts feed (evidence: `README.md`)
- Sensor feed → Sensor intake: pipes observations (evidence: `README.md`)
- Sensor intake → Event buffer: queues events (evidence: `README.md`)
- Event buffer → Response workers: supplies work (evidence: `README.md`)
- Response workers → Basin model: processes events (evidence: `src/main/java/com/basinwatch/engine/BasinEngine.java`)
- Basin model → Resource allocator: reserves resources (evidence: `src/main/java/com/basinwatch/domain/BasinModel.java`)
- Basin model → Domain snapshots and events: produces snapshots (evidence: `src/main/java/com/basinwatch/domain/BasinModel.java`)
- Engine lifecycle → Domain snapshots and events: publishes snapshots (evidence: `README.md`)
- Domain snapshots and events → Basin map: renders basin state (evidence: `README.md`)
- Engine lifecycle → Archive worker: archives readings (evidence: `src/main/java/com/basinwatch/engine/BasinEngine.java`)
- Archive worker → Sensor archive: writes measurements (evidence: `src/main/java/com/basinwatch/engine/ArchiveWorker.java`)
- Engine lifecycle → Operational journal: records events (evidence: `src/main/java/com/basinwatch/engine/BasinEngine.java`)
- Swing console → Session saves: saves sessions (evidence: `README.md`)
- Swing console → Save catalog: lists saves (evidence: `src/main/java/com/basinwatch/app/MainFrame.java`)
- Engine lifecycle → Operational reports: generates reports (evidence: `README.md`)
- Engine lifecycle → SQLite history service: records history (evidence: `src/main/java/com/basinwatch/engine/BasinEngine.java`)
- History viewer → Engine lifecycle: requests history (evidence: `src/main/java/com/basinwatch/app/DatabaseHistoryPanel.java`)
- SQLite history service → History repositories: dispatches queries (evidence: `src/main/java/com/basinwatch/db/DatabaseService.java`)
- History repositories → SQLite connection manager: opens connections (evidence: `src/main/java/com/basinwatch/db/SensorReadingRepository.java`)
- Swing console → Architecture inspector: shows inspector (evidence: `src/main/java/com/basinwatch/app/MainFrame.java`)
