# rpendleton/battleship-rust architecture

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

- Interactive diagram: https://gitdiagram.com/rpendleton/battleship-rust
- Repository: https://github.com/rpendleton/battleship-rust

## Overview

Battleship Probability Engine has two main workflows: generating and encoding the legal-board dataset offline, then filtering that dataset at query time to produce per-cell ship counts. The graph also preserves the generator’s board rules and the CLI/FFI entry points. The reader and CLI behavior are supported by sampled source; generator and dataset stages are described in the README. Filter internals and FFI wiring are not sampled, so their documented relationships are shown without inferring further implementation details.

Main entry points: [`src/core/reader.rs`](https://github.com/rpendleton/battleship-rust/blob/main/src/core/reader.rs) (Dataset reader), [`src/core/filter.rs`](https://github.com/rpendleton/battleship-rust/blob/main/src/core/filter.rs) (Filter and count), [`src/bin/generator.rs`](https://github.com/rpendleton/battleship-rust/blob/main/src/bin/generator.rs) (Generator CLI), [`src/main.rs`](https://github.com/rpendleton/battleship-rust/blob/main/src/main.rs) (Query CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Dataset generation"]
  node_generator_cli["Generator CLI<br/>[generator.rs]"]
  node_enumerator["Board enumeration<br/>[generator.rs]"]
  node_raw_dataset[("Raw board records")]
  node_encoder["Delta encoder<br/>[encoder.rs]"]
  node_delta_dataset[("Delta records")]
  node_zstd_tool["zstd compressor"]
  node_compressed_dataset[("Compressed dataset")]
end

subgraph group_model["Board model"]
  node_board_state["Placement state<br/>[board_state.rs]"]
  node_common_masks["Placement masks<br/>[common_masks.rs]"]
  node_board_mask["Bitmask utilities<br/>[board_mask.rs]"]
  node_point["Board coordinates<br/>[point.rs]"]
  node_symmetries["Symmetry filter<br/>[symmetries.rs]"]
end

subgraph group_query["Query runtime"]
  node_reader["Dataset reader<br/>[reader.rs]"]
  node_filter["Filter and count<br/>[filter.rs]"]
  node_rayon["Parallel counting<br/>[filter.rs]"]
  node_heatmap["Cell count heatmap"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["Query CLI<br/>[main.rs]"]
  node_ffi["C FFI wrapper<br/>[ffi.rs]"]
end

node_generator_user(("Dataset operator"))
node_query_user(("Query client"))
node_api_client(("Rust API client"))
node_ffi_client(("Swift / iOS client"))

node_generator_user -->|"runs"| node_generator_cli
node_generator_cli -->|"starts enumeration"| node_enumerator
node_enumerator -->|"places ships"| node_board_state
node_board_state -->|"gets placement masks"| node_common_masks
node_common_masks -->|"builds masks"| node_board_mask
node_board_state -->|"updates masks"| node_board_mask
node_enumerator -->|"uses coordinates"| node_point
node_generator_cli -->|"filters canonical boards"| node_symmetries
node_generator_cli -->|"writes records"| node_raw_dataset
node_raw_dataset -->|"streams records"| node_encoder
node_encoder -->|"writes XOR deltas"| node_delta_dataset
node_delta_dataset -.->|"compresses"| node_zstd_tool
node_zstd_tool -.->|"writes compressed data"| node_compressed_dataset
node_query_user -->|"submits masks"| node_cli
node_cli -->|"opens dataset"| node_reader
node_cli -->|"passes masks and boards"| node_filter
node_api_client -->|"creates reader"| node_reader
node_api_client -->|"queries boards"| node_filter
node_ffi_client -->|"passes masks and path"| node_ffi
node_ffi -->|"opens dataset"| node_reader
node_ffi -->|"queries boards"| node_filter
node_compressed_dataset -->|"streams records"| node_reader
node_reader -.->|"decodes when compressed"| node_zstd_tool
node_reader -->|"yields decoded boards"| node_filter
node_filter -->|"counts in parallel"| node_rayon
node_filter -->|"returns cell counts"| node_heatmap
node_heatmap -->|"prints CSV"| node_cli
node_heatmap -->|"fills output buffer"| node_ffi_client

click node_generator_cli "https://github.com/rpendleton/battleship-rust/blob/main/src/bin/generator.rs"
click node_enumerator "https://github.com/rpendleton/battleship-rust/blob/main/src/bin/generator.rs"
click node_board_state "https://github.com/rpendleton/battleship-rust/blob/main/src/generator/board_state.rs"
click node_common_masks "https://github.com/rpendleton/battleship-rust/blob/main/src/generator/common_masks.rs"
click node_board_mask "https://github.com/rpendleton/battleship-rust/blob/main/src/generator/board_mask.rs"
click node_point "https://github.com/rpendleton/battleship-rust/blob/main/src/generator/point.rs"
click node_symmetries "https://github.com/rpendleton/battleship-rust/blob/main/src/generator/symmetries.rs"
click node_encoder "https://github.com/rpendleton/battleship-rust/blob/main/src/bin/encoder.rs"
click node_cli "https://github.com/rpendleton/battleship-rust/blob/main/src/main.rs"
click node_ffi "https://github.com/rpendleton/battleship-rust/blob/main/src/core/ffi.rs"
click node_reader "https://github.com/rpendleton/battleship-rust/blob/main/src/core/reader.rs"
click node_filter "https://github.com/rpendleton/battleship-rust/blob/main/src/core/filter.rs"
click node_rayon "https://github.com/rpendleton/battleship-rust/blob/main/src/core/filter.rs"

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_generator_cli,node_enumerator,node_raw_dataset,node_encoder,node_delta_dataset,node_zstd_tool,node_compressed_dataset,node_query_user,node_api_client,node_ffi_client toneBlue
class node_board_state,node_common_masks,node_board_mask,node_point,node_symmetries toneAmber
class node_reader,node_filter,node_rayon,node_heatmap toneMint
class node_cli,node_ffi toneRose
class node_generator_user toneIndigo
```

## Components

### Dataset generation

- [Generator CLI](https://github.com/rpendleton/battleship-rust/blob/main/src/bin/generator.rs): `src/bin/generator.rs`
- [Board enumeration](https://github.com/rpendleton/battleship-rust/blob/main/src/bin/generator.rs): `src/bin/generator.rs`
- **Raw board records**
- [Delta encoder](https://github.com/rpendleton/battleship-rust/blob/main/src/bin/encoder.rs): `src/bin/encoder.rs`
- **Delta records**
- **zstd compressor**
- **Compressed dataset**

### Board model

- [Placement state](https://github.com/rpendleton/battleship-rust/blob/main/src/generator/board_state.rs): `src/generator/board_state.rs`
- [Placement masks](https://github.com/rpendleton/battleship-rust/blob/main/src/generator/common_masks.rs): `src/generator/common_masks.rs`
- [Bitmask utilities](https://github.com/rpendleton/battleship-rust/blob/main/src/generator/board_mask.rs): `src/generator/board_mask.rs`
- [Board coordinates](https://github.com/rpendleton/battleship-rust/blob/main/src/generator/point.rs): `src/generator/point.rs`
- [Symmetry filter](https://github.com/rpendleton/battleship-rust/blob/main/src/generator/symmetries.rs): `src/generator/symmetries.rs`

### Query runtime

- [Dataset reader](https://github.com/rpendleton/battleship-rust/blob/main/src/core/reader.rs): `src/core/reader.rs`
- [Filter and count](https://github.com/rpendleton/battleship-rust/blob/main/src/core/filter.rs): `src/core/filter.rs`
- [Parallel counting](https://github.com/rpendleton/battleship-rust/blob/main/src/core/filter.rs): `src/core/filter.rs`
- **Cell count heatmap**

### User interfaces

- [Query CLI](https://github.com/rpendleton/battleship-rust/blob/main/src/main.rs): `src/main.rs`
- [C FFI wrapper](https://github.com/rpendleton/battleship-rust/blob/main/src/core/ffi.rs): `src/core/ffi.rs`

### Other components

- **Dataset operator**
- **Query client**
- **Rust API client**
- **Swift / iOS client**

## Connections

- Dataset operator → Generator CLI: runs
- Generator CLI → Board enumeration: starts enumeration
- Board enumeration → Placement state: places ships
- Placement state → Placement masks: gets placement masks
- Placement masks → Bitmask utilities: builds masks
- Placement state → Bitmask utilities: updates masks
- Board enumeration → Board coordinates: uses coordinates
- Generator CLI → Symmetry filter: filters canonical boards
- Generator CLI → Raw board records: writes records
- Raw board records → Delta encoder: streams records
- Delta encoder → Delta records: writes XOR deltas
- Delta records → zstd compressor: compresses
- zstd compressor → Compressed dataset: writes compressed data
- Query client → Query CLI: submits masks
- Query CLI → Dataset reader: opens dataset
- Query CLI → Filter and count: passes masks and boards
- Rust API client → Dataset reader: creates reader
- Rust API client → Filter and count: queries boards
- Swift / iOS client → C FFI wrapper: passes masks and path
- C FFI wrapper → Dataset reader: opens dataset
- C FFI wrapper → Filter and count: queries boards
- Compressed dataset → Dataset reader: streams records
- Dataset reader → zstd compressor: decodes when compressed
- Dataset reader → Filter and count: yields decoded boards
- Filter and count → Parallel counting: counts in parallel
- Filter and count → Cell count heatmap: returns cell counts
- Cell count heatmap → Query CLI: prints CSV
- Cell count heatmap → Swift / iOS client: fills output buffer