Portfolio & Documentation

The first screen of the README, before any scrolling, should contain:

1. One paragraph: what the system is, at what scale and speed, and why you built it. "A price-time-priority exchange in Rust: gateway, pre-trade risk, a single-threaded matching engine with a replicated journal, and A/B market data. ~X M orders/s and Y µs p99 order-to-ack on a tuned host" (with the numbers linked to the report).
2. Proof it runs: a screenshot or short recording of the GPUI terminal running your engine, or of the deployed demo's page, plus the demo link.
3. Quick start in three commands or fewer, and you've tested them on a clean machine.

Below the fold: the headline performance table (generated, see Day 3), the architecture overview link, a crate map (one line per crate, in data-flow order), how to run the tests and benchmarks, what's deliberately out of scope (no clearing, one asset class, simulated members), and the licence.

The Diátaxis framework is a useful check on everything else you write. A tutorial, a how-to guide, a reference and an explanation are different documents. Mixing them is why most READMEs are hard to use. The README is mostly explanation plus one how-to (quick start). Everything else gets linked.

The overview answers where does an order go, who owns what, and what must always be true? Use the top two levels of the C4 model: context (the exchange, its members, market-data consumers) and containers/components (gateway, risk, engine, journal, market data, the demo and the terminal). One diagram, one paragraph per component, and an explicit invariants section:

• Every component has an owner thread. State is mutated by exactly one thread. Name it.
• Every arrow that crosses a thread boundary is a queue, and you name its type (the week 5 ring, the week 16 broadcast ring). A direct call across threads in the diagram is either a bug in the diagram or a lock in the code. Conversely, a queue between two components on the same thread is a hop you're paying for nothing.
• The order path is one line: gateway → risk → engine → market data. Readers anchor everything else to it. The repo's README diagram draws gateway → risk → journal → engine → marketdata, because the journal sequences and appends each command before the engine applies it, and a week 51 test checks that the diagram draws exactly that path.
• Decisions have records. For the three biggest choices (single-threaded matching, ack-after-replication, the wire format) write a short architecture decision record: context, decision, consequences.

Keep the diagram as code (Mermaid renders directly in GitHub markdown) so it's diffable and reviewable like everything else, and generate the component table from the same data if you can. Then the drill's checks can run in CI.

The drill encodes the overview as data and lints it the way a careful reviewer would. Then you derive the order path from the flows instead of typing it.

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Transport {
    Call,      // a direct function call: only valid within one thread
    Queue,     // an in-process queue (SPSC ring, broadcast ring, ...)
    Tcp,
    Multicast,
}

#[derive(Debug, Clone)]
pub struct Component {
    pub name: &'static str,
    pub crate_name: &'static str,
    pub thread: &'static str, // owning thread; "" = not stated
}

#[derive(Debug, Clone)]
pub struct Flow {
    pub from: &'static str,
    pub to: &'static str,
    pub via: Transport,
}

