# bee-san/ciphey architecture

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

- Interactive diagram: https://gitdiagram.com/bee-san/ciphey
- Repository: https://github.com/bee-san/ciphey

## Overview

Ciphey is a library-first tool that searches for decoding paths and identifies likely plaintext; the CLI is one interface to the library. Its principal workflow accepts text, selects decoders, runs them under a search strategy, checks candidate output, and presents results. The repository also documents timeout handling, configurable and enhanced plaintext detection, multilevel decoding, statistics, and custom themes. Some relationships and capability implementations are based on README or source-index references; unsampled code is not treated as inspected.

Main entry points: [`src/lib.rs`](https://github.com/bee-san/ciphey/blob/master/src/lib.rs) (Library API), [`src/searchers/astar.rs`](https://github.com/bee-san/ciphey/blob/master/src/searchers/astar.rs) (A* search), [`src/checkers/athena.rs`](https://github.com/bee-san/ciphey/blob/master/src/checkers/athena.rs) (Plaintext detection), [`src/cli/mod.rs`](https://github.com/bee-san/ciphey/blob/master/src/cli/mod.rs) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_cli["CLI<br/>[mod.rs]"]
  node_input["Input parsing<br/>[mod.rs]"]
  node_api_input["Library input"]
  node_output["CLI output<br/>[mod.rs]"]
end

subgraph group_orchestration["Decode orchestration"]
  node_library["Library API<br/>[lib.rs]"]
  node_search["A* search<br/>[astar.rs]"]
  node_search_helpers["Search helpers"]
  node_filter["Decoder selection<br/>[mod.rs]"]
end

subgraph group_engines["Decoding and detection"]
  node_decoders["Decoder implementations"]
  node_decoder_contract["Decoder contract<br/>[interface.rs]"]
  node_vigenere["Vigenère decoder"]
  node_crack_results["Decode results<br/>[crack_results.rs]"]
  node_plaintext_checks["Plaintext detection<br/>[athena.rs]"]
  node_checker_types["Checker types<br/>[checker_type.rs]"]
end

subgraph group_state["Configuration and state"]
  node_config["Runtime configuration<br/>[mod.rs]"]
  node_timer["Timeout handling<br/>[mod.rs]"]
  node_stats_db[("Statistics database<br/>[database.rs]")]
  node_plaintext_store[("Collected plaintexts")]
end

node_user(("User or API client"))

node_user -->|"invokes"| node_cli
node_cli -->|"parses input"| node_input
node_input -->|"builds input"| node_api_input
node_cli -->|"uses library"| node_library
node_library -->|"accepts input"| node_api_input
node_library -->|"starts search"| node_search
node_library -->|"uses settings"| node_config
node_search -->|"gets decoders"| node_filter
node_search -->|"uses helpers"| node_search_helpers
node_search -->|"checks candidates"| node_plaintext_checks
node_filter -->|"selects decoders"| node_decoders
node_filter -->|"runs candidates"| node_plaintext_checks
node_decoders -->|"implements"| node_decoder_contract
node_vigenere -->|"implements"| node_decoder_contract
node_decoders -->|"checks output"| node_plaintext_checks
node_decoders -->|"returns results"| node_crack_results
node_plaintext_checks -->|"returns check result"| node_checker_types
node_cli -->|"prints results"| node_output
node_output -->|"reads theme"| node_config
node_search -.->|"uses timeout"| node_timer
node_plaintext_checks -.->|"collects results"| node_plaintext_store
node_output -->|"reads collected results"| node_plaintext_store
node_library -.->|"records statistics"| node_stats_db

click node_cli "https://github.com/bee-san/ciphey/blob/master/src/cli/mod.rs"
click node_input "https://github.com/bee-san/ciphey/blob/master/src/cli_input_parser/mod.rs"
click node_api_input "https://github.com/bee-san/ciphey/blob/master/src/api_library_input_struct.rs"
click node_output "https://github.com/bee-san/ciphey/blob/master/src/cli_pretty_printing/mod.rs"
click node_library "https://github.com/bee-san/ciphey/blob/master/src/lib.rs"
click node_search "https://github.com/bee-san/ciphey/blob/master/src/searchers/astar.rs"
click node_search_helpers "https://github.com/bee-san/ciphey/blob/master/src/searchers/helper_functions.rs"
click node_filter "https://github.com/bee-san/ciphey/blob/master/src/filtration_system/mod.rs"
click node_decoders "https://github.com/bee-san/ciphey/tree/master/src/decoders"
click node_decoder_contract "https://github.com/bee-san/ciphey/blob/master/src/decoders/interface.rs"
click node_vigenere "https://github.com/bee-san/ciphey/blob/master/src/decoders/vigenere_decoder.rs"
click node_crack_results "https://github.com/bee-san/ciphey/blob/master/src/decoders/crack_results.rs"
click node_plaintext_checks "https://github.com/bee-san/ciphey/blob/master/src/checkers/athena.rs"
click node_checker_types "https://github.com/bee-san/ciphey/blob/master/src/checkers/checker_type.rs"
click node_config "https://github.com/bee-san/ciphey/blob/master/src/config/mod.rs"
click node_timer "https://github.com/bee-san/ciphey/blob/master/src/timer/mod.rs"
click node_stats_db "https://github.com/bee-san/ciphey/blob/master/src/storage/database.rs"
click node_plaintext_store "https://github.com/bee-san/ciphey/blob/master/src/storage/wait_athena_storage.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_cli,node_input,node_api_input,node_output,node_user toneBlue
class node_library,node_search,node_search_helpers,node_filter toneAmber
class node_decoders,node_decoder_contract,node_vigenere,node_crack_results,node_plaintext_checks,node_checker_types toneMint
class node_config,node_timer,node_stats_db,node_plaintext_store toneRose
```

## Components

### User interfaces

- [CLI](https://github.com/bee-san/ciphey/blob/master/src/cli/mod.rs): `src/cli/mod.rs`
- [Input parsing](https://github.com/bee-san/ciphey/blob/master/src/cli_input_parser/mod.rs): `src/cli_input_parser/mod.rs`
- [Library input](https://github.com/bee-san/ciphey/blob/master/src/api_library_input_struct.rs): `src/api_library_input_struct.rs`
- [CLI output](https://github.com/bee-san/ciphey/blob/master/src/cli_pretty_printing/mod.rs): `src/cli_pretty_printing/mod.rs`

### Decode orchestration

- [Library API](https://github.com/bee-san/ciphey/blob/master/src/lib.rs): `src/lib.rs`
- [A* search](https://github.com/bee-san/ciphey/blob/master/src/searchers/astar.rs): `src/searchers/astar.rs`
- [Search helpers](https://github.com/bee-san/ciphey/blob/master/src/searchers/helper_functions.rs): `src/searchers/helper_functions.rs`
- [Decoder selection](https://github.com/bee-san/ciphey/blob/master/src/filtration_system/mod.rs): `src/filtration_system/mod.rs`

### Decoding and detection

- [Decoder implementations](https://github.com/bee-san/ciphey/tree/master/src/decoders): `src/decoders`
- [Decoder contract](https://github.com/bee-san/ciphey/blob/master/src/decoders/interface.rs): `src/decoders/interface.rs`
- [Vigenère decoder](https://github.com/bee-san/ciphey/blob/master/src/decoders/vigenere_decoder.rs): `src/decoders/vigenere_decoder.rs`
- [Decode results](https://github.com/bee-san/ciphey/blob/master/src/decoders/crack_results.rs): `src/decoders/crack_results.rs`
- [Plaintext detection](https://github.com/bee-san/ciphey/blob/master/src/checkers/athena.rs): `src/checkers/athena.rs`
- [Checker types](https://github.com/bee-san/ciphey/blob/master/src/checkers/checker_type.rs): `src/checkers/checker_type.rs`

### Configuration and state

- [Runtime configuration](https://github.com/bee-san/ciphey/blob/master/src/config/mod.rs): `src/config/mod.rs`
- [Timeout handling](https://github.com/bee-san/ciphey/blob/master/src/timer/mod.rs): `src/timer/mod.rs`
- [Statistics database](https://github.com/bee-san/ciphey/blob/master/src/storage/database.rs): `src/storage/database.rs`
- [Collected plaintexts](https://github.com/bee-san/ciphey/blob/master/src/storage/wait_athena_storage.rs): `src/storage/wait_athena_storage.rs`

### Other components

- **User or API client**

## Connections

- User or API client → CLI: invokes
- CLI → Input parsing: parses input (evidence: `src/cli_input_parser/mod.rs`)
- Input parsing → Library input: builds input (evidence: `src/cli_input_parser/mod.rs`)
- CLI → Library API: uses library (evidence: `src/lib.rs`)
- Library API → Library input: accepts input (evidence: `src/lib.rs`)
- Library API → A* search: starts search (evidence: `src/lib.rs`)
- Library API → Runtime configuration: uses settings (evidence: `src/lib.rs`)
- A* search → Decoder selection: gets decoders (evidence: `src/searchers/mod.rs`)
- A* search → Search helpers: uses helpers (evidence: `src/searchers/mod.rs`)
- A* search → Plaintext detection: checks candidates (evidence: `src/searchers/mod.rs`)
- Decoder selection → Decoder implementations: selects decoders (evidence: `src/filtration_system/mod.rs`)
- Decoder selection → Plaintext detection: runs candidates (evidence: `src/filtration_system/mod.rs`)
- Decoder implementations → Decoder contract: implements (evidence: `src/decoders/mod.rs`)
- Vigenère decoder → Decoder contract: implements (evidence: `src/decoders/vigenere_decoder.rs`)
- Decoder implementations → Plaintext detection: checks output (evidence: `src/decoders/a1z26_decoder.rs`)
- Decoder implementations → Decode results: returns results (evidence: `src/decoders/interface.rs`)
- Plaintext detection → Checker types: returns check result (evidence: `src/checkers/athena.rs`)
- CLI → CLI output: prints results (evidence: `src/cli/mod.rs`)
- CLI output → Runtime configuration: reads theme (evidence: `src/cli_pretty_printing/mod.rs`)
- A* search → Timeout handling: uses timeout
- Plaintext detection → Collected plaintexts: collects results
- CLI output → Collected plaintexts: reads collected results (evidence: `src/cli_pretty_printing/mod.rs`)
- Library API → Statistics database: records statistics (evidence: `src/lib.rs`)