SOLID Rust - Modular Architecture

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

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

---

DRY - Reuse Before Creating (MANDATORY)

Before writing ANY new code:

1. Grep the codebase for similar traits, services, or logic
2. Check shared locations: src/core/services/, src/core/traits/
3. If similar code exists -> extend/reuse instead of duplicate
4. 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>