Clean Architecture Checker

Purpose

Verify that new code follows Clean Architecture principles as defined in the Polibase project.

When to Activate

This skill activates automatically when:

• Creating or modifying files in src/domain/, src/application/, src/infrastructure/, or src/interfaces/
• Reviewing code changes across multiple layers
• Adding entities, repositories, use cases, or services

Quick Checklist

Before approving code, verify:

• Dependency Rule: Dependencies point inward (Domain ← Application ← Infrastructure ← Interfaces)
• Entity Independence: Domain entities have no framework dependencies (no SQLAlchemy, Streamlit, etc.)
• Repository Pattern: All repos inherit from BaseRepository[T] and use async/await
• DTO Usage: DTOs used for layer boundaries, not raw entities
• Type Safety: Complete type hints with proper Optional handling
• Tests: Unit tests for domain services and use cases

Core Principles

1. Dependency Rule

Dependencies must point inward: Domain ← Application ← Infrastructure ← Interfaces

✅ Domain imports nothing from outer layers ✅ Application only imports Domain ✅ Infrastructure imports Domain and Application ✅ Interfaces imports all inner layers (but not other Interface modules)

2. Entity Independence

Domain entities must not depend on external frameworks

✅ Use @dataclass or Pydantic BaseModel ❌ No SQLAlchemy models in Domain ❌ No UI framework imports in Domain

3. Repository Pattern

All repositories follow async/await with ISessionAdapter

✅ Interfaces in Domain: class IRepo(BaseRepository[T]) ✅ Implementations in Infrastructure: class RepoImpl(BaseRepositoryImpl[T], IRepo) ✅ All methods are async def

4. DTO Pattern

Always use DTOs between layers

✅ DTOs in src/application/dto/ ✅ Input DTO → Use Case → Output DTO ❌ Never expose domain entities directly to outer layers

5. Type Safety

Leverage Python 3.11+ type hints

✅ All public methods have type hints ✅ Use T | None for nullable types ✅ Explicit None checks for Optional values

Common Violations

See examples.md for detailed good/bad code examples.

Detailed Reference

For comprehensive architecture guidelines, see reference.md.

Templates

Use templates in templates/ directory for creating new:

• Domain entities
• Repository interfaces and implementations
• Use cases with DTOs
• Domain services

References

• CLEAN_ARCHITECTURE_MIGRATION.md
• ARCHITECTURE.md
• tmp/clean_architecture_analysis_2025.md