# zhangjiayin/truefix architecture

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

- Interactive diagram: https://gitdiagram.com/zhangjiayin/truefix
- Repository: https://github.com/zhangjiayin/truefix

## Overview

1. **Overall shape**
   - This is a Rust workspace for a FIX protocol engine, organized as a set of layered crates plus conformance/test assets.
   - The main runtime path is: configuration → engine facade → transport/session orchestration → FIX codec/dictionary validation → storage/logging → application callbacks.

2. **`truefix` facade**
   - The top-level `truefix` crate is the public entry point.
   - It re-exports the main API surface, defines the `Application` trait and `MessageCracker`, and exposes `Engine::start` for one-shot startup from a `.cfg` file.
   - This crate is the boundary that application code typically depends on.

3. **Protocol core: `truefix-core`**
   - `truefix-core` contains the low-level FIX message model and wire codec: fields, field maps, repeating groups, messages, tags, framing, encode/decode, checksum/body-length handling, and typed protocol errors.
   - It is the lowest protocol layer and does not know about session state, transport sockets, or persistence.
   - All higher layers depend on it for parsing and rendering FIX messages.

4. **Dictionary system: `truefix-dict`**
   - `truefix-dict` is the dictionary and codegen layer.
   - It has a dual-track architecture: build-time generation of typed Rust messages/enums/groups, and runtime `DataDictionary` validation from the same normalized source.
   - It also includes dictionary parsing, validation, FIX repository/Orchestra conversion, hashing, and a CLI used by both build.rs and users.
   - This crate is the bridge between protocol syntax and typed domain models.

5. **Session engine: `truefix-session`**
   - `truefix-session` implements the FIX session state machine and protocol behavior: logon/logout, heartbeat timing, sequence management, resend/gap-fill handling, schedule windows, reset semantics, and reverse-route behavior.
   - It also defines admin/application behavior boundaries and typed callback outcomes used by `Application`.
   - This is where session correctness lives; it consumes decoded messages and emits session actions/responses.

6. **Transport layer: `truefix-transport`**
   - `truefix-transport` owns the network-facing initiator/acceptor machinery.
   - It handles multi-session and dynamic sessions, reconnect/failover, socket options, TLS/mTLS via rustls, proxy support, PROXY protocol, synchronous write behavior, and bounded inbound backpressure.
   - Its job is to move bytes to/from the session engine while enforcing network and connection policies.

7. **Persistence layer: `truefix-store`**
   - `truefix-store` abstracts message/session persistence behind a `MessageStore`-style boundary.
   - Backends include memory, file-based storage, cached file storage, SQL, MSSQL, Redb, MongoDB, and no-op.
   - The store is used by session recovery/resend flows to survive restarts and reconstruct sequence state.

8. **Logging layer: `truefix-log`**
   - `truefix-log` provides the logging side of engine observability and audit trails.
   - It supports screen, file, tracing, composite logs, plus backend variants aligned with store technology choices such as SQL, MSSQL, Redb, and MongoDB.
   - The log layer is separate from the store but follows the same persistence/backing pattern, so engines can pair a store backend with a log backend.

9. **Configuration and wiring: `truefix-config`**
   - `truefix-config` parses `.cfg` files into `SessionSettings`, performs interpolation/resolution, and maps config keys to engine/session/store/log/transport behavior.
   - This crate is the main wiring boundary between declarative deployment config and runtime objects.
   - The README shows that `Engine::start` consumes these resolved settings to assemble the full engine without extra application code.

10. **End-to-end data flow**
   - Inbound: socket bytes enter `truefix-transport`, are framed and decoded by `truefix-core`, validated/typed by `truefix-dict`, then processed by `truefix-session`, which consults store/log state and invokes `Application` callbacks when needed.
   - Outbound: `Application` may produce or modify messages, `truefix-session` applies session rules and sequence handling, `truefix-dict`/`truefix-core` render them, `truefix-transport` sends them, and store/log capture the session state and audit trail.
   - Recovery/resend paths loop through store access to replay prior messages and preserve session continuity.

11. **Build-time vs runtime boundaries**
   - Dictionary code generation happens at build time and is backed by checked-in normalized source plus conversion tooling.
   - Runtime dictionary validation is separate, but the two are intentionally kept in sync by sharing the same normalized input and hash checks.
   - This split is important for the diagram: one path produces typed Rust artifacts, the other validates live FIX traffic.

12. **Testing, conformance, and release gating**
   - `truefix-at` is the acceptance-test crate and acts as the release gate; it ports FIX conformance scenarios across multiple FIX versions.
   - The workspace also contains extensive unit/integration tests per crate, benchmarks for core/session performance, and CI workflows that exercise formatting, linting, tests, service-backed storage, and dictionary tooling.
   - For architecture diagrams, this is the quality-assurance boundary around the engine.

