solid-python

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](references/principles.md) | Quick reference for all 5 principles | | Patterns & Structure | [patterns.md](references/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 |