# ojitoss/bitack architecture

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

- Interactive diagram: https://gitdiagram.com/ojitoss/bitack
- Repository: https://github.com/ojitoss/bitack

## Overview

#### Purpose and Public API
Bitack is a Rust library for declaratively describing compact binary bit layouts, then serializing `u32` values into bytes and deserializing bytes back into values. The crate entry point is `src/lib.rs`; its public model centers on schemes and fields in `src/schemes.rs` and `src/fields.rs`.

#### Scheme Model
`BitScheme` represents an ordered binary layout composed of `BitField` entries. Fields encode both width and behavior: value-consuming fields such as `Next`, structural gaps such as `Skip`, and prefix-oriented encodings such as leading-one/leading-zero fields. This declarative layer is defined across:
- `src/schemes.rs`
- `src/fields.rs`

A scheme is the boundary between caller-provided logical values and the library’s bit-level representation.

#### Write Pipeline
Writing begins with a `BitScheme` plus a vector of values. The scheme traverses fields in layout order; only fields that represent stored values consume input elements, while skipped/reserved fields emit ignored or padded bits. Bit-level emission and field-specific encoding are implemented in:
- `src/schemes/writter.rs`
- `src/fields.rs`
- `src/utils/bitmask.rs`

The result is a byte-oriented buffer suitable for external sinks such as files. Output is padded/aligned to four-byte blocks, and internal field operations are constrained to `u32`.

#### Read Pipeline
Reading accepts a byte buffer and applies the same ordered scheme to recover logical field values. The reader interprets bit positions, ignores `Skip` regions, and decodes the field encoding rules before returning values in scheme order. The decoding stage is isolated in:
- `src/schemes/reader.rs`
- `src/schemes.rs`
- `src/fields.rs`

This makes the scheme itself the shared contract between producer and consumer; no file, network, or persistence runtime is built into the crate.

#### Bit Manipulation Foundation
Low-level masks, bit extraction, and related primitives support both directions of conversion. Shared abstraction traits and utilities likely separate reusable bit operations from scheme traversal:
- `src/utils.rs`
- `src/utils/bitmask.rs`
- `src/utils/traits.rs`

These utilities are an internal implementation boundary: callers describe fields and invoke scheme read/write APIs rather than manually shifting and masking bits.

#### Runtime and Integration Boundary
The repository is a Cargo Rust library (`Cargo.toml`) with no service runtime or external infrastructure dependency shown. Consumers supply input values and choose output destinations; the file-system integration shown by the project is consumer-side usage:
- `examples/fs.rs`
- `examples/fs.rs`

The primary external integration is therefore any Rust application that imports the crate, writes returned bytes to a transport/storage system, and later feeds bytes back to the same compatible scheme.

