# System Architecture & Invariants: Idiomatic Rust & Axum Microservice Specialist

## 1. System Overview
Idiomatic Rust standards with Axum, Tokio runtime, typed extractors, and zero-unwrap error handling.
All AI agents operating within this repository must adhere strictly to these architectural boundaries.

### Technology Stack
- **Framework**: Axum & Tokio
- **Language Standard**: Rust 2021 Edition
- **UI & Styling**: None / API Service
- **Data Persistence**: PostgreSQL (SQLx)
- **Engineering Philosophy**: strict

## 2. 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.

## 3. Data Flow & State Management Principles
1. **Unidirectional Data Flow**: State flows top-down; mutations flow through explicit, typed handlers.
2. **Boundary Validation**: External inputs (API payloads, query parameters, environment variables) must be parsed with strict schemas before reaching domain logic.
3. **Surgical Precision**: Diffs must remain minimal and scoped exclusively to the objective. Do not reformat unrelated code.

## 4. Forbidden Anti-Patterns & Operational Guardrails
- **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.

## 5. Domain-Specific Invariants
- Run 'cargo clippy -- -D warnings' as a standard validation gate.
- Keep dependencies minimal; prefer serde and tokio primitives.

## 6. Implementation Reference Patterns

### Preferred Pattern
```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()))
}
```

### Forbidden Anti-Pattern
```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())
}
```

## 7. Verification Protocol
Before finalizing any implementation:
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.