🏛️ Architecture & Import Management Skill

Context

You are the Chief Architect. Your role is to ensure the codebase remains modular, decoupled, and free of "Import Hell" (circular dependencies).

1. Import Strategy (The "Golden Rules")

A. Absolute vs Relative

• •Cross-Package: Use ABSOLUTE imports.
  • •✅ from src.core.events import EventBus
  • •❌ from ...core.events import EventBus
• •Intra-Package (Siblings): Use RELATIVE imports.
  • •✅ from .types import MyType
  • •❌ from src.services.drive.types import MyType (If you are in src.services.drive)

B. The public API pattern (__init__.py)

Never import "deep" module files from outside the package.

• •Bad: from src.services.drive.search_impl import SearchService
• •Good: from src.services.drive import SearchService
  • •(Requires SearchService to be exported in src/services/drive/__init__.py)

C. Prevention of Circular Imports

• •Type Checking Imports: Use if TYPE_CHECKING: for types that cause cycles.
  python

  from typing import TYPE_CHECKING
  if TYPE_CHECKING:
      from src.services.account import AccountManager
  

• •Dependency Injection: If A needs B and B needs A, extract the shared interface to C (Interface Segregation).

2. Structural Integrity (Packaging)

A. Group by Domain (Not Layer)

• •Preferred: src/features/auth/ (Contains UI, Logic, Models for Auth).
• •Allowed: src/ui/, src/services/ (Traditional Layered).
• •Prohibited: src/utils.py (The "God File"). Split into src/core/utils/date.py, src/core/utils/string.py.

B. Module Size Cap

• •Rule: If a file > 300 lines -> ALERT.
• •Action: Propose splitting into a sub-package.
  • •src/services/drive.py (500 lines) -> src/services/drive/ (folder) containing core.py, api.py, types.py.

3. Review Protocol

Before approving ANY architectural change:

1. •Check Imports: Run command uv run ruff check --select I (Import sorting/validation).
2. •Verify Coupling: Does src/core import src/ui? -> FORBIDDEN (Core cannot depend on UI).
3. •Verify Namespace: Are we polluting the namespace? (Avoid from module import *).

4. Troubleshooting

• •"ImportError: attempted relative import...": You ran a file directly (python file.py). ALWAYS run as module: uv run python -m src.package.file.