#[derive(Debug, Clone)]
pub struct ArchDoc {
    pub entry: &'static str, // where orders enter
    pub components: Vec<Component>,
    pub flows: Vec<Flow>,
}

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub enum Issue {
    /// The entry or a flow endpoint isn't a listed component (each name once).
    UnknownComponent(&'static str),
    /// A component with thread == "".
    NoOwnerThread(&'static str),
    /// A Call between two components on different (stated) threads.
    CallAcrossThreads(&'static str, &'static str),
    /// A Queue between two components on the same (stated) thread.
    QueueWithinThread(&'static str, &'static str),
    /// A listed component not reachable from `entry` by following flows
    /// between listed components (all of them, if the entry is unknown).
    Unreachable(&'static str),
}

/// Every issue, each once, in any order.
pub fn lint(doc: &ArchDoc) -> Vec<Issue> {
    let _ = doc;
    todo!()
}

/// The order path: start at `entry`; repeatedly follow the FIRST flow (in
/// list order) from the current component to a listed component not yet on
/// the path; stop when there is none. Empty if the entry isn't listed.
pub fn order_path(doc: &ArchDoc) -> Vec<&'static str> {
    let _ = doc;
    todo!()
}

Your performance numbers are the most scrutinised part of the repo, and the easiest to get wrong. Rules for the report:

• Generate it. cargo xtask report --markdown PATH renders the report from the benchmark JSON, and cargo xtask report --from hft-report.json --markdown - re-renders a saved report without running anything. No number is ever typed by hand, so the README can't drift from the data.
• State the context on every report: CPU model, core count, kernel, governor and isolation settings, rustc version, build profile, commit hash, date, and whether the run was on the tuned reference machine or a laptop. The generated report records the commit, CPU, core count, OS, rustc and date; state the rest next to it.
• Report distributions, not a number: p50, p99, p99.9 and max with sample counts, using the coordinated-omission-corrected open-loop numbers from week 25. Link the full HDR histogram plots.
• Compare only like with like. Same machine, same profile, enough repetitions. Call a change a change only when it's outside run-to-run noise, and say so when it isn't.
• Say what's missing. Kernel networking rather than bypass, simulated members, one host. Limitations stated up front read as competence; limitations discovered by the reader read as overclaiming.

The drill builds the comparison logic a report needs when it sets two runs side by side: medians over repeated runs, a conservative "ranges must not overlap" rule for calling a change, three-significant-figure formatting, and an explicit refusal to compare across machines or build profiles. cargo xtask report --markdown renders one report rather than a comparison, and formats its numbers the drill's way: three significant figures, truncated, with the unit switched to keep them.

#[derive(Debug, Clone)]
pub struct Run {
    pub machine: &'static str,
    pub profile: &'static str, // build profile, e.g. "release+lto"
    pub p99_ns: Vec<u64>,      // one p99 per repeated benchmark run
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Verdict {
    Incomparable(&'static str), // "machine" | "profile" | "samples"
    NoChange,
    Faster(u64), // percent
    Slower(u64), // percent
}

/// Median; for an even count, the mean of the two middle values rounded
/// down. 0 for an empty slice.
pub fn median(xs: &[u64]) -> u64 {
    let _ = xs;
    todo!()
}

/// Rules, in order:
///  machine differs → Incomparable("machine"); profile differs →
///  Incomparable("profile"); either run has < 5 samples → Incomparable("samples").
///  Every `after` sample below every `before` sample → Faster(p);
///  every `after` sample above every `before` sample → Slower(p);
///  otherwise → NoChange.
///  p = |median(before) − median(after)| × 100 / median(before),
///  rounded to the nearest integer (halves up).
pub fn compare(before: &Run, after: &Run) -> Verdict {
    let _ = (before, after);
    todo!()
}

/// Three significant figures, truncated (not rounded), switching units:
///   < 1_000 ns → "850 ns"; < 1_000_000 → "1.23 µs" / "12.3 µs" / "123 µs";
///   < 1_000_000_000 → "1.23 ms" ...; otherwise seconds, e.g. "1.50 s".
pub fn fmt_ns(ns: u64) -> String {
    let _ = ns;
    todo!()
}

/// "| {name} | {fmt_ns(median before)} | {fmt_ns(median after)} | {verdict} |"
/// verdict: "faster by 20%" | "slower by 12%" | "no change (within noise)"
///        | "not comparable (machine)" (or profile / samples)
pub fn row(name: &str, before: &Run, after: &Run) -> String {
    let _ = (name, before, after);
    todo!()
}

Some readers will open crates/sync/src/spsc.rs. Make that a good experience:

• Module-level docs that state the invariants before any code: "single producer, single consumer; head is written only by the producer…".
• A // SAFETY: comment on every unsafe block, arguing why it's sound. Clippy's undocumented_unsafe_blocks lint enforces it, so turn it on for the crates that use unsafe.
• Doc examples are tests. cargo test compiles and runs them, so the example in the README of each crate can't rot.
• Public items documented in library crates (#![warn(missing_docs)]), each with a sentence on cost where it matters: "O(1), no allocation", "takes a lock".
• Tests named for the behaviour they protect. w07_sweep_follows_price_then_time_priority is documentation.

Interviewers will ask "tell me about this project". Have a ten-minute version and a two-minute version, both with the same spine:

1. The problem in one sentence, and why it's hard (determinism plus microsecond latency plus recovery).
2. The architecture along the order path, in one breath, with the thread model.
3. One deep decision you can defend against pushback, such as single-threaded matching, ack-after-replication or the wire format, with the alternative you rejected.
4. One bug story with a measurement: the false-sharing hunt, the coordinated-omission correction that changed your p99 by 10×, the replay that disagreed with production.
5. The numbers, with their machine and method, and what limits them.
6. What's next and what you would do differently.

Tailor the emphasis to the role. Trading-infrastructure teams want steps 2–5. Exchange operators want determinism, recovery and failover. Quant developer roles want the backtester and the strategy work from weeks 41–45.

Ask someone who hasn't seen the project (or yourself, on a fresh VM) to go from the repo URL to running the demo and the test suite in ten minutes, without asking you anything. Write down every place they hesitate. Each hesitation is a documentation bug: a missing prerequisite, an outdated command, an unexplained term, a broken link. Fix them all, then run the test again with someone else.