arch:review

Command /architect:review

Comprehensive architecture review for Python backend projects.

Instructions

Step 1: Discover Project Structure

Use Glob to map the project:

# Find main structure
Glob: **/main.py, **/app.py, **/wsgi.py
Glob: **/__init__.py
Glob: **/models.py, **/services.py, **/routers.py, **/repositories.py

# Find configuration
Glob: **/config.py, **/settings.py, **/.env.example

# Find tests
Glob: **/test_*.py, **/*_test.py, **/conftest.py

Step 2: Analyze Layer Architecture

Check if proper separation exists:

Layer	Files	Responsibility
Presentation	routers.py, views.py	HTTP handling, DTOs
Application	services.py	Business logic
Domain	models.py	Entities, business rules
Infrastructure	repositories.py	Data access

Check violations:

• Business logic in routers (should be in services)
• Direct DB access in services (should be via repositories)
• Models returning DTOs (should return domain objects)

Step 3: Check Module Boundaries

For each module, verify:

1. Cohesion: Related functionality grouped together
2. Coupling: Minimal dependencies on other modules
3. Encapsulation: Clear public API (__init__.py exports)

# Check for cross-module imports
Grep: "from src.modules.users" in orders/
Grep: "from src.modules.orders" in users/

Circular dependencies:

Module A imports Module B
Module B imports Module A  ← Problem!

Step 4: Analyze Dependency Injection

Check how dependencies are managed:

Good patterns:

# Constructor injection
class UserService:
    def __init__(self, repository: UserRepository):
        self._repository = repository

# DI container (dependency-injector)
user_service = providers.Factory(UserService, repository=user_repository)

Bad patterns:

# Hard-coded dependencies
class UserService:
    def __init__(self):
        self._repository = UserRepository()  # Tight coupling!

# Global instances
user_service = UserService()  # Global state!