# chuck-ie/lamellae architecture

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

- Interactive diagram: https://gitdiagram.com/chuck-ie/lamellae
- Repository: https://github.com/chuck-ie/lamellae

## Overview

lamellae is a Rust bounded SPSC queue whose defining behavior is cache-line-granular publication: writes remain producer-owned until a line is advanced or explicitly flushed. Users create paired endpoints with `channel!`, send or batch-fill data (including a zero-copy closure API), publish it, then receive individual or batched data. The graph captures that runtime path and the ring-buffer, cache-line, and interruption-tracking layers supported by sampled source; zero-copy and documented constraints are included, while unsampled internal wiring is omitted.

Main entry points: [`src/buffer.rs`](https://github.com/chuck-ie/lamellae/blob/main/src/buffer.rs) (Ring buffer), [`src/producer.rs`](https://github.com/chuck-ie/lamellae/blob/main/src/producer.rs) (Producer endpoint), [`src/consumer.rs`](https://github.com/chuck-ie/lamellae/blob/main/src/consumer.rs) (Consumer endpoint), [`src/lib.rs`](https://github.com/chuck-ie/lamellae/blob/main/src/lib.rs) (Channel macro)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Queue API"]
  node_channel["Channel macro<br/>[lib.rs]"]
  node_producer["Producer endpoint<br/>[producer.rs]"]
  node_consumer["Consumer endpoint<br/>[consumer.rs]"]
end

subgraph group_storage["Buffer and layout"]
  node_buffer["Ring buffer<br/>[buffer.rs]"]
  node_cacheline["Cache-line slots<br/>[wrapper.rs]"]
end

subgraph group_sync["Publication synchronization"]
  node_interruptions["Interruption tracker"]
  node_spinlock["Backoff helper<br/>[spinlock.rs]"]
end

node_user(("Queue user"))

node_user -->|"creates channel"| node_channel
node_channel -->|"allocates endpoints"| node_buffer
node_buffer -->|"returns endpoint"| node_producer
node_buffer -->|"returns endpoint"| node_consumer
node_producer -->|"writes and publishes"| node_buffer
node_consumer -->|"reads published data"| node_buffer
node_buffer -->|"stores slots"| node_cacheline
node_producer -->|"records flush boundary"| node_interruptions
node_consumer -->|"reads boundaries"| node_interruptions

click node_channel "https://github.com/chuck-ie/lamellae/blob/main/src/lib.rs"
click node_producer "https://github.com/chuck-ie/lamellae/blob/main/src/producer.rs"
click node_consumer "https://github.com/chuck-ie/lamellae/blob/main/src/consumer.rs"
click node_buffer "https://github.com/chuck-ie/lamellae/blob/main/src/buffer.rs"
click node_cacheline "https://github.com/chuck-ie/lamellae/blob/main/src/wrapper.rs"
click node_interruptions "https://github.com/chuck-ie/lamellae/blob/main/src/interruption_tracker.rs"
click node_spinlock "https://github.com/chuck-ie/lamellae/blob/main/src/spinlock.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_channel,node_producer,node_consumer toneBlue
class node_buffer,node_cacheline toneAmber
class node_interruptions,node_spinlock toneMint
class node_user toneRose
```

## Components

### Queue API

- [Channel macro](https://github.com/chuck-ie/lamellae/blob/main/src/lib.rs): `src/lib.rs`
- [Producer endpoint](https://github.com/chuck-ie/lamellae/blob/main/src/producer.rs): `src/producer.rs`
- [Consumer endpoint](https://github.com/chuck-ie/lamellae/blob/main/src/consumer.rs): `src/consumer.rs`

### Buffer and layout

- [Ring buffer](https://github.com/chuck-ie/lamellae/blob/main/src/buffer.rs): `src/buffer.rs`
- [Cache-line slots](https://github.com/chuck-ie/lamellae/blob/main/src/wrapper.rs): `src/wrapper.rs`

### Publication synchronization

- [Interruption tracker](https://github.com/chuck-ie/lamellae/blob/main/src/interruption_tracker.rs): `src/interruption_tracker.rs`
- [Backoff helper](https://github.com/chuck-ie/lamellae/blob/main/src/spinlock.rs): `src/spinlock.rs`

### Other components

- **Queue user**

## Connections

- Queue user → Channel macro: creates channel
- Channel macro → Ring buffer: allocates endpoints
- Ring buffer → Producer endpoint: returns endpoint
- Ring buffer → Consumer endpoint: returns endpoint
- Producer endpoint → Ring buffer: writes and publishes
- Consumer endpoint → Ring buffer: reads published data
- Ring buffer → Cache-line slots: stores slots
- Producer endpoint → Interruption tracker: records flush boundary
- Consumer endpoint → Interruption tracker: reads boundaries