Main entry points: [`src/lib.rs`](https://github.com/ojitoss/bitack/blob/main/src/lib.rs) (Crate entry point), [`src/schemes.rs`](https://github.com/ojitoss/bitack/blob/main/src/schemes.rs) (BitScheme), [`src/schemes/writter.rs`](https://github.com/ojitoss/bitack/blob/main/src/schemes/writter.rs) (Scheme writer), [`src/schemes/reader.rs`](https://github.com/ojitoss/bitack/blob/main/src/schemes/reader.rs) (Scheme reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_lib["Crate entry point<br/>Rust library API<br/>[lib.rs]"]
  node_scheme["BitScheme<br/>layout model<br/>[schemes.rs]"]
  node_fields["BitField variants<br/>field model<br/>[fields.rs]"]
end

subgraph group_codec["Scheme Codec"]
  node_writer["Scheme writer<br/>encoding pipeline<br/>[writter.rs]"]
  node_reader["Scheme reader<br/>decoding pipeline<br/>[reader.rs]"]
  node_byte_buffer["Byte buffer<br/>encoded data"]
end

subgraph group_foundation["Bit Foundation"]
  node_utils["Shared utilities<br/>bit abstractions<br/>[utils.rs]"]
  node_bitmask["Bit masks<br/>bit primitives<br/>[bitmask.rs]"]
  node_traits["Utility traits<br/>shared abstractions<br/>[traits.rs]"]
end

node_consumer(("Rust consumer<br/>external application"))
node_filesystem_example["File I/O usage<br/>consumer example<br/>[fs.rs]"]
node_cargo["Cargo package<br/>Rust crate manifest<br/>[Cargo.toml]"]

node_consumer -->|"imports"| node_lib
node_lib -->|"exposes"| node_scheme
node_lib -->|"exposes"| node_fields
node_scheme -->|"orders"| node_fields
node_scheme -->|"writes with"| node_writer
node_scheme -->|"reads with"| node_reader
node_writer -->|"encodes rules"| node_fields
node_reader -->|"decodes rules"| node_fields
node_writer -->|"produces"| node_byte_buffer
node_byte_buffer -->|"feeds"| node_reader
node_writer -->|"uses"| node_bitmask
node_reader -->|"uses"| node_bitmask
node_utils -->|"contains"| node_bitmask
node_utils -->|"contains"| node_traits
node_filesystem_example -->|"uses"| node_lib
node_filesystem_example -->|"persists"| node_byte_buffer
node_cargo -->|"packages"| node_lib

click node_lib "https://github.com/ojitoss/bitack/blob/main/src/lib.rs"
click node_scheme "https://github.com/ojitoss/bitack/blob/main/src/schemes.rs"
click node_fields "https://github.com/ojitoss/bitack/blob/main/src/fields.rs"
click node_writer "https://github.com/ojitoss/bitack/blob/main/src/schemes/writter.rs"
click node_reader "https://github.com/ojitoss/bitack/blob/main/src/schemes/reader.rs"
click node_utils "https://github.com/ojitoss/bitack/blob/main/src/utils.rs"
click node_bitmask "https://github.com/ojitoss/bitack/blob/main/src/utils/bitmask.rs"
click node_traits "https://github.com/ojitoss/bitack/blob/main/src/utils/traits.rs"
click node_filesystem_example "https://github.com/ojitoss/bitack/blob/main/examples/fs.rs"
click node_cargo "https://github.com/ojitoss/bitack/blob/main/Cargo.toml"

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_lib,node_scheme,node_fields toneBlue
class node_writer,node_reader,node_byte_buffer toneAmber
class node_utils,node_bitmask,node_traits toneMint
class node_consumer,node_filesystem_example,node_cargo toneNeutral
```

## Components

### Public API

- [Crate entry point](https://github.com/ojitoss/bitack/blob/main/src/lib.rs): Rust library API · `src/lib.rs`
- [BitScheme](https://github.com/ojitoss/bitack/blob/main/src/schemes.rs): layout model · Ordered shared contract for encoding and decoding. · `src/schemes.rs`
- [BitField variants](https://github.com/ojitoss/bitack/blob/main/src/fields.rs): field model · Defines value, skip, and prefix-oriented field behavior. · `src/fields.rs`

### Scheme Codec

- [Scheme writer](https://github.com/ojitoss/bitack/blob/main/src/schemes/writter.rs): encoding pipeline · Traverses fields and emits encoded bits into padded bytes. · `src/schemes/writter.rs`
- [Scheme reader](https://github.com/ojitoss/bitack/blob/main/src/schemes/reader.rs): decoding pipeline · Traverses fields and recovers logical values from bytes. · `src/schemes/reader.rs`
- **Byte buffer**: encoded data · Four-byte-aligned serialized output and reader input.

### Bit Foundation

- [Shared utilities](https://github.com/ojitoss/bitack/blob/main/src/utils.rs): bit abstractions · `src/utils.rs`
- [Bit masks](https://github.com/ojitoss/bitack/blob/main/src/utils/bitmask.rs): bit primitives · Masks and extracts u32 bit ranges. · `src/utils/bitmask.rs`
- [Utility traits](https://github.com/ojitoss/bitack/blob/main/src/utils/traits.rs): shared abstractions · `src/utils/traits.rs`

### Other components

- **Rust consumer**: external application · Supplies values, stores bytes, and later provides bytes for decoding.
- [File I/O usage](https://github.com/ojitoss/bitack/blob/main/examples/fs.rs): consumer example · Demonstrates consumer-side persistence of returned bytes. · `examples/fs.rs`
- [Cargo package](https://github.com/ojitoss/bitack/blob/main/Cargo.toml): Rust crate manifest · `Cargo.toml`

## Connections

- Rust consumer → Crate entry point: imports
- Crate entry point → BitScheme: exposes
- Crate entry point → BitField variants: exposes
- BitScheme → BitField variants: orders
- BitScheme → Scheme writer: writes with
- BitScheme → Scheme reader: reads with
- Scheme writer → BitField variants: encodes rules
- Scheme reader → BitField variants: decodes rules
- Scheme writer → Byte buffer: produces
- Byte buffer → Scheme reader: feeds
- Scheme writer → Bit masks: uses
- Scheme reader → Bit masks: uses
- Shared utilities → Bit masks: contains
- Shared utilities → Utility traits: contains
- File I/O usage → Crate entry point: uses
- File I/O usage → Byte buffer: persists
- Cargo package → Crate entry point: packages