decomposition

Decomposition Rules

Files grow. Without a rule, they grow until grep is the only navigation tool. These rules tell you exactly when to split, and how to split safely.

File Size Limits

LOC range	State	Action required
0–400	Green	None.
400–600	Yellow	Plan a split. Add # TODO(decompose): A1 — split by ... header.
600+	Red	Block the merge. Decompose first.

CI runs python scripts/check_loc.py app/ and fails on any file > 600 LOC.

When to Convert a File into a Package

Convert <file>.py into <file>/ when any is true:

• Crosses 400 LOC and the next change would push it past 500.
• Contains 2+ disjoint sub-domains (image vs video, user vs admin).
• Mixes HTTP handlers with worker handlers.
• Mixes Pydantic schemas + auth deps + route handlers.
• Has 2+ callers each importing only one symbol — the split lines are obvious.

How to Split Safely (Atomic PR Pattern)

1. Create the package. <file>/__init__.py is empty for now.

2. Move disjoint pieces to sub-files (a.py, b.py, c.py).

3. Re-export old public names from __init__.py:

   # services/wallet/__init__.py
   from .user import WalletUserService
   from .admin import WalletAdminService
   
   # backwards-compat alias for old imports
   WalletService = WalletUserService
   
   __all__ = ["WalletUserService", "WalletAdminService", "WalletService"]
   

4. Run tests — they must pass without changes.

5. Open a follow-up PR to migrate callers off the legacy alias. Once it lands, delete the alias.

Static Data Separation

Static data goes in app/data/ (project-wide) or <domain>/registry.py (domain-local). Never inline:

# ❌ BAD — pricing constants tangled into service file
class AIService:
    PRICING = {
        "gpt-4o":     Decimal("0.005"),
        "claude-3-5": Decimal("0.003"),
        # ... 80 more lines ...
    }
    async def generate(self, ...): ...