SOLID Go - 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 Go 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 interfaces, services, or logic

• Check shared locations: internal/core/services/ , internal/core/ports/

• If similar code exists -> extend/reuse instead of duplicate

• 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