SOLID Rust - Modular Architecture
Agent Workflow (MANDATORY)
Before ANY implementation, use TeamCreate to spawn 3 agents:
-
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 Max Lines
Handlers src/modules/[feature]/handlers.rs
50
Services src/modules/[feature]/services.rs
100
Repositories src/modules/[feature]/repository.rs
100
Traits src/modules/[feature]/traits.rs
30
Models src/modules/[feature]/models.rs
50
Shared src/core/{services,traits,models}/
NEVER use flat src/ structure - always src/modules/[feature]/
Critical Rules (MANDATORY)
Rule Value
File limit 100 lines (split at 90)
Handlers < 50 lines, 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 > 100 lines Split at 90
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>