Michaelalber AI Toolkit Rust Feature Slice

Rust Feature Slice Architecture

"Organize code by what it does, not by what it is. A feature folder contains everything needed to deliver a capability — not everything that happens to be a handler." -- Adapted from Jimmy Bogard

"In Rust, there is no DI framework. There is ownership. Design your dependencies so that ownership is clear, and wiring becomes mechanical." -- Rust Architecture Principle

Core Philosophy

Vertical slice architecture in Rust organizes code by feature (domain capability) rather than technical layer (handlers, services, repositories). Each feature is a Rust module containing everything needed to deliver that capability: router, handlers, service trait, service implementation, request/response types, and tests.

Rust has no dependency injection framework. Dependencies are wired manually using Arc<dyn Trait> stored in Axum's State<AppState>. This is not a limitation — it is explicit, compile-time-verified dependency wiring. The AppState struct is the composition root.

CQRS in Rust is a naming convention enforced by trait design: OrderReader (query methods) and OrderWriter (command methods) are separate traits, potentially implemented by the same struct. This separation makes the read/write boundary explicit without requiring a library.

Non-Negotiable Constraints:

1. Feature module isolation — no use crate::features::other_feature:: in handlers. Features communicate through shared types in a common or domain module, not through direct imports.
2. Service traits, not concrete types — Arc<dyn OrderService> in AppState, not Arc<OrderServiceImpl>. This enables testing with mock implementations.
3. Arc<dyn Trait> for shared state — not Mutex<ConcreteType>. The trait defines the contract; the Arc provides shared ownership.
4. Result<T, AppError> on all handlers — handlers return Result<impl IntoResponse, AppError>. No panics, no unwrap in handler code.
5. Handler thinness — handlers extract request data, call the service, and return the response. Business logic belongs in the service, not the handler.

Domain Principles Table

Knowledge Base Lookups

Workflow

DETECT (before scaffolding)
    [ ] Check for existing AppState struct (src/state.rs or src/app.rs)
    [ ] Check for existing features/ directory structure
    [ ] Identify Rust edition and async runtime (Cargo.toml)
    [ ] Check for existing error types (AppError)
    [ ] Identify database access pattern (SQLx, Diesel, none)

        |
        v

SCAFFOLD (create feature module)
    [ ] Create src/features/<name>/mod.rs (re-exports)
    [ ] Create src/features/<name>/router.rs (Axum Router with State)
    [ ] Create src/features/<name>/service.rs (trait + impl)
    [ ] Create src/features/<name>/models.rs (request/response types)
    [ ] Create src/features/<name>/errors.rs (feature error type)
    [ ] Create tests/features/<name>/integration_test.rs

        |
        v

REGISTER (wire into app)
    [ ] Add service to AppState struct
    [ ] Add Arc<dyn Trait> initialization in app startup
    [ ] Merge feature Router into main app Router
    [ ] Add From<FeatureError> for AppError

        |
        v

VERIFY
    [ ] cargo build (no errors)
    [ ] cargo test (all tests pass)
    [ ] cargo clippy -- -D warnings (no warnings)

Exit criteria: Feature module created, registered in app, tests pass, Clippy clean.

State Block

<rust-feature-slice-state>
phase: DETECT | SCAFFOLD | REGISTER | VERIFY | COMPLETE
feature_name: [name]
edition: [2015 | 2018 | 2021]
async_runtime: [tokio | async-std | none]
app_state_exists: [true | false]
features_dir_exists: [true | false]
app_error_exists: [true | false]
files_created: [comma-separated list]
build_status: [pass | fail | not-run]
test_status: [pass | fail | not-run]
last_action: [description]
next_action: [description]
</rust-feature-slice-state>

Output Templates

Scaffold Checklist

## Rust Feature Slice Scaffold: [feature-name]

### Files to Create
- [ ] `src/features/[name]/mod.rs`
- [ ] `src/features/[name]/router.rs`
- [ ] `src/features/[name]/service.rs`
- [ ] `src/features/[name]/models.rs`
- [ ] `src/features/[name]/errors.rs`
- [ ] `tests/features/[name]/integration_test.rs`

### Files to Modify
- [ ] `src/state.rs` — add `Arc<dyn [Name]Service>` field
- [ ] `src/app.rs` or `src/main.rs` — merge feature Router, initialize service
- [ ] `src/errors.rs` — add `From<[Name]Error> for AppError`

### Verification
- [ ] `cargo build` passes
- [ ] `cargo test` passes
- [ ] `cargo clippy -- -D warnings` passes

Feature Module Template (in output)

// src/features/orders/mod.rs
// <AI-Generated START>
pub mod errors;
pub mod models;
pub mod router;
pub mod service;

pub use router::orders_router;
pub use service::OrderService;
// <AI-Generated END>

AI Discipline Rules

CRITICAL: Service Traits, Not Concrete Types in AppState

WRONG:

pub struct AppState {
    pub order_service: Arc<OrderServiceImpl>,
}

RIGHT:

pub struct AppState {
    pub order_service: Arc<dyn OrderService>,
}

The trait in AppState enables mock injection in tests. The concrete type is an implementation detail.

CRITICAL: Handlers Must Be Thin

WRONG:

async fn create_order(
    State(state): State<AppState>,
    Json(req): Json<CreateOrderRequest>,
) -> Result<impl IntoResponse, AppError> {
    // 50 lines of business logic here
    let validated = if req.items.is_empty() { ... };
    let total = req.items.iter().map(|i| i.price * i.qty).sum();
    // ... more logic
}

RIGHT:

async fn create_order(
    State(state): State<AppState>,
    Json(req): Json<CreateOrderRequest>,
) -> Result<impl IntoResponse, AppError> {
    let order = state.order_service.create_order(req).await?;
    Ok((StatusCode::CREATED, Json(order)))
}

REQUIRED: async_trait or Native Async Traits

For Rust < 1.75, use async_trait:

#[async_trait::async_trait]
pub trait OrderService: Send + Sync {
    async fn create_order(&self, req: CreateOrderRequest) -> Result<Order, OrderError>;
}

For Rust 1.75+, use native async traits:

pub trait OrderService: Send + Sync {
    fn create_order(&self, req: CreateOrderRequest)
        -> impl Future<Output = Result<Order, OrderError>> + Send;
}

Note both patterns in the scaffold and recommend native async traits for Rust 1.75+.

Anti-Patterns Table

Error Recovery

AppState Already Exists with Different Structure

Symptoms: src/state.rs exists but uses a different pattern (e.g., concrete types)

Recovery:
1. Read the existing AppState structure
2. Report the current pattern to the user
3. Ask: "The existing AppState uses [pattern]. Should I adapt the new feature
   to match the existing pattern, or refactor AppState to use Arc<dyn Trait>?"
4. Do NOT silently change the existing AppState pattern
5. If user wants to keep existing pattern: scaffold the feature to match

No Existing Features Directory

Symptoms: src/features/ does not exist

Recovery:
1. Create src/features/mod.rs with the new feature module declaration
2. Note in the scaffold output: "Created src/features/ directory structure"
3. Add `pub mod features;` to src/lib.rs or src/main.rs
4. Proceed with the feature scaffold

async_trait Version Conflict

Symptoms: Cargo.toml has async_trait but at an incompatible version

Recovery:
1. Check the Rust edition and version
2. If Rust 1.75+: recommend removing async_trait and using native async traits
3. If Rust < 1.75: check async_trait version compatibility
4. Report the conflict and recommended resolution before scaffolding

Integration with Other Skills

Source: michaelalber/ai-toolkit — distributed by TomeVault.