ArchDogma

Architectural Dogma Detector

Active On PyPI v0.5.0

A Python CLI that catches the architectural dogmas slowly killing your project. Not linting. Not formatting. The beliefs that feel like best practices until they don't.

GitHub pip install archdogma

What It Actually Does

You've read Clean Architecture. You follow SOLID. You do TDD. And your project is still a mess — because the rules that saved the last codebase are destroying this one.

ArchDogma doesn't tell you to follow rules. It documents who followed each rule and where it broke them — every case with a verifiable source — then finds the same shapes in your code. Twenty detectors across three tiers: single functions (AST), module structure (import graph), and change history (git). Honest output. No false comfort.

$ archdogma modules src/

src/archdogma/probe/tags/tier1.py archdogma.probe.tags.tier1

Ca=5 Ce=0 I=0.00 · 609 SLOC · 33 defs · 8 commits · last change 95d ago

[god-module] 609 SLOC across 33 top-level definitions. A file this wide has no single reason to change, so every reason to change lands in it.

[churn-hotspot] 609 SLOC changed across 8 commits — top 4% of this repository by change frequency.

21 modules · 30 internal imports · 0 cycle(s) · 3 tag(s) in 2 module(s)

↑ This is ArchDogma scanning itself. The god-module is ours — left standing, asserted in a test. A catalog of other people's failures that exempts itself would be the dogma it documents.

Twenty Detectors, Three Tiers

Each tier answers a question the one below it structurally cannot ask. Every tag links back to a catalog entry with sourced failure cases.

Tier 1 — one function or class

deep-nesting · long-function · god-function · too-many-params · if-on-parameter · magic-numbers · dynamic-magic · broad-except · mutable-default-arg · too-many-returns · god-class · deep-inheritance

● 12 active

Tier 2 — the import graph

circular-import · hub-module · god-module · unstable-dependency. Coupling, cycles, and whether dependencies point where the folder names claim.

● 4 active

Tier 3 — structure × git history

load-bearing-wall · churn-hotspot · single-author-hub · temporal-coupling. The file everything depends on that nobody has touched in years. The pair that changes together with no import between them.

● 4 active

The catalog — 12 dogmas, 22 candidates

DRY, TDD, SOLID, Clean Architecture, KISS, microservices and more — 10 of 12 filled with fetch-verified failure cases: Segment, Discord, GFS, Go generics, Basecamp, Neversoft…

● archdogma explain <anything>

microservices — no detector, deliberately

The Segment failure lives in deployment topology and shared databases. A Python import graph cannot see it, and the catalog says so instead of shipping a guess wearing a tag name.

◌ honest gap

Design Principles

Stdlib Analyzers, Two-Dependency Core

The analyzers are pure stdlib. The package pulls exactly click and pyyaml; rich and TTS are opt-in extras.

Honest Output

Every finding carries the conditions under which its rule breaks, and links to a documented case of a real team paying for it.

Incomplete on Purpose

12 dogmas, not 200 — and where a dogma can't be detected honestly, the catalog says so instead of shipping a guess.

Strict Typing

100% typed. mypy strict. The codebase enforces what the tool preaches.

Getting Started

Installation

pip install archdogma        # v0.5.0 on PyPI · Python 3.11+
# or from source:
git clone https://github.com/gaidar0yegor/ArchDogma
cd ArchDogma && pip install -e .

Usage

archdogma scan src/               # Tier 1: every function and class
archdogma modules src/            # Tiers 2+3: imports x git history
archdogma scan . --format json    # machine-readable, catalog context included
archdogma explain dry            # the rule, its origin, who paid, when to break it
archdogma explain circular-import --speak   # voice mode, day one

Python 3.11+. Two dependencies (click, pyyaml). Tier 3 needs a git work tree — without one it says so instead of guessing.

Why It Exists

Linters catch bugs.
ArchDogma catches beliefs.

Pylint will tell you about an unused import. It won't tell you that your microservices architecture is 80% network overhead because you split a monolith that had no scaling problem.

The catalog is incomplete.
That's the point.

A tool with 200 checks is a tool nobody reads. Twelve well-specified dogmas — ten filled with sourced, fetch-verified failure cases — beat a comprehensive catalogue of noise. Where evidence is missing, the entry says so.

Tech Stack

Python 3.11+ Zero Dependencies mypy strict AST Analysis pytest pyproject.toml

Current Status

v0.5.0 — On PyPI

Three analysis tiers (AST, import graph, git history), the explain mentor command, agent-ready JSON that carries the catalog's break-conditions with every finding, CI on Python 3.11–3.13, 496 tests. Catalog: 12 dogmas, 10 filled with fetch-verified failure cases.

GitHub: gaidar0yegor/ArchDogma
PyPI: pip install archdogma — v0.5.0 live, piwheels builds included
Launch write-up: ArchDogma: Python Architecture Linting That Doesn't Lie

Free. That's the Model.

The scanner, the catalog, the MCP server and the contracts checker are MIT, free for private code, no tokens, no cloud. If ArchDogma helps you, the contribution that matters most is a sourced postmortem — open an issue with the postmortem label.