# sander-w/breakwater architecture

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

- Interactive diagram: https://gitdiagram.com/sander-w/breakwater
- Repository: https://github.com/sander-w/breakwater

## Overview

breakwater is a Python package for conceptual breakwater design. Its principal workflow is to define hydraulic limit states and materials, choose a rubble-mound or caisson concept, compute design variants, and inspect the resulting concept. It also supports batches of configurations and an interactive parameter-tuning application; core calculation modules are exposed for custom automation. The README documents additional multi-criteria/DesignExplorer assessment, and the tree includes a breakwater database. Sampled excerpts are partial, so uncertain subsystem wiring is omitted.

Main entry points: [`breakwater/__init__.py`](https://github.com/sander-w/breakwater/blob/master/breakwater/__init__.py) (Package API), [`breakwater/rubble.py`](https://github.com/sander-w/breakwater/blob/master/breakwater/rubble.py) (Rubble mound), [`breakwater/caisson.py`](https://github.com/sander-w/breakwater/blob/master/breakwater/caisson.py) (Caisson), [`breakwater/design.py`](https://github.com/sander-w/breakwater/blob/master/breakwater/design.py) (Configurations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Design inputs"]
  node_conditions["Limit states<br/>[conditions.py]"]
  node_materials["Materials<br/>[material.py]"]
  node_waves["Wave utilities<br/>[wave.py]"]
end

subgraph group_design["Concept design"]
  node_config["Configurations<br/>[design.py]"]
  node_rubble["Rubble mound<br/>[rubble.py]"]
  node_caisson["Caisson<br/>[caisson.py]"]
end

subgraph group_analysis["Engineering analysis"]
  node_stability["Stability methods<br/>[stability.py]"]
  node_overtopping["Overtopping methods<br/>[overtopping.py]"]
  node_toe["Toe stability<br/>[toe.py]"]
  node_goda["Goda methods<br/>[goda.py]"]
  node_soil["Soil analysis<br/>[soil.py]"]
  node_bishop["Bishop analysis<br/>[bishop.py]"]
end

subgraph group_exploration["Design exploration"]
  node_interactive_entry["Interactive entry<br/>[interactive.py]"]
  node_interactive_app["Interactive UI<br/>[main.py]"]
  node_varying_ui["Parameter controls<br/>[input.py]"]
  node_design_ui["Design view<br/>[interactive.py]"]
  node_cost["Cost estimates<br/>[cost.py]"]
  node_explorer["DesignExplorer export"]
end

subgraph group_data["Reference data"]
  node_database[("Breakwater database<br/>[database.py]")]
end

node_designer(("Designer"))
node_api["Package API<br/>[__init__.py]"]
node_reference_site(("Reference database site"))
node_design_explorer(("DesignExplorer"))

node_designer -->|"uses"| node_api
node_api -->|"exposes"| node_conditions
node_api -->|"exposes"| node_materials
node_api -->|"exposes"| node_config
node_api -->|"exposes"| node_rubble
node_api -->|"exposes"| node_caisson
node_api -->|"exposes"| node_interactive_entry
node_api -->|"exposes"| node_waves
node_designer -->|"defines"| node_conditions
node_designer -->|"defines"| node_materials
node_designer -->|"computes waves"| node_waves
node_designer -->|"designs"| node_rubble
node_designer -->|"designs"| node_caisson
node_designer -->|"configures"| node_config
node_config -->|"constructs"| node_rubble
node_config -->|"constructs"| node_caisson
node_rubble -->|"uses"| node_stability
node_rubble -->|"uses"| node_toe
node_rubble -->|"uses"| node_overtopping
node_caisson -->|"uses"| node_goda
node_caisson -->|"uses"| node_overtopping
node_caisson -->|"uses"| node_toe
node_designer -->|"starts"| node_interactive_entry
node_interactive_entry -->|"launches"| node_interactive_app
node_interactive_app -->|"hosts"| node_varying_ui
node_interactive_app -->|"hosts"| node_design_ui
node_config -->|"estimates cost"| node_cost
node_designer -.->|"exports concepts"| node_explorer
node_explorer -.->|"opens in"| node_design_explorer
node_designer -->|"queries"| node_database
node_database -.->|"updates from"| node_reference_site
node_designer -.->|"uses directly"| node_soil
node_designer -.->|"uses directly"| node_bishop

click node_api "https://github.com/sander-w/breakwater/blob/master/breakwater/__init__.py"
click node_conditions "https://github.com/sander-w/breakwater/blob/master/breakwater/conditions.py"
click node_materials "https://github.com/sander-w/breakwater/blob/master/breakwater/material.py"
click node_waves "https://github.com/sander-w/breakwater/blob/master/breakwater/utils/wave.py"
click node_config "https://github.com/sander-w/breakwater/blob/master/breakwater/design.py"
click node_rubble "https://github.com/sander-w/breakwater/blob/master/breakwater/rubble.py"
click node_caisson "https://github.com/sander-w/breakwater/blob/master/breakwater/caisson.py"
click node_interactive_entry "https://github.com/sander-w/breakwater/blob/master/breakwater/interactive.py"
click node_interactive_app "https://github.com/sander-w/breakwater/blob/master/breakwater/app/main.py"
click node_varying_ui "https://github.com/sander-w/breakwater/blob/master/breakwater/app/input.py"
click node_design_ui "https://github.com/sander-w/breakwater/blob/master/breakwater/app/interactive.py"
click node_cost "https://github.com/sander-w/breakwater/blob/master/breakwater/utils/cost.py"
click node_explorer "https://github.com/sander-w/breakwater/blob/master/breakwater/utils/_design_explorer.py"
click node_stability "https://github.com/sander-w/breakwater/blob/master/breakwater/core/stability.py"
click node_overtopping "https://github.com/sander-w/breakwater/blob/master/breakwater/core/overtopping.py"
click node_toe "https://github.com/sander-w/breakwater/blob/master/breakwater/core/toe.py"
click node_goda "https://github.com/sander-w/breakwater/blob/master/breakwater/core/goda.py"
click node_soil "https://github.com/sander-w/breakwater/blob/master/breakwater/core/soil.py"
click node_bishop "https://github.com/sander-w/breakwater/blob/master/breakwater/core/bishop.py"
click node_database "https://github.com/sander-w/breakwater/blob/master/breakwater/database/database.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_conditions,node_materials,node_waves toneBlue
class node_config,node_rubble,node_caisson,node_reference_site toneAmber
class node_stability,node_overtopping,node_toe,node_goda,node_soil,node_bishop,node_api toneMint
class node_interactive_entry,node_interactive_app,node_varying_ui,node_design_ui,node_cost,node_explorer toneRose
class node_database,node_designer,node_design_explorer toneIndigo
```

## Components

### Design inputs

- [Limit states](https://github.com/sander-w/breakwater/blob/master/breakwater/conditions.py): `breakwater/conditions.py`
- [Materials](https://github.com/sander-w/breakwater/blob/master/breakwater/material.py): `breakwater/material.py`
- [Wave utilities](https://github.com/sander-w/breakwater/blob/master/breakwater/utils/wave.py): `breakwater/utils/wave.py`

### Concept design

- [Configurations](https://github.com/sander-w/breakwater/blob/master/breakwater/design.py): `breakwater/design.py`
- [Rubble mound](https://github.com/sander-w/breakwater/blob/master/breakwater/rubble.py): `breakwater/rubble.py`
- [Caisson](https://github.com/sander-w/breakwater/blob/master/breakwater/caisson.py): `breakwater/caisson.py`

### Engineering analysis

- [Stability methods](https://github.com/sander-w/breakwater/blob/master/breakwater/core/stability.py): `breakwater/core/stability.py`
- [Overtopping methods](https://github.com/sander-w/breakwater/blob/master/breakwater/core/overtopping.py): `breakwater/core/overtopping.py`
- [Toe stability](https://github.com/sander-w/breakwater/blob/master/breakwater/core/toe.py): `breakwater/core/toe.py`
- [Goda methods](https://github.com/sander-w/breakwater/blob/master/breakwater/core/goda.py): `breakwater/core/goda.py`
- [Soil analysis](https://github.com/sander-w/breakwater/blob/master/breakwater/core/soil.py): `breakwater/core/soil.py`
- [Bishop analysis](https://github.com/sander-w/breakwater/blob/master/breakwater/core/bishop.py): `breakwater/core/bishop.py`

### Design exploration

- [Interactive entry](https://github.com/sander-w/breakwater/blob/master/breakwater/interactive.py): `breakwater/interactive.py`
- [Interactive UI](https://github.com/sander-w/breakwater/blob/master/breakwater/app/main.py): `breakwater/app/main.py`
- [Parameter controls](https://github.com/sander-w/breakwater/blob/master/breakwater/app/input.py): `breakwater/app/input.py`
- [Design view](https://github.com/sander-w/breakwater/blob/master/breakwater/app/interactive.py): `breakwater/app/interactive.py`
- [Cost estimates](https://github.com/sander-w/breakwater/blob/master/breakwater/utils/cost.py): `breakwater/utils/cost.py`
- [DesignExplorer export](https://github.com/sander-w/breakwater/blob/master/breakwater/utils/_design_explorer.py): `breakwater/utils/_design_explorer.py`

### Reference data

- [Breakwater database](https://github.com/sander-w/breakwater/blob/master/breakwater/database/database.py): `breakwater/database/database.py`

### Other components

- **Designer**
- [Package API](https://github.com/sander-w/breakwater/blob/master/breakwater/__init__.py): `breakwater/__init__.py`
- **Reference database site**
- **DesignExplorer**

## Connections

- Designer → Package API: uses
- Package API → Limit states: exposes
- Package API → Materials: exposes
- Package API → Configurations: exposes
- Package API → Rubble mound: exposes
- Package API → Caisson: exposes
- Package API → Interactive entry: exposes
- Package API → Wave utilities: exposes
- Designer → Limit states: defines
- Designer → Materials: defines
- Designer → Wave utilities: computes waves
- Designer → Rubble mound: designs
- Designer → Caisson: designs
- Designer → Configurations: configures
- Configurations → Rubble mound: constructs
- Configurations → Caisson: constructs
- Rubble mound → Stability methods: uses
- Rubble mound → Toe stability: uses
- Rubble mound → Overtopping methods: uses
- Caisson → Goda methods: uses
- Caisson → Overtopping methods: uses
- Caisson → Toe stability: uses
- Designer → Interactive entry: starts
- Interactive entry → Interactive UI: launches
- Interactive UI → Parameter controls: hosts
- Interactive UI → Design view: hosts
- Configurations → Cost estimates: estimates cost
- Designer → DesignExplorer export: exports concepts
- DesignExplorer export → DesignExplorer: opens in
- Designer → Breakwater database: queries
- Breakwater database → Reference database site: updates from
- Designer → Soil analysis: uses directly
- Designer → Bishop analysis: uses directly