ludo-technologies/pyscn/architecture-review

Python Architecture Review with pyscn

Run the pyscn CLI to understand module structure and coupling. No install needed: uvx pyscn@latest <command>.

Commands

Useful flags: --min-cbo <n> (minimum CBO to report), --json (detailed report file). Report files are NOT written to stdout; they go to .pyscn/reports/ and the path is printed on completion.

Module Communities (context map for agents)

Module community detection is opt-in: run with --select communities --json and read the report file.

The JSON report includes community_analysis.community_context_map, a compact, deterministic map telling you which modules to inspect together:

• bundles[]: clusters of modules that change together. Each has modules, packages, risk_level, the cluster's bridge_modules, an optional suggested_review_scope (path prefix to focus a review on), and a one-line summary. Large bundles cap the module list with a ... +N more marker (module_count always holds the true total).
• bridge_modules[]: modules that couple two or more communities (module, the communities it connects, and a reason). Widen the review scope to include these when touching a bundle they connect.

Use the map to scope reviews and refactors: load all modules in a bundle together, and pull in connected bridge modules before changing cluster boundaries.

Interpreting Coupling Results

• High CBO classes depend on many others; changes ripple widely. Suggest interface extraction or dependency inversion.
• High LCOM4 classes bundle unrelated responsibilities; suggest splitting along the disconnected method groups.
• Dependency cycles are the highest-priority architectural issue; name the modules in each cycle and the weakest edge to break.

Always tie findings back to concrete modules and suggest a specific structural change.

MCP Alternative

If the pyscn-mcp MCP server is connected, you can use its tools instead of the CLI: check_coupling for CBO metrics, or analyze_code with analyses: ["deps"], ["lcom"], or ["communities"] (communities require output_mode: "full"; the full response includes the same community_context_map). Results are returned inline with no report files.