Domain: Architecture — Function Reference

⚠ HERITAGE EXTRACTION — donor AMS architecture domain (Wave 8 quarantine)

This file extracts the donor AMS src/domains/architecture/ module (deleted R53). The unified_architecture tool, the 5-layer classification, and the baseline-gate machinery are all donor surface — Phase 0 Colibri ships no unified_architecture tool and no architecture-introspection runtime. The 19 Phase 0 tools are listed in ../mcp-tools-phase-0.md; architecture observability is Phase 1+ territory.

Read this file as donor genealogy only.

Incremental modular-monolith observability for the Colibri source tree. Scans src/ to classify files into 5 architecture layers, parses static + dynamic imports, detects cross-layer violations against configurable rule sets (current rules vs. target rules), tracks file size maintainability, compares against a stored baseline, and generates a migration plan. All operations are compute-only and read-only (except baseline write).

MCP Tools Exposed

Exposed through unified controller. Key tool names: unified_architecture (sub-actions: status, violations, gate, module).

Tool Name	Description	Key Inputs	Returns
unified_architecture (status)	Full architecture report	none	{ architecture: { style, sourceRoot, moduleFileCount, importEdges, couplingTop, violations, maintainability, baseline, migrationPlan } }
unified_architecture (violations)	List specific violations	mode?: current\|target (default target), limit?: 1-2000	{ mode, total, violations[] }
unified_architecture (gate)	CI gate check vs baseline	allowedDelta?: 0, updateBaseline?: false	{ gate: { pass, delta, hasBaseline, ... } }
unified_architecture (module)	Details for one module	moduleName: string	{ details: { module, fileCount, files[], inbound, outbound, currentRuleAllows[], targetRuleAllows[] } }

Core Functions

getArchitectureStatus()

Purpose: Full architecture scan: file classification, import analysis, violation detection, coupling matrix, maintainability signals, baseline comparison. Returns: { success, architecture } — see schema below.

getArchitectureViolations(mode, limit)

Purpose: Return the violation list for the chosen rule mode. Parameters: mode: "current"|"target" (default "target"), limit: number (1-2000, default 200) Returns: { success, mode, total, violations[] } each with { fromFile, toFile, fromModule, toModule }.

getArchitectureGate(options)

Purpose: CI gate: compare current violations + oversized files against baseline. Pass if delta <= allowedDelta, no new oversized files, no tracked file growth. Parameters: options: { allowedDelta?: 0, updateBaseline?: false } Returns: { success, gate: { pass, allowedDelta, delta, hasBaseline, baselinePath, baselineTargetViolations, currentTargetViolations, baselineOversizedFiles, currentOversizedFiles, oversizedDelta, trackedGrowth[], baselineWarning, updatedBaseline, recommendation } } Side effects: If updateBaseline=true, writes config/architecture-baseline.json.

getArchitectureBaselinePath()

Purpose: Return the configured baseline file path (respects AMS_ARCH_BASELINE_PATH env var). Returns: string (normalized with forward slashes).

getArchitectureModule(moduleName)

Purpose: Return details for a single module layer. Parameters: moduleName: string Returns: { success, details: { module, fileCount, files[], inbound: { [fromModule]: count }, outbound: { [toModule]: count }, currentRuleAllows[], targetRuleAllows[] } }

Database Operations

None. Entirely filesystem-based.

Key Algorithms

Module Classification (classifyModule)

if file in { server.js, config.js }: return "composition"
for each { prefix, module } in MODULE_MATCHERS:
  if relativePath.startsWith(prefix): return module
return "unknown"

Module layers in dependency order:

• composition — server.js, config.js
• interface — controllers/, watchers/, dashboard/
• application — middleware/, tools/, gsd/, services/
• domain — domains/, analysis/, analytics/, claude/, intelligence/, validation/
• infrastructure — db/, utils/, metrics/, alerts/, websocket/, performance/, security/, config/

Import Parsing (parseImports)

static regex:  /from\s+["']([^"']+)["']/g
dynamic regex: /import\(\s*["']([^"']+)["']\s*\)/g
return unique Set of all matched specifiers

Import Resolution (resolveImportToSourcePath)

if importSpecifier does not start with ".": return null (external package)
raw = path.resolve(fromFile.dir, importSpecifier)
candidates = [raw, raw + ".js", raw + "/index.js"]
return first candidate where fs.existsSync and isFile

Violation Detection (evaluateViolations)

for each importEdge { fromModule, toModule }:
  allowedTargets = rules[fromModule]
  if toModule not in allowedTargets: violations.push(edge)

Current Rules (permissive — maintains backward compat)

composition → any
interface   → application, domain, infrastructure, composition, interface
application → domain, infrastructure, composition, application
domain      → domain, infrastructure, composition
infrastructure → infrastructure, composition

Target Rules (strict — goal state)

composition → any
interface   → application, domain, composition, interface (no direct infrastructure)
application → domain, composition, application (no direct infrastructure)
domain      → domain, composition (no infrastructure — must use ports)
infrastructure → infrastructure, composition

Coupling Matrix

moduleMatrix[fromModule][toModule] = count of import edges
pairs sorted descending by count = top coupling relationships

Maintainability Signals

DEFAULT_MAX_FILE_LINES = 1200
FILE_LINE_BUDGETS = specific overrides for large known files

for each .js file:
  lines = source.split(/\r?\n/).length
  budget = FILE_LINE_BUDGETS[relative] or DEFAULT_MAX_FILE_LINES
  if lines > budget: oversized.push({ file, lines, budget, overflow })
  if file in tracked: record actual line count

Migration Plan (buildMigrationPlan)

P0: canonical orchestration/architecture baselines wired → status: closed
P1: lock current boundaries → status: closed
P2: extract domain ports (domain→infrastructure violations) → open if count > 0
P3: move interface/application infra access behind services → open if count > 0
P4: adopt strict target rules as default gate → open if targetViolations > 0

Baseline File Schema (config/architecture-baseline.json)

{
  "version": 2,
  "updatedAt": "ISO8601",
  "style": "modular-monolith-incremental",
  "sourceRoot": "normalized/path",
  "totals": { "files": N, "importEdges": N },
  "violations": { "current": N, "target": N },
  "maintainability": {
    "defaultMaxLines": 1200,
    "oversizedCount": N,
    "trackedLineCounts": { "relative/path.js": N }
  }
}

Gate Pass Condition

pass = (currentTarget - baselineTarget <= allowedDelta)
     AND (currentOversized - baselineOversized <= 0)
     AND (trackedGrowth.length === 0)

trackedGrowth = files in FILE_LINE_BUDGETS whose current line count exceeds the baseline value.