<objective> SOLID Java enforces a modular architecture for Java 21+: every feature lives under `modules/[feature]/` (controllers, services, repositories, interfaces, models/DTOs) with shared code in `modules/core/`, interfaces live only in `modules/[feature]/interfaces/`, controllers stay under 50 lines and delegate to services, records are used for DTOs and sealed types for restricted hierarchies, and every public method carries Javadoc.

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. </objective>

SOLID Java - 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 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 |