# Project Structure Rust

> Rust/Cargo Layout

- Skill: `irahardianto/project-structure-rust` (Agent Skill)
- Install (CLI): `npx skillmds@latest add irahardianto/project-structure-rust`
- Raw SKILL.md: https://api.skillmd.com/api/skills/irahardianto/project-structure-rust/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: irahardianto (https://skillmd.com/u/irahardianto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/irahardianto/project-structure-rust

---


## Rust/Cargo Layout

Vertical slice — features are modules, not layers.

### Single Binary Crate

```
project-root/
  Cargo.toml
  build.rs                          # Optional (FFI, codegen)
  src/
    main.rs                        # Entry point: CLI, server, wire deps
    lib.rs                         # Public modules (enables integration testing)
    config.rs                      # Config loading
    error.rs                       # App-wide errors (thiserror)
    telemetry.rs                   # Tracing setup

    features/
      mod.rs
      task/
        mod.rs                     # Public API, re-exports
        service.rs                 # Business logic orchestration
        logic.rs                   # Pure rules (no I/O)
        models.rs                  # Domain structs
        error.rs                   # Feature errors
        repository.rs              # Storage trait
        postgres.rs                # PostgreSQL impl
        mock.rs                    # Mock impl

    handlers/
      mod.rs
      task_handler.rs              # HTTP handlers (axum/actix)
      auth_handler.rs
    router.rs                      # Routes + middleware

  tests/                           # Integration tests (separate crate, pub API only)
    common/mod.rs                  # Shared fixtures
    task_api_test.rs
  benches/
    task_benchmark.rs
```

Key: `lib.rs` + `main.rs` enables integration testing. `mod.rs` = feature boundary. `error.rs` per feature with `thiserror` + `#[from]`. No top-level `controllers/`/`services/`.

### Library Crate

```
project-root/
  Cargo.toml
  src/
    lib.rs                         # Public API surface
    parser.rs
    ast.rs
    error.rs
    internal/
      mod.rs
      optimizer.rs
      cache.rs
  examples/
    basic_usage.rs
  tests/
    parsing_test.rs
  benches/
    parser_benchmark.rs
```

### Cargo Workspace (Multi-Crate)

```
project-root/
  Cargo.toml                        # [workspace]
  Cargo.lock                        # Committed for binaries

  crates/
    myapp/
      Cargo.toml
      src/
        main.rs
        lib.rs
        config.rs
        error.rs
        api/
          mod.rs
          routes.rs
          handlers.rs

    myapp-parser/
      Cargo.toml
      build.rs
      src/
        lib.rs
        parser.rs
        transform.rs
        cache.rs
      tests/
        parser_integration.rs

    myapp-client/
      Cargo.toml
      src/
        lib.rs
        client.rs
        lifecycle.rs
        retry.rs

    myapp-search/
      Cargo.toml
      src/
        lib.rs
        search.rs
        filter.rs
      tests/
        search_integration.rs

    myapp-common/
      Cargo.toml
      src/
        lib.rs
        types.rs
        error.rs
      tests/
        common_integration.rs

  tests/
    integration/
      full_pipeline_test.rs

  config/
    myapp.config.default.json
```

Key differences: `crates/` = Cargo workspace. Each crate own `Cargo.toml` (scoped deps, separate compilation). `build.rs` for FFI. `Cargo.lock` committed for binaries. Feature flags via `[features]` in `Cargo.toml`.

### Test Organization (Rust-Specific)

**Unit — inline** (not separate files): `#[cfg(test)] mod tests` at bottom of each `.rs`. Conditionally compiled. Access private via `use super::*`. Idiomatic — do NOT create `*_test.rs`.

**Integration — `tests/` dir**: each file = separate crate, public API only. No `#[cfg(test)]` needed. Shared helpers: `tests/common/mod.rs` (NOT `tests/common.rs`).

**Workspace-level:** `tests/` at workspace root or dedicated test crate.

```
crates/pathfinder-search/
  Cargo.toml
  src/
    lib.rs                  # Contains #[cfg(test)] mod tests { ... }
    search.rs               # Contains #[cfg(test)] mod tests { ... }
    filter.rs               # Contains #[cfg(test)] mod tests { ... }
    mock.rs
  tests/
    search_integration.rs
    common/
      mod.rs
```

### Related
- Project Structure GEMINI.md § Project Structure
- Rust Idioms and Patterns @.gemini/skills/rust-idioms/SKILL.md