90% of linters catch style. They tell you that your line is 81 characters or that you forgot a docstring. What they don't tell you is that your payments/ module has zero tests, three circular imports, and a god class that 14 other files depend on — and that the last team with this exact pattern had a 4-hour outage that cost them €47,000.

The Incident That Started It

Two years ago I was building a data pipeline. Kafka → Python workers → ClickHouse. Standard stack, nothing exotic. We had pylint, mypy, bandit, the whole CI choir. Green builds, 94% coverage, everyone happy.

Then one Tuesday at 3:14 AM, the ingestion worker froze. Not crashed — froze. Kafka lag grew to 2 million messages. ClickHouse started rejecting writes. By 6 AM the dashboard was a red wall and the CTO was in the war room.

Root cause? A single Python file — ingestion/handlers.py — had grown to 1,800 lines. It imported 23 other modules, 4 of them circularly. When one handler threw an exception, the cleanup logic (also in the same file) tried to close a connection that was still held by the circular import path. Deadlock.

We had 11 linting tools. None of them flagged "this file is too big" or "these imports form a cycle." Because that's not their job. Their job is style, types, and security — not architecture.

What ArchDogma Actually Does

ArchDogma is an architectural linter. It doesn't care about your quotes or your type hints. It cares about:

  • Circular imports — the silent killer of startup time and testability
  • God modules — files that grew so big they became single points of failure
  • Tight coupling — when 12 files depend on one internal class, refactoring becomes surgery
  • Missing tests on critical paths — because coverage percentage is a lie if payment logic has 0%
  • Dead code clusters — functions no one calls but everyone is afraid to delete

Every finding comes with a link to a real postmortem. Not a vague "best practice" — an actual incident: what broke, why, how long it took to fix, and what the code looked like before it blew up.

Real Output on Real Code

Here's what archdogma scan . looks like on a mid-size Django project:

$ archdogma scan . --severity=high

✓ scanned 47 files, 12 detectors

⚠ ARCH001  circular_import
  utils.py:12 imports models.py
  models.py:8 imports utils.py
  → cycle: 2 files, 7 functions affected
  [postmortem: pm-2024-003-ring-buffer-deadlock]

⚠ ARCH005  god_module
  views.py: 1,247 lines, 14 classes, 37 public functions
  → 14 other files import from this module directly
  [postmortem: pm-2023-011-monolith-handler-freeze]

⚠ ARCH009  missing_tests
  payments/ directory: 0% coverage, 2,400 lines of code
  → 14 past incidents linked to untested payment paths
  [postmortem: pm-2025-001-checkout-race-condition]

⚠ ARCH012  tight_coupling
  db_session created in handler.py:142
  passed to 6 downstream functions (never mocked in tests)
  → average test runtime: 4.2s per case (DB hits)
  [postmortem: pm-2024-007-test-suite-timeout]

Each [postmortem] link opens a one-page incident report: what the code looked like, what the trigger was, how long the outage lasted, and the exact refactor that prevented recurrence. No theory — just scars.

Why This Isn't Just Another Linter

Pylint tells you what is wrong with your style. Mypy tells you what is wrong with your types. Bandit tells you what is wrong with your security.

ArchDogma tells you when your architecture is about to cost you money. It links each smell to a real incident with a real dollar amount. The postmortem catalog currently has 14 cases, and every one of them started with a code pattern that a standard linter would ignore.

The difference is context. A 1,200-line file isn't always bad. But a 1,200-line file that 14 other modules import directly, that has zero tests, and that handles payment state transitions — that's a bomb with a timer. ArchDogma knows the difference because it reads the whole graph, not just one file.

The Pro Kit: From Open Source to Revenue

The open-source core (pip install archdogma) is free forever. It has 12 Tier 1 detectors, whole-project scanning, JSON output, and GitHub Actions integration. Use it. Abuse it. Ship it.

But if you want the postmortem catalog, the team-size configs, and the step-by-step CI setup guide, that's the ArchDogma Pro Kit.

  • Consultation (150€) — 2-hour Zoom. I run ArchDogma on your repo live. You get 5–10 real issues with file:line context, prioritized fix list, and a CI blueprint for your stack.
  • Self-Service Pack (49€) — Course + templates + postmortem catalog + lifetime updates. Set up architecture auditing in CI in one day.
  • Enterprise (from 400€) — Custom detectors, private postmortem ingestion, team onboarding, Slack support.

Two consultations a week = 50€/day. That's the goal. Everything else is documentation.

What I Want You To Do Now

If you've ever been woken up at 3 AM by a code pattern that "should have been obvious in hindsight," try this: 

pip install archdogma
archdogma scan . --severity=high

Look at the first finding. Click the postmortem link. Read the incident. Then ask yourself: could this happen to us?

If the answer is yes — book a consultation or grab the Self-Service Pack. Architecture doesn't lie. You just need to ask it the right questions.