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

---

Architecture (Modules MANDATORY)

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

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

---

Critical Rules (MANDATORY)

Rule	Value
File limit	100 lines (split at 90)
Routes	< 50 lines, delegate to services
Interfaces	interfaces/ directory ONLY
Docstrings	Every public function documented
Type hints	MANDATORY on all signatures
Protocols	Use typing.Protocol for interfaces
Small interfaces	1-3 methods max

---

Reference Guide

Topic	Reference	When to consult
SOLID Principles	principles.md	Quick reference for all 5 principles
Patterns & Structure	patterns.md	Directory layout, testing, typing

---

Forbidden

Anti-Pattern	Fix
Files > 100 lines	Split at 90
Interfaces in impl files	Move to interfaces/ directory
Fat interfaces (4+ methods)	Split into small Protocols
Flat src/ structure	Use modules/[feature]/
Concrete dependencies	Use Protocol + dependency injection
Missing type hints	Add type annotations to all signatures