Architecture

CSha is one C++20 command-line application built by the root CMakeLists.txt.
The core uses OpenCV matrices; Cubiomes remains a bundled C dependency. Two
additional C++ libraries provide live transport and streamed Docker archives.

Entry point and dispatch

src/main.cpp
  └── csha::run_cli(argc, argv)             src/heler.cpp / src/heler.h
        ├── docker-image COMMAND          src/docker/cli.cpp
        ├── blob-streams COMMAND          src/streams/cli.cpp
        └── -M MODE                       legacy image/map option parser
              ├── CSha                    src/CSha.cpp
              ├── image-pair maps         src/image_pair.cpp
              └── PNG data URL I/O        src/image_url.cpp

main.cpp only forwards arguments and returns the helper's exit code.
heler.cpp owns usage text, option parsing, image I/O, and legacy mode dispatch.
The spelling heler is the filename used by this project. The Blob Streams and
Docker subcommands are selected before the legacy getopt_long parser and
receive their own argument slices.

src/all.cpp maps mode aliases and performs shared option validation. Mode-specific
work happens in CSha and the specialized modules. Keep new behavior in its
module rather than growing the entry-point wrapper.

Build targets

Target	Responsibility	Main dependencies
`csha`	Executable and CLI adapters	Internal C++ libraries
`csha_core`	Encrypted images, ZIP conversion, environment maps, seed metadata, image-pair keys, data URLs	Cubiomes, OpenCV, OpenSSL Crypto, zlib, libzip
`csha_encoder_module`	Shared `csha.encoder` interface from `src/crypto/encoder.ixx`	C++20 module toolchain
`csha_ciphers`	Authenticated envelopes and streaming cipher implementations	Crypto++, OpenSSL Crypto, `csha_encoder_module`
`cubiomes`	Minecraft biome generation	C compiler, threads, math library on Unix
`csha_blob_streams`	Transport-independent authenticated stream sessions	OpenSSL SSL and Crypto
`csha_docker_image`	Encrypted Docker-save archive PNG codec	OpenSSL Crypto, libpng, `csha_ciphers`
`csha_tests`	Core Catch2 tests	`csha_core`, Catch2
`csha_blob_tests`	Stream-session Catch2 tests	`csha_blob_streams`, Catch2

Only the csha executable is installed. The libraries are currently internal
CMake targets, not an installed SDK with exported package configuration. See
C++ API for an in-tree embedding example.

Shared encryption interface

src/crypto/encoder.ixx exports the C++20 module csha.encoder, including
Encoder, StreamingEncoder, cipher IDs, key types, and configuration.
make_encoder selects AES or one of ten added cipher choices;
make_stream_encoder supplies the bounded-memory Docker archive interface.
Legacy AES image formats remain supported. New authenticated envelopes carry
their cipher ID and key-derivation metadata. OpenSSL and Crypto++ supply the
cryptographic primitives. See Encryption algorithms.

Image and map pipeline

For an ordinary AES image, input bytes are encrypted, framed with an explicit
length, and packed into pixels. Decoding unpacks bytes and decrypts them.
CSha::encode_zip wraps archive bytes in Base64 before this path; decode_zip
reverses it. Image work is in memory and scales with payload size.

Environment-map generation encrypts payload data and embeds it into map pixels.
Seed-map generation uses Cubiomes to render a biome visualization and stores
seed metadata in a row. Reading seed metadata does not decrypt an environment
payload. src/map/seed_metadata.cpp centralizes current row layout and legacy
read compatibility.

Image-pair maps encrypt one payload with a random data key, then store two
independently wrapped copies of that key. Either credential image unlocks it.
Data URLs are an I/O wrapper around PNG bytes and do not alter encryption.
See Formats and keys for compatibility and capacity boundaries.

Network and Docker pipelines

The Blob Streams Session engine has no sockets. It consumes ordered encrypted
bytes and exposes encrypted/plaintext output queues. Its CLI adapter adds POSIX
sockets, stdin/stdout, polling, timeouts, and an optional paired HTTP CONNECT
relay. The relay forwards encrypted bytes without device private keys.

Docker commands resolve a local image reference to an immutable image ID,
save its archive, and stream it through the PNG codec. On recovery, authentication
and archive checks finish before Docker sees the restored archive. Private
temporary files keep large payloads off the in-memory image path. The CLI invokes
Docker with argument arrays; it does not build a shell command from these options.

Source layout

Path	Purpose
`src/crypto/`	AES primitives, pixel encoding/decoding, metadata, and helpers
`src/map/`	Seed conversions, Java-compatible random behavior, metadata layout
`src/streams/`	TLS session engine and live CLI adapter
`src/docker/`	Archive envelope, streaming PNG row codec, Docker CLI adapter
`third_party/cubiomes/`	Upstream C source and license
`tests/`	Core, transport, CLI, and optional real-Docker validation
`docs/`	Versioned documentation sources
`docs/site/`	Apidog page mapping, landing template, theme, and original assets

Cubiomes is compiled with signed-overflow wrapping (-fwrapv) to preserve its
upstream arithmetic assumptions. CMake selects library sources explicitly and
does not link upstream example entry points into the application.

Validation and contribution workflow

Build with CMake, run CTest, and exercise the changed CLI route. The 12
registered CTest groups cover the core API and CLI, cipher/module contracts, Blob
sessions and protocol boundaries, direct/relay process flows, Docker archives,
image-pair/data-URL integration, help, and version. See Testing. Core tests run serially where they share generated filenames.

For a new flag, update parsing, validation, usage output, this documentation,
and the relevant integration coverage. Preserve old file-format reads when
changing an encoder, and document any incompatibility for older binaries.
Build and test details are in Building and installation.

Configure with -DBUILD_TESTING=OFF to omit test targets and their Catch2/Python dependencies.

Architecture

Entry point and dispatch#

Build targets#

Shared encryption interface#

Image and map pipeline#

Network and Docker pipelines#

Source layout#