solid-java

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

SOLID Java - Modular Architecture

Agent Workflow (MANDATORY)

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

1. fuse-ai-pilot:explore-codebase - Analyze existing architecture
2. fuse-ai-pilot:research-expert - Verify Java 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 interfaces, services, or logic
2. Check shared locations: modules/core/services/, modules/core/interfaces/
3. If similar code exists -> extend/reuse instead of duplicate
4. If code will be used by 2+ features -> create it in modules/core/

---

Architecture (Modules MANDATORY)

Layer	Location	Max Lines
Controllers	modules/[feature]/controllers/	50
Services	modules/[feature]/services/	100
Repositories	modules/[feature]/repositories/	100
Interfaces	modules/[feature]/interfaces/	30
Models/DTOs	modules/[feature]/models/	50
Shared	modules/core/{services,interfaces,models}/	-

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

---

Critical Rules (MANDATORY)

Rule	Value
File limit	100 lines (split at 90)
Controllers	< 50 lines, delegate to services
Interfaces	modules/[feature]/interfaces/ ONLY
Javadoc	Every public method documented
Records	Use for DTOs (Java 16+)
Sealed	Use for restricted hierarchies (Java 17+)

---

Reference Guide

Concepts

Topic	Reference	When to consult
SOLID Overview	solid-principles.md	Quick reference
SRP	single-responsibility.md	Fat classes
OCP	open-closed.md	Adding providers
LSP	liskov-substitution.md	Contracts
ISP	interface-segregation.md	Fat interfaces
DIP	dependency-inversion.md	Injection
Architecture	architecture-patterns.md	Modular patterns

Templates

Template	When to use
module.md	Feature module structure
service.md	Business logic service
interface.md	Contract definition
repository.md	Data access layer
error.md	Custom exceptions
test.md	Unit tests with mocks

---

Forbidden

Anti-Pattern	Fix
Files > 100 lines	Split at 90
Interfaces in impl files	Move to interfaces/ directory
new ConcreteClass() in services	Use dependency injection
Flat src/ structure	Use modules/[feature]/
God classes	Split by responsibility