13. **Examples and operational docs**
   - `crates/truefix/examples/` contains runnable sample programs showing how the engine is embedded in real applications.
   - The `specs/` and `docs/` directories are not runtime components, but they are important design artifacts: they define contracts, roadmaps, and parity goals that the codebase is built against.

Main entry points: [`crates/truefix-session/src/lib.rs`](https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-session/src/lib.rs) (Session), [`crates/truefix-dict/src/lib.rs`](https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-dict/src/lib.rs) (Dictionary), [`crates/truefix-config/src/lib.rs`](https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-config/src/lib.rs) (Config), [`crates/truefix-transport/src/lib.rs`](https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-transport/src/lib.rs) (Transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime crates"]
  node_truefix["truefix<br/>public facade<br/>[lib.rs]"]
  node_config["Config<br/>cfg wiring<br/>[lib.rs]"]
  node_session["Session<br/>state machine<br/>[lib.rs]"]
  node_transport["Transport<br/>network I/O<br/>[lib.rs]"]
  node_core["Core codec<br/>FIX wire codec<br/>[lib.rs]"]
  node_dict["Dictionary<br/>typed protocol<br/>[lib.rs]"]
  node_store[("Store<br/>persistence<br/>[lib.rs]")]
  node_log[("Log<br/>[lib.rs]")]
  node_application["Application<br/>callback API<br/>[lib.rs]"]
  node_buildgen["Codegen<br/>build-time gen<br/>[build.rs]"]
  node_cli["Dict CLI<br/>tooling<br/>[truefix-dict.rs]"]
end

subgraph group_quality["Quality gate"]
  node_at["AT suite<br/>acceptance tests<br/>[lib.rs]"]
  node_examples["Examples<br/>sample apps<br/>[banzai.rs]"]
  node_specs["Specs<br/>design contracts<br/>[spec.md]"]
  node_docs["Docs<br/>[roadmap.md]"]
end

node_truefix -->|"loads settings"| node_config
node_truefix -->|"starts engine"| node_session
node_truefix -->|"exports API"| node_application
node_config -->|"maps network"| node_transport
node_config -->|"maps session"| node_session
node_config -->|"maps store"| node_store
node_config -->|"maps log"| node_log
node_session -->|"uses codec"| node_core
node_session -->|"validates typed"| node_dict
node_session -->|"recovers state"| node_store
node_session -->|"audits state"| node_log
node_session -->|"invokes callbacks"| node_application
node_transport -->|"delivers bytes"| node_session
node_transport -->|"frames messages"| node_core
node_transport -->|"checks groups"| node_dict
node_dict -->|"builds protocol"| node_core
node_buildgen -->|"generates types"| node_dict
node_cli -->|"parses source"| node_dict
node_at -->|"gates parity"| node_dict
node_at -->|"gates session"| node_session
node_at -->|"gates transport"| node_transport
node_examples -->|"show usage"| node_truefix
node_specs -.->|"defines target"| node_truefix
node_docs -.->|"tracks parity"| node_at

click node_truefix "https://github.com/zhangjiayin/truefix/blob/main/crates/truefix/src/lib.rs"
click node_config "https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-config/src/lib.rs"
click node_session "https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-session/src/lib.rs"
click node_transport "https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-transport/src/lib.rs"
click node_core "https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-core/src/lib.rs"
click node_dict "https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-dict/src/lib.rs"
click node_store "https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-store/src/lib.rs"
click node_log "https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-log/src/lib.rs"
click node_application "https://github.com/zhangjiayin/truefix/blob/main/crates/truefix/src/lib.rs"
click node_buildgen "https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-dict/build.rs"
click node_cli "https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-dict/src/bin/truefix-dict.rs"
click node_at "https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-at/src/lib.rs"
click node_examples "https://github.com/zhangjiayin/truefix/blob/main/crates/truefix/examples/banzai.rs"
click node_specs "https://github.com/zhangjiayin/truefix/blob/main/specs/001-fix-engine-parity/spec.md"
click node_docs "https://github.com/zhangjiayin/truefix/blob/main/docs/roadmap.md"

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_truefix,node_config,node_session,node_transport,node_core,node_dict,node_store,node_log,node_application,node_buildgen,node_cli toneBlue
class node_at,node_examples,node_specs,node_docs toneAmber
```

## Components

### Runtime crates

Core engine layers that assemble, validate, move, and persist FIX traffic.

- [truefix](https://github.com/zhangjiayin/truefix/blob/main/crates/truefix/src/lib.rs): public facade · Top-level API boundary and engine entry point for application code. · `crates/truefix/src/lib.rs`
- [Config](https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-config/src/lib.rs): cfg wiring · Parses deployment config and resolves runtime settings. · `crates/truefix-config/src/lib.rs`
- [Session](https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-session/src/lib.rs): state machine · Implements FIX session behavior, sequencing, recovery, and callback boundaries. · `crates/truefix-session/src/lib.rs`
- [Transport](https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-transport/src/lib.rs): network I/O · Initiator/acceptor network layer with reconnect, TLS, proxy, and backpressure policies. · `crates/truefix-transport/src/lib.rs`
- [Core codec](https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-core/src/lib.rs): FIX wire codec · Low-level FIX message model, framing, and encode/decode primitives. · `crates/truefix-core/src/lib.rs`
- [Dictionary](https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-dict/src/lib.rs): typed protocol · Dictionary parsing, validation, hashing, and code generation from normalized FIX sources. · `crates/truefix-dict/src/lib.rs`
- [Store](https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-store/src/lib.rs): persistence · Message and session persistence backends used for recovery and resend flows. · `crates/truefix-store/src/lib.rs`
- [Log](https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-log/src/lib.rs): audit logging · Observability and audit backends for screen, file, tracing, and durable sinks. · `crates/truefix-log/src/lib.rs`
- [Application](https://github.com/zhangjiayin/truefix/blob/main/crates/truefix/src/lib.rs): callback API · Application-facing trait boundary and message cracking hooks exposed by the facade. · `crates/truefix/src/lib.rs`
- [Codegen](https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-dict/build.rs): build-time gen · Build-time typed artifact generation from the FIX dictionary source. · `crates/truefix-dict/build.rs`
- [Dict CLI](https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-dict/src/bin/truefix-dict.rs): tooling · Command-line dictionary tool used by build scripts and users. · `crates/truefix-dict/src/bin/truefix-dict.rs`

### Quality gate

Acceptance tests, examples, and design contracts that constrain the runtime.

- [AT suite](https://github.com/zhangjiayin/truefix/blob/main/crates/truefix-at/src/lib.rs): acceptance tests · Conformance and release-gating scenarios across FIX versions. · `crates/truefix-at/src/lib.rs`
- [Examples](https://github.com/zhangjiayin/truefix/blob/main/crates/truefix/examples/banzai.rs): sample apps · Runnable embedding examples for operational usage patterns. · `crates/truefix/examples/banzai.rs`
- [Specs](https://github.com/zhangjiayin/truefix/blob/main/specs/001-fix-engine-parity/spec.md): design contracts · Versioned architecture and parity contracts that define target behavior. · `specs/001-fix-engine-parity/spec.md`
- [Docs](https://github.com/zhangjiayin/truefix/blob/main/docs/roadmap.md): project docs · Roadmap, parity notes, and audit artifacts that guide implementation. · `docs/roadmap.md`

## Connections

- truefix → Config: loads settings · Facade startup begins by resolving config into runtime settings.
- truefix → Session: starts engine · Public engine entry wires settings into session orchestration.
- truefix → Application: exports API · Facade exposes the application callback boundary.
- Config → Transport: maps network · Configuration selects initiator/acceptor, TLS, proxy, and socket behavior.
- Config → Session: maps session · Configuration feeds session identity, schedules, and behavior switches.
- Config → Store: maps store · Configuration chooses persistence backend and recovery options.
- Config → Log: maps log · Configuration chooses audit/logging backend.
- Session → Core codec: uses codec · Session logic consumes decoded FIX messages and renders outbound ones.
- Session → Dictionary: validates typed · Session consults dictionaries for message, field, and admin validation.
- Session → Store: recovers state · Sequence recovery and resend flows read and write persisted session data.
- Session → Log: audits state · Session events and message activity are recorded to logging backends.
- Session → Application: invokes callbacks · Session hands application messages and callback outcomes to user code.
- Transport → Session: delivers bytes · Network I/O passes framed traffic into session processing and sends outbound bytes.
- Transport → Core codec: frames messages · Transport relies on core framing and codec for wire parsing/rendering.
- Transport → Dictionary: checks groups · Transport integrates dictionary-aware decoding and message validation.
- Dictionary → Core codec: builds protocol · Dictionary layer is built on top of the core FIX model and codec types.
- Codegen → Dictionary: generates types · Build script produces typed Rust artifacts from normalized dictionary sources.
- Dict CLI → Dictionary: parses source · CLI shares parsing, validation, and conversion paths with the dictionary crate.
- AT suite → Dictionary: gates parity · Acceptance scenarios verify dictionary coverage and typed/runtime consistency.
- AT suite → Session: gates session · Conformance tests exercise state machine and recovery behavior.
- AT suite → Transport: gates transport · Scenario coverage includes connection handling, TLS, failover, and backpressure.
- Examples → truefix: show usage · Examples demonstrate embedding the facade in applications.
- Specs → truefix: defines target · Architecture contracts define the intended engine surface and boundaries.
- Docs → AT suite: tracks parity · Docs capture roadmap, audits, and acceptance status for the engine.
