---
# System prepended metadata

title: Engineering Guide

---

# Engineering Guide

## 1. Key Principles
> These are the non-negotiable core ideas we bring into everything we build. Builder, orderflow integrations, telemetry etc. 
> We move fast, and keep systems simple and clean so we can keep shipping.

- **You own what you ship**
  The engineer writing the code is responsible for correctness, clarity, impact and delivery. If it breaks, you fix it. If it’s unclear, you clarify it.
- **We own the system together**  
  An important follow-up to the above point. There’s no “not my code”. If you see something broken, unclear, or slow - fix it or flag it. Everyone is responsible for the state of the codebase, not just the original author.
 - **Code is a liability**  
  Fewer lines = less to reason about, less to break, less to maintain. Delete aggressively. If something isn’t essential, remove it.  
- **Tight local feedback loops**  
  Every part of the system must run locally and mimic production closely. Fast iteration is an exponential leverage. If something can’t run locally, fix that first.
- **Simplicity over complexity**  
  Simple, predictable designs are easier to optimise, debug, and scale. Be concise. Complexity spreads fast and kills performance.
- **Contain complexity**  
  Keep modules tight. Keep scope narrow. Keep interfaces explicit (do not pub use ::* everything...). Complexity that leaks across boundaries causes spaghetti.
  
> Our priorities for code match our principles:
> 1. **Correctness** – the system must behave deterministically. If it’s wrong, nothing else matters.  
>    Correctness comes from clear, contained systems without unnecessary complexity.  
> 2. **Performance** – speed is a large part of our edge and pnl.
> 3. **Maintainability** – simple code is faster to iterate on and easier to reason about.
>
> Everything else follows from these. Keep these in mind when designing, reviewing, or rewriting.

---

## 2. Reviews
> Reviews are one of the most important, and most overlooked, parts of being an engineer. High standards in reviews = high standards in the system. Treat them as first-class.

### Pull Requests
- Keep PRs scoped and clear.
- Never mix large refactors with business logic changes.  
  - Cosmetic refactor → separate PR (skim quickly).  
  - Logic change → separate PR (deep review).
- If there are business logic changes include a short rationale: what changed, why it matters, how to review (e.g., key files changed).

### Reviews
- Reviewing is *not optional*. It’s part of being an engineer.
- No one works alone. No big code changes go to production without review.
- Do not skim changes. If you don’t understand the change, ask questions or get the right reviewer involved. Don’t let unclear code merge.  
- If you see something sloppy, call it out. Everyone owns quality.
- There's more than one good way to implement something. Don't bikeshed. Review comments should be substantive and backed by reason.

> Strong review culture requires work from both sides. PRs must be scoped and reasonable. Reviews must be done thoroughly and promptly (should be ≤1 day).  

---

## 3. Framework for our High-Performance Systems
> This is the core of our infra. Everything else sits around it. Even when building systems that aren't on the hot-path it's still important to understand these principles.

### Core Ideas
- One stage = one responsibility.
- Message passing, not shared locks.
- Timing for every stage, for every message.

### How It Looks
- **Pipeline**  
  The system is built from well-defined stages (tiles). Each tile has a single responsibility, runs pinned on a core, and spins in a tight loop.
- **Tile Trait**  
  - Each tile implements a Tile trait with setup, pinned loop, and teardown.  
  - Each tile owns its core.
  - Tiles are isolated - no shared mutable state between them.  
- **Communication**  
  - Lightweight, copy messages are sent through broadcast queues.  
  - Any dynamic allocations are stored in pre-allocated shared memory. Messages only carry offsets.
- **Telemetry / Tracking**  
  - All messages are tracked as `InternalMessage`.  
  - Because queues are broadcast, a separate process can pick up and read everything to display locally (e.g., overseer) or write to DBs.

> Core datastructures and types can be found in `gattaca-com/flux`
> https://github.com/firedancer-io/firedancer is a great reference and the inspiration for the name "Tile".
---

## 4. More General Code Guidelines

- **AI**
  AI can help, but it’s easy to abuse. Unsupervised changes are messy, overcomplicated, and usually wrong. Don’t ship code you don’t understand.
- **Crates**  
  Crates are often overused in the wrong place and underused in the right place. Make a new crate only if it’s actually reused.  
  - Don’t split code into multiple crates for the sake of it. If a component (e.g. bid-submitter) is only ever read by one crate, keep it together.  
  - Do split code into crates if they’re genuinely shared.  
  - Avoid dumping everything into a single “shared” or “common” crate. Keep shared crates focused and minimal so importing one doesn’t drag in everything else.
- **Config for the sake of config is a mistake**  
  Are these conditions going to be used. Do they provide a use. If not, do not add.
- **Dumping Grounds**
  Avoid catch-all files like `types.rs`, `utils.rs`, or `mod.rs`.  
  This doesn’t mean one file per struct — that’s also wrong.  
  Group related things together, separate unrelated ones.
- **Comments**
  - Don’t comment the obvious (`// this variable is a count` above `let mut count = 0;`).  
  - Avoid overly verbose doc comments.  
  - Keep comments concise and pointed.  
  - Comment where logic is non-obvious or business rules aren’t clear from code alone.
- **Tests**  
  Test enough to be sure it works. Tests should be clear and fast.  
  Don’t build bloated CI or over-engineered tests. Tight local feedback loops and good monitoring do most of work.
- **Lints**
  Run `just fmt` and `just clippy` before every PR. It’s easy and keeps the style consistent.
- **Traits**
  Traits with a single implementation shouldn’t exist.  
  Same principle as config: don’t add traits for the sake of traits.
- **Commit Messages**
    Commits into develop must be clearly named. The history should tell a clear story of what happened - no “wip” or vague messages.
    Temporary messages are fine on feature branches since they’ll be squash merged, but make sure the final squash commit is clear and to     the point.
    
    
> This guide is always changing. If you see gaps, propose changes.