<objective> SOLID Go enforces a modular architecture for Go 1.27+: every feature lives under `internal/modules/[feature]/` (handlers, services, repositories, ports, models) with shared code in `internal/core/`, interfaces (ports) live only in `ports/` directories and stay small (1-3 methods, the Go idiom), functions accept interfaces but return structs, and every exported function carries a godoc comment.

Before writing any new code it requires a DRY check against internal/core/services and internal/core/ports. See solid-principles.md for the overview, the per-principle references for SRP/OCP/LSP/ISP/DIP detail, architecture-patterns.md for hexagonal/modular layout, and the templates for module/service/interface/handler/error/test scaffolding. </objective>

SOLID Go - 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 Go 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: internal/core/services/, internal/core/ports/
3. If similar code exists -> extend/reuse instead of duplicate
4. If code will be used by 2+ features -> create it in internal/core/

---

Architecture (Modules MANDATORY)

| Layer | Location | Max Lines | |-------|----------|-----------| | Handlers | internal/modules/[feature]/handlers/ | 50 | | Services | internal/modules/[feature]/services/ | 100 | | Repositories | internal/modules/[feature]/repositories/ | 100 | | Ports (interfaces) | internal/modules/[feature]/ports/ | 30 | | Models | internal/modules/[feature]/models/ | 50 | | Shared | internal/core/{services,ports,models}/ | - |

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

---

Critical Rules (MANDATORY)

| Rule | Value | |------|-------| | File limit | 100 lines (split at 90) | | Handlers | < 50 lines, delegate to services | | Interfaces | ports/ directory ONLY | | Godoc | Every exported function documented | | Accept interfaces | Return structs | | Small interfaces | 1-3 methods max (Go idiom) |

---

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 providers | | LSP | liskov-substitution.md | Contracts | | ISP | interface-segregation.md | Fat interfaces | | DIP | dependency-inversion.md | Injection | | Architecture | architecture-patterns.md | Hex/modular |

Templates

| Template | When to use | |----------|-------------| | module.md | Feature module structure | | service.md | Business logic service | | interface.md | Port definition | | handler.md | HTTP handler | | error.md | Custom errors | | test.md | Table-driven tests |

---

Forbidden

| Anti-Pattern | Fix | |--------------|-----| | Files > 100 lines | Split at 90 | | Interfaces in impl files | Move to ports/ directory | | Fat interfaces (4+ methods) | Split into small interfaces | | Flat internal/ structure | Use internal/modules/[feature]/ | | init() for dependency wiring | Use constructor injection |