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):
     code

     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:
  typescript

  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