Architecture & Design Auditor (L3 Worker)

Specialized worker auditing architecture principles and design patterns.

Purpose & Scope

• Worker in ln-620 coordinator pipeline - invoked by ln-620-codebase-auditor
• Audit architecture and design (Categories 3+4: High Priority)
• Check DRY/KISS/YAGNI violations, layer breaks, TODO/FIXME, workarounds, error handling
• Return structured findings with severity, location, effort, recommendations
• Calculate compliance score (X/10) for Architecture & Design category

Inputs (from Coordinator)

Receives contextStore with:

• tech_stack - detected tech stack (languages, frameworks)
• best_practices - researched best practices from MCP
• principles - project-specific principles from docs/principles.md
• codebase_root - root path of codebase

Domain-aware fields (NEW):

• domain_mode: "domain-aware" | "global" (optional, defaults to "global")
• current_domain: {name, path} when domain_mode="domain-aware"

Example contextStore (domain-aware):

{
  "tech_stack": {...},
  "best_practices": {...},
  "principles": {...},
  "codebase_root": "/project",
  "domain_mode": "domain-aware",
  "current_domain": {
    "name": "users",
    "path": "src/users"
  }
}

Workflow

1. Parse context from contextStore

   • Extract tech_stack, best_practices, principles
   • Determine scan_path (NEW):

     IF domain_mode == "domain-aware":
       scan_path = codebase_root + "/" + current_domain.path
       domain_name = current_domain.name
     ELSE:
       scan_path = codebase_root
       domain_name = null
     

2. Scan codebase for violations

   • All Grep/Glob patterns use scan_path (not codebase_root)
   • Example: Grep(pattern="TODO", path=scan_path)

3. Collect findings with severity, location, effort, recommendation

   • Tag each finding with domain: domain_name (if domain-aware)

4. Calculate score using penalty algorithm

5. Return JSON result to coordinator

   • Include domain and scan_path fields (if domain-aware)

Audit Rules (Priority: HIGH)

1. DRY Violations (Don't Repeat Yourself)

What: Duplicated logic, constants, or code blocks across files

Detection Categories:

1.1. Identical Code Duplication

• Search for identical functions (use AST comparison or text similarity)
• Find repeated constants: same value defined in multiple files
• Detect copy-pasted code blocks (>10 lines identical)

Severity:

• HIGH: Critical business logic duplicated (payment, auth)
• MEDIUM: Utility functions duplicated
• LOW: Simple constants duplicated (<5 occurrences)

1.2. Duplicated Validation Logic

What: Same validation patterns repeated across validators/controllers

Detection:

• Email validation: /@.*\./ regex patterns in multiple files
• Password validation: /.{8,}/, strength checks repeated
• Phone validation: phone number regex duplicated
• Common patterns: isValid*, validate*, check* functions with similar logic

Severity:

• HIGH: Auth/payment validation duplicated (inconsistency risk)
• MEDIUM: User input validation duplicated (3+ occurrences)
• LOW: Simple format checks duplicated (<3 occurrences)

Recommendation: Extract to shared validators module (validators/common.ts)

Effort: M (extract validators, update imports)

1.3. Repeated Error Messages

What: Hardcoded error messages instead of centralized error catalog

Detection:

• Grep for hardcoded strings in throw new Error("..."), res.status(400).json({ error: "..." })
• Find repeated messages: "User not found", "Invalid credentials", "Unauthorized access"
• Check for missing error constants file: errors.ts, error-messages.ts, constants/errors.ts

Severity:

• MEDIUM: Critical error messages hardcoded (auth, payment) - inconsistency risk
• MEDIUM: No centralized error messages file
• LOW: Same error message in <3 places

Recommendation:

• Create central error messages file (constants/error-messages.ts)
• Define error catalog: const ERRORS = { USER_NOT_FOUND: "User not found", ... }
• Replace hardcoded strings with constants: throw new Error(ERRORS.USER_NOT_FOUND)

Effort: M (create error catalog, replace hardcoded strings)

1.4. Similar Code Patterns (>80% Similarity)

What: Code with similar logic but different variable names/structure

Detection:

• Use fuzzy matching/similarity algorithms (Levenshtein distance, Jaccard similarity)
• Compare function bodies ignoring variable names
• Threshold: >80% similarity = potential duplication

Example:

// File 1
function processUser(user) { return user.name.toUpperCase(); }

// File 2
function formatUserName(u) { return u.name.toUpperCase(); }
// ✅ Same logic, different names - DETECTED

Severity:

• MEDIUM: Similar business logic (>80% similarity) in critical paths
• LOW: Similar utility functions (<3 occurrences)

Recommendation: Extract common logic, create shared helper function

Effort: M (refactor to shared module)

1.5. Duplicated SQL Queries

What: Same SQL queries/ORM calls in different controllers/services

Detection:

• Find repeated raw SQL strings: SELECT * FROM users WHERE id = ?
• ORM duplicates: User.findOne({ where: { email } }) in multiple files
• Grep for common patterns: SELECT, INSERT, UPDATE, DELETE with similar structure

Severity:

• HIGH: Critical queries duplicated (payment, auth)
• MEDIUM: Common queries duplicated (3+ occurrences)
• LOW: Simple queries duplicated (<3 occurrences)

Recommendation: Extract to Repository layer, create query methods

Effort: M (create repository methods, update callers)

1.6. Copy-Pasted Tests

What: Test files with identical structure (arrange-act-assert duplicated)

Detection:

• Find tests with >80% similar setup/teardown
• Repeated test data: same fixtures defined in multiple test files
• Pattern: beforeEach, afterEach with identical code

Severity:

• MEDIUM: Test setup duplicated in 5+ files
• LOW: Similar test utilities duplicated (<5 files)

Recommendation: Extract to test helpers (tests/helpers/*), use shared fixtures

Effort: M (create test utilities, refactor tests)

1.7. Repeated API Response Structures

What: Duplicated response objects instead of shared DTOs

Detection:

• Find repeated object structures in API responses:

  return { id: user.id, name: user.name, email: user.email }
  

• Check for missing DTOs folder: dtos/, responses/, models/
• Grep for common patterns: return { ... } in controllers

Severity:

• MEDIUM: Response structures duplicated in 5+ endpoints (inconsistency risk)
• LOW: Simple response objects duplicated (<5 endpoints)

Recommendation: Create DTOs/Response classes, use serializers

Effort: M (create DTOs, update endpoints)

---

Overall Recommendation for DRY: Extract to shared module, create utility function, centralize constants/messages/validators/DTOs

Overall Effort: M (refactor + update imports, typically 1-4 hours per duplication type)

2. KISS Violations (Keep It Simple, Stupid)

What: Over-engineered abstractions, unnecessary complexity

Detection:

• Abstract classes with single implementation
• Factory patterns for 2 objects
• Deep inheritance (>3 levels)
• Generic types with excessive constraints

Severity:

• HIGH: Abstraction prevents understanding core logic
• MEDIUM: Unnecessary pattern (factory for 2 types)
• LOW: Over-generic types (acceptable tradeoff)

Recommendation: Remove abstraction, inline implementation, flatten hierarchy

Effort: L (requires careful refactoring)

3. YAGNI Violations (You Aren't Gonna Need It)

What: Unused extensibility, dead feature flags, premature optimization

Detection:

• Feature flags that are always true/false
• Abstract methods never overridden
• Config options never used
• Interfaces with single implementation (no plans for more)

Severity:

• MEDIUM: Unused extensibility points adding complexity
• LOW: Dead feature flags (cleanup needed)

Recommendation: Remove unused code, simplify interfaces

Effort: M (verify no future use, then delete)

4. Layer Boundary Breaks

What: Architectural layers violated (UI calling DB directly, Controller bypassing Service, etc.)

Detection:

• Grep for direct DB calls in UI/presentation layer
• Grep for Repository imports in Controllers:
  • Pattern: import.*Repository.*from in files matching *Controller.*, *controller.*, *Controller.ts, *Controller.js, *controller.py
• Check for concrete class dependencies instead of interfaces/abstractions
• Verify separation: Controller → Service → Repository → DB (Clean Architecture dependency rule)

Severity:

• CRITICAL: UI directly accessing database (bypass all layers)
• CRITICAL: Controller directly using Repository (skip Service layer)
• HIGH: Business logic in presentation layer
• HIGH: Dependency on concrete classes instead of interfaces (violates Dependency Inversion Principle)
• MEDIUM: Tight coupling between layers

Recommendation:

• Add service layer between Controller and Repository
• Use Dependency Inversion Principle: depend on interfaces/abstractions, not concrete implementations
• Refactor to proper layering (Controller → Service → Repository → DB)

Effort: L (architectural refactor)

5. TODO/FIXME/HACK Comments

What: Unfinished work, temporary solutions

Detection:

• Grep for TODO, FIXME, HACK, XXX, OPTIMIZE
• Check age (git blame) - old TODOs are higher severity

Severity:

• HIGH: TODO in critical path (auth, payment) >6 months old
• MEDIUM: FIXME/HACK with explanation
• LOW: Recent TODO (<1 month) with plan

Recommendation: Complete TODO, remove HACK, refactor workaround

Effort: Varies (S for simple TODO, L for architectural HACK)

6. Missing Error Handling

What: Critical paths without try-catch, error propagation

Detection:

• Find async functions without error handling
• Check API routes without error middleware
• Verify database calls have error handling

Severity:

• CRITICAL: Payment/auth without error handling
• HIGH: User-facing operations without error handling
• MEDIUM: Internal operations without error handling

Recommendation: Add try-catch, implement error middleware, propagate errors properly

Effort: M (add error handling logic)

7. Centralized Error Handling

What: Errors handled inconsistently across different contexts (web requests, cron jobs, background tasks)

Detection:

• Search for centralized error handler class/module: ErrorHandler, errorHandler, error-handler.ts/js/py
• Check if error middleware delegates to handler: errorHandler.handleError(err) or similar
• Verify all async routes use promises or async/await (Express 5+ auto-catches rejections)
• Check for error transformation (sanitize stack traces for users in production)
• Anti-pattern check: Look for process.on("uncaughtException") usage (BAD PRACTICE per Express docs)

Severity:

• HIGH: No centralized error handler (errors handled inconsistently in multiple places)
• HIGH: Using uncaughtException listener instead of proper error propagation (Express anti-pattern)
• MEDIUM: Error middleware handles errors directly (doesn't delegate to central handler)
• MEDIUM: Async routes without proper error handling (not using promises/async-await)
• LOW: Stack traces exposed in production responses (security/UX issue)

Recommendation:

• Create single ErrorHandler class/module for ALL error contexts
• Middleware should only catch and forward to ErrorHandler (delegate pattern)
• Use async/await for async routes (framework auto-forwards errors)
• Transform errors for users: hide sensitive details (stack traces, internal paths) in production
• DO NOT use uncaughtException listeners - use process managers (PM2, systemd) for restart instead
• For unhandled rejections: log and restart process (use supervisor, not inline handler)

Effort: M-L (create error handler, refactor existing middleware)

8. Dependency Injection / Centralized Init

What: Direct imports/instantiation instead of dependency injection, scattered initialization

Detection:

• Check for DI container usage:
  • Node.js: inversify, awilix, tsyringe, typedi packages
  • Python: dependency_injector, injector packages
  • Java: Spring @Autowired, @Inject annotations
  • .NET: Built-in DI in ASP.NET Core, IServiceCollection
• Grep for direct instantiations in business logic: new SomeService(), new SomeRepository()
• Check for centralized Init/Bootstrap module: bootstrap.ts, init.py, Startup.cs, app.module.ts
• Verify controllers/services receive dependencies via constructor/parameters, not direct imports

Severity:

• MEDIUM: No DI container (hard to test, tight coupling, difficult to swap implementations)
• MEDIUM: Direct instantiation in business logic (new Service() in controllers/services)
• LOW: Mixed DI and direct imports (inconsistent pattern)

Recommendation:

• Use DI container for dependency management (Inversify, Awilix, Spring, built-in .NET DI)
• Centralize initialization in Init/Bootstrap module
• Inject dependencies via constructor/parameters (dependency injection pattern)
• Never use direct instantiation for business logic classes (only for DTOs, value objects)

Effort: L (refactor to DI pattern, add container, update all instantiations)

9. Missing Best Practices Guide

What: No architecture/design best practices documentation for developers

Detection:

• Check for architecture guide files:
  • docs/architecture.md, docs/best-practices.md, docs/design-patterns.md
  • ARCHITECTURE.md, CONTRIBUTING.md (architecture section)
• Verify content includes: layering rules, error handling patterns, DI usage, coding conventions

Severity:

• LOW: No architecture guide (harder for new developers to understand patterns and conventions)

Recommendation:

• Create docs/architecture.md with project-specific patterns:
  • Document layering: Controller→Service→Repository→DB
  • Error handling: centralized ErrorHandler pattern
  • Dependency Injection: how to add new services/repositories
  • Coding conventions: naming, file organization, imports
• Include examples from existing codebase
• Keep framework-agnostic (principles, not specific implementations)

Effort: S (create markdown file, ~1-2 hours documentation)

Scoring Algorithm

penalty = (critical * 2.0) + (high * 1.0) + (medium * 0.5) + (low * 0.2)
score = max(0, 10 - penalty)

Output Format

Return JSON to coordinator:

Global mode output:

{
  "category": "Architecture & Design",
  "score": 6,
  "total_issues": 12,
  "critical": 2,
  "high": 4,
  "medium": 4,
  "low": 2,
  "findings": [...]
}

Domain-aware mode output (NEW):

{
  "category": "Architecture & Design",
  "score": 6,
  "domain": "users",
  "scan_path": "src/users",
  "total_issues": 12,
  "critical": 2,
  "high": 4,
  "medium": 4,
  "low": 2,
  "findings": [
    {
      "severity": "CRITICAL",
      "location": "src/users/controllers/UserController.ts:45",
      "issue": "Controller directly uses Repository (layer boundary break)",
      "principle": "Layer Separation (Clean Architecture)",
      "recommendation": "Create UserService, inject into controller",
      "effort": "L",
      "domain": "users"
    },
    {
      "severity": "HIGH",
      "location": "src/users/services/UserService.ts:45",
      "issue": "DRY violation - duplicate validation logic",
      "principle": "DRY Principle",
      "recommendation": "Extract to shared validators module",
      "effort": "M",
      "domain": "users"
    }
  ]
}

Critical Rules

• Do not auto-fix: Report only
• Domain-aware scanning: If domain_mode="domain-aware", scan ONLY scan_path (not entire codebase)
• Tag findings: Include domain field in each finding when domain-aware
• Context-aware: Use project's principles.md to define what's acceptable
• Age matters: Old TODOs are higher severity than recent ones
• Effort realism: S = <1h, M = 1-4h, L = >4h

Definition of Done

• contextStore parsed (including domain_mode and current_domain)
• scan_path determined (domain path or codebase root)
• All 9 checks completed (scoped to scan_path):
  • DRY (7 subcategories), KISS, YAGNI, Layer Breaks, TODOs, Error Handling, Centralized Errors, DI/Init, Best Practices Guide
• Findings collected with severity, location, effort, recommendation, domain
• Score calculated
• JSON returned to coordinator with domain metadata

Reference Files

• Architecture rules: references/architecture_rules.md

---

Version: 4.0.0 Last Updated: 2025-12-23