Architecture Enforcement All Tiers

Maintain code quality and prevent complexity creep

Overview

The architecture enforcement system checks code against configurable thresholds:

  • Files stay under size limits
  • Functions remain focused and small
  • Modules don't accumulate too many functions
  • Import complexity stays manageable

Quick Start

bash 
# Check a specific file
bpsai-pair arch check src/myfile.py

# Check an entire directory
bpsai-pair arch check src/

# Get split suggestions for a large file
bpsai-pair arch suggest-split src/large_file.py

Configuration

Architecture thresholds are configured in .paircoder/config.yaml:

yaml 
architecture:
  thresholds:
file_lines:
  error: 400      # Files over 400 lines trigger error
  warning: 200    # Files over 200 lines trigger warning
function_lines: 50  # Functions over 50 lines trigger error
functions_per_file: 15  # More than 15 functions trigger error
imports: 20         # More than 20 imports trigger error

  exclude_patterns:
- "**/tests/**"      # Test files often need many functions
- "**/__init__.py"   # Init files aggregate exports
- "**/migrations/**" # Generated migrations

Thresholds Explained

File Lines (400 error / 200 warning)

Large files indicate too many responsibilities, are hard to navigate, difficult to test, and prone to merge conflicts.

Fix: Use arch suggest-split to identify extraction candidates.

Function Lines (50 max)

Long functions indicate complex logic, poor abstraction, and are hard to test.

Fix: Extract helper functions, use early returns, separate concerns.

Functions per File (15 max)

Many functions indicate the file is doing too much with mixed responsibilities.

Fix: Group related functions into separate modules.

Imports (20 max)

Many imports indicate high coupling and too many dependencies.

Fix: Review if all imports are needed, consider dependency injection.

Hub Pattern

Large modules become "hubs" that re-export from smaller modules:

python 
# Before: large_module.py (800 lines)
class ClassA: ...
class ClassB: ...

# After: large_module/__init__.py (hub)
"""Hub module for large_module. Re-exports public API."""
from .class_a import ClassA
from .class_b import ClassB

__all__ = ["ClassA", "ClassB"]

CI Integration

yaml 
# .github/workflows/arch-check.yml
name: Architecture Check
on: [push, pull_request]

jobs:
  arch-check:
runs-on: ubuntu-latest
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-python@v5
    with:
      python-version: '3.11'
  - run: pip install bpsai-pair
  - run: bpsai-pair arch check src/