# Idiomatic Rust & Axum Microservice Specialist

> Idiomatic Rust standards with Axum, Tokio runtime, typed extractors, and zero-unwrap error handling.

## Quick Reference
- **Framework**: Axum & Tokio
- **Language**: Rust 2021 Edition
- **Styling & UI**: None / API Service
- **Database / Persistence**: PostgreSQL (SQLx)
- **Architectural Philosophy**: strict

## Core Architectural Invariants
- **Guard Clauses & Early Returns**: Exit early from functions to eliminate deeply nested if-else pyramids.
- **Explicit Result / Tuple Returns**: Return [error, result] or Result<T, E> types for operations that can fail.
- **Schema-Driven Boundaries**: Validate all external data (API, forms, env) with Zod or Pydantic schemas; on failure, reject with a typed error and never pass unvalidated data onward.

## Operational Guardrails & Prohibited Patterns
- **Inspect Before Acting**: Always read and understand existing code and imports before suggesting changes.
- **Minimal Surgical Diffs**: Touch only lines relevant to prompt. Preserve existing comments and formatting.
- **Propose Verification Steps**: With every modification, specify concrete commands or tests to verify correctness.

## Mandatory Project Directives
- Run 'cargo clippy -- -D warnings' as a standard validation gate.
- Keep dependencies minimal; prefer serde and tokio primitives.

## Implementation Reference

### Preferred Patterns
```rust
// Good: Typed handler returning custom Result with IntoResponse
pub async fn create_user(
    State(state): State<Arc<AppState>>,
    Json(payload): Json<CreateUserRequest>,
) -> Result<Json<UserResponse>, AppError> {
    let user = state.db.insert_user(&payload).await?;
    Ok(Json(user.into()))
}
```

### Discouraged Anti-Patterns
```rust
// Discouraged: Calling unwrap inside async handler
pub async fn create_user(Json(payload): Json<CreateUserRequest>) -> Json<UserResponse> {
    let user = db.insert_user(&payload).await.unwrap();
    Json(user.into())
}
```

## Verification Commands & Workflows
1. Propagate errors with the '?' operator; never call .unwrap() or .expect() in handlers.
2. Implement IntoResponse on a centralized AppError enum.
3. Use Axum extractors (State, Json, Path) in strict dependency order.
4. Pass shared resources via Arc<AppState> using Axum's State extractor.

## Context Documents & Specs
- [System Architecture](ARCHITECTURE.md): Authoritative system design, data flows, and state machine invariants.
- [AI Multi-Agent Spec](AGENTS.md): Universal specification for autonomous coding agent operations.