solid-rust

Before writing any new code it requires a DRY check against src/core/services and src/core/traits. See solid-principles.md for the overview, the per-principle references for SRP/OCP/LSP/ISP/DIP detail, and the templates for module/service/trait/handler/error/test scaffolding.

SOLID Rust - Modular Architecture

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

fuse-ai-pilot:explore-codebase - Analyze existing architecture
fuse-ai-pilot:research-expert - Verify Rust docs via Context7
fuse-ai-pilot:sniper - Post-implementation validation

DRY - Reuse Before Creating (MANDATORY)

Before writing ANY new code:

Grep the codebase for similar traits, services, or logic
Check shared locations: src/core/services/, src/core/traits/
If similar code exists -> extend/reuse instead of duplicate
If code will be used by 2+ features -> create it in src/core/

Architecture (Modules MANDATORY)

Layer	Location
Handlers	`src/modules/[feature]/handlers.rs`
Services	`src/modules/[feature]/services.rs`
Repositories	`src/modules/[feature]/repository.rs`
Traits	`src/modules/[feature]/traits.rs`
Models	`src/modules/[feature]/models.rs`
Shared	`src/core/{services,traits,models}/`

NEVER use flat src/ structure - always src/modules/[feature]/

Critical Rules (MANDATORY)

Rule	Value
File limit	`FUSE_SOLID_MAX_LINES`
Handlers	Thin, delegate to services
Traits	`traits.rs` or `src/core/traits/` ONLY
Rustdoc	`///` on every public item
Error handling	Use `thiserror` for custom errors
Generics	Use trait bounds, not concrete types

Reference Guide

Concepts

Topic	Reference	When to consult
SOLID Overview	solid-principles.md	Quick reference
SRP	single-responsibility.md	Fat structs
OCP	open-closed.md	Adding impls
LSP	liskov-substitution.md	Trait contracts
ISP	interface-segregation.md	Fat traits
DIP	dependency-inversion.md	Generics/DI
Architecture	architecture-patterns.md	Modular crate

Templates

Template	When to use
module.md	Feature module structure
service.md	Business logic service
trait-def.md	Trait definition
handler.md	HTTP handler (Axum)
error.md	Custom errors (thiserror)
test.md	Unit + integration tests

Forbidden

Anti-Pattern	Fix
Files over `FUSE_SOLID_MAX_LINES`	Split by responsibility
Traits in impl files	Move to `traits.rs`
`Box<dyn Any>`	Use proper trait bounds
Flat `src/` structure	Use `src/modules/[feature]/`
Unwrap in library code	Use `Result<T, E>`