Codebase Orientation

Learn a Rust workspace by reading Cargo.toml boundaries, tracing the binary main path, and mapping where errors, config, and domain types live.

Recipe

# Workspace overview
cat Cargo.toml
cargo tree --depth 2
rg "^\[workspace\]" -l
 
# Entry points
fd main.rs
rg "#\[tokio::main\]" -l
 
# Public API surface
cargo doc --no-deps --open

When to reach for this:

• First day on a new repo
• Before proposing architecture refactor
• After major workspace split

Working Example

Typical Axum service workspace layout:

billing/
  Cargo.toml          # workspace root
  crates/
    api/              # binary: HTTP server
      src/main.rs
      src/routes/
      src/state.rs
    domain/           # lib: business logic, no axum
    infra/            # lib: sqlx, reqwest adapters
  migrations/         # sqlx migrate

Reading order:

1. Root Cargo.toml workspace members and shared deps
2. api/src/main.rs - startup, tracing, pool creation
3. domain/src/lib.rs - core types and traits
4. infra - how DB and HTTP clients implement traits
5. migrations/ - schema truth

What this demonstrates:

• Binaries are thin; domain stays framework-agnostic
• Dependency direction: api -> domain <- infra
• Migrations live outside hot code paths

Deep Dive

Questions to Answer in Hour One

Navigation Tools

• rg "struct AppState" - shared handler state
• cargo doc - rustdoc on public items
• rust-analyzer goto-def across crates

Gotchas

• Starting in wrong crate - missing workspace context. Fix: always root Cargo.toml first.
• Ignoring feature flags - code "missing" in IDE. Fix: check Cargo.toml [features].
• Assuming single binary - workspace has many. Fix: cargo metadata | jq '.packages[].targets'.
• Docs only in README - stale. Fix: trust cargo doc and architecture/ ADRs.
• Skipping migrations - wrong mental model of entities. Fix: read SQL schema early.

Alternatives

FAQs

Related

• Project structure patterns
• Workspaces
• Onboarding Devs Checklist
• Search & regex

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.