# envelo Architecture
`envelo` keeps a message's creation-time fields, body, and per-route metadata in one generic value. The crate exports only `Envelo<Header, Payload, Extension>` from `src/envelo.rs`, is dependency-free, and is built with `#![no_std]`.
## Design goals
- One predictable shape; easy to integrate with any transport or storage layer.
- Separation of concerns: immutable creation-time data in `Header`, hop-local context in `Extension`.
- Minimal API surface: construction, immutable/mutable accessors, `into_parts`, and `From<(H, P, E)>` to wrap tuples.
- Portable: zero dependencies and `#![no_std]` with no feature flags.
## Type breakdown
```
Envelo<Header, Payload, Extension>
```
- `Header`: creation-time fields decided up front (source IDs, timestamps, schema versions, initial routing hints). Treat as read-only; rebuild the envelope if it changes.
- `Payload`: the body you route or process. If its type or content changes, create a new envelope to keep intent explicit.
- `Extension`: per-route metadata that can be swapped or mutated as the value moves between stages.
- `into_parts`: consumes the envelope and yields `(Header, Payload, Extension)` for serialization, storage, or handoff.
- `From<(H, P, E)>`: converts a tuple into an envelope; the reverse direction stays explicit via `into_parts` to avoid ambiguity.
## Mutability guidelines
- Prefer cloning and rebuilding to mutate `Header`, so provenance remains clear.
- `Payload` updates are clearer as new envelopes, especially when changing types.
- `Extension` is intended to change in place; use `extension_mut()` or replace it for the next hop.
- `header_mut` and `payload_mut` exist for flexibility; enforce any invariants inside your types (e.g., private fields, setters with validation) and prefer rebuilding when that keeps intent clearer.
## Extension patterns
- Routing hints per hop: start with an empty type (e.g., `()`) and attach a `RouteMeta` when a stage needs it by rebuilding `Envelo<_, _, RouteMeta>`.
- Shared tracing/logging state in `std` contexts: store interior mutable data such as `Arc<RwLock<T>>` or `dashmap::DashMap<K, V>`.
- Dynamic attachments: keep a `TypeId`-keyed map (e.g., `HashMap<TypeId, Box<dyn Any>>` or a dashmap variant) to add and remove heterogeneous metadata.
## File layout
- `src/envelo.rs`: struct definition, accessors, `into_parts`, and tuple conversion.
- `src/lib.rs`: `#![no_std]` crate root re-exporting `Envelo`.