go-navigator-architecture-explorer

name: go-navigator-architecture-explorer description: Use Go Navigator MCP to map Go service architecture (layers, boundaries, dependencies), detect coupling/cycles, and flag layer violations (domain <-> transport/storage); do not modify code

Go Navigator — Architecture Explorer (READ)

Purpose

Answer quickly:

• How packages/layers are organized
• Where dependency boundaries are violated
• Where cycles/coupling hotspots exist

Scope rules

• READ-ONLY: never call renameSymbol or rewriteAst.
• Prefer semantic tools over ad-hoc text search.
• Focus on internal architecture; external deps are context only.

Defaults

• Use "dir": "." unless user specifies another root.
• If package is needed, use exact path from listPackages.
• For architecture analysis, default to "testScope": "exclude" to reduce noise.
• Switch to "testScope": "include" only when debugging test-induced coupling.
• Depth:
  • summary (default): overview + key risks
  • standard: + graph stats + boundary checks
  • deep: + evidence and hotspot details

Quick decision matrix

• Need fast map of repo shape: listPackages (+ optional getProjectSchema)
• Need coupling/cycles: getDependencyGraph
• Need runtime-level function coupling: callGraph
• Need boundary violations: listImports + targeted getFileInfo
• Need port/adapter quality: listInterfaces + getImplementations

Core workflow

1) Map packages and candidate layers

1. listPackages { "dir": ".", "testScope": "exclude" }
2. Optional: getProjectSchema { "dir": ".", "depth": "standard", "testScope": "exclude" }

Layer heuristics by path keywords:

• cmd/ -> entrypoints
• domain|model|entities -> domain
• service|usecase|app -> application/service
• transport|http|grpc|handler|api -> transport
• storage|repo|postgres|mysql|redis|kafka -> infrastructure
• pkg/ -> shared libraries

2) Analyze dependencies and hotspots

• getDependencyGraph { "dir": ".", "testScope": "exclude" }
• If user asks about one area: pass "package" filter.
• For critical symbols in hotspot packages:
  • callGraph { "dir": ".", "ident": "<FuncOrMethod>", "direction": "both", "maxDepth": 2, "testScope": "exclude" }

Extract:

• cycles
• top fan-in packages (bottlenecks)
• top fan-out packages (god-packages/orchestrators)
• high-degree function hubs (from callGraph node/edge density)

3) Boundary checks

• listImports { "dir": ".", "package": "<pkg>", "testScope": "exclude" }
• For suspicious edges, inspect files with real schema:
  • getFileInfo { "dir": ".", "file": "<file>", "options": { "withComments": true } }

Default boundary rules (override if user provides custom rules):

• domain must not import transport/storage
• service should depend on domain abstractions
• transport/storage should implement adapters around domain/service

4) Interface boundary quality

• listInterfaces { "dir": ".", "package": "<pkg>", "testScope": "exclude" }
• getImplementations { "dir": ".", "name": "<InterfaceName>", "testScope": "exclude" }

Output guidance

For summary requests:

• short summary (3–6 bullets)
• layer map
• top risks (cycles/hotspots/violations)

For standard|deep:

• include evidence files/lines
• include concrete refactor directions

Do not force a heavy template for short user questions.