ArchDogma
Architectural Dogma Detector
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.
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 tells you which rules you're following too hard, where they've stopped serving you, and what the cost is. Eleven detectors. Honest output. No false comfort.
The Eleven Dogmas
Patterns that started as wisdom and became religion. Detected automatically.
dry_dogma
DRY applied past the point where duplication was the actual problem.
tdd_dogma
Test-first as ritual, not design tool. Tests that describe implementation, not behaviour.
microservices_dogma
Distributed system added before the monolith was a bottleneck. Network calls where function calls belonged.
clean_arch_dogma
Layer boundaries enforced so strictly the code fights to get anything done.
solid_dogma
SOLID principles applied individually, not as a system — especially ISP and DIP gone wrong.
immutability_dogma
Immutable-everything in a domain where mutation is the correct model. Performance and clarity both suffer.
deep_nesting
Cognitive depth that no review catches because each level looks reasonable alone.
god_function
Functions that know too much. The ones nobody touches because nobody fully understands them.
long_function
Length as a proxy for complexity. Correlated but not the same thing — and both matter.
too_many_params
Signatures that are honest about a missing abstraction. The function is doing too many things.
premature_optimization
Complexity added for a performance problem that hasn't been measured.
Design Principles
Zero Dependencies
Pure Python stdlib. No graph of transitive risk. Installs in 2 seconds.
Honest Output
Violations with context, not just line numbers. Explains the cost, not just the rule.
Incomplete on Purpose
11 dogmas, not 111. A tool that catches real patterns beats one that cries wolf.
Strict Typing
100% typed. mypy strict. The codebase enforces what the tool preaches.
Getting Started
Installation
pip install archdogma # PyPI — coming soon
# or from source:
git clone https://github.com/LodsterSwamp/ArchDogma
cd ArchDogma && pip install -e .Usage
archdogma scan ./src # scan a directory
archdogma scan . --json # machine-readable output
archdogma list # list all detectors
archdogma explain dry_dogma # detailed explanationPython 3.11+. No dependencies. Works on any codebase.
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. Eleven well-specified dogmas, each with evidence and cost analysis, beats a comprehensive catalogue of noise.
Tech Stack
Current Status
v0.1.0 — Active Development
4 Tier-1 detectors active (deep nesting, god function, long function, too many params). 3 dogma detectors complete (DRY, TDD, Microservices). PyPI release planned when core catalogue hits 6/11.
- GitHub org: LodsterSwamp — coming soon
- PyPI:
pip install archdogma— coming soon - Announce blog post — planned for org launch