DEV Community: Piyush Anand

Stop your Flutter architecture from drifting: layer rules and cycle checks in your IDE and CI with arch_guard

Piyush Anand — Sun, 11 Oct 2026 12:27:15 +0000

Every Flutter project I've worked on started with a clean folder structure: domain, data, presentation, maybe a features/ folder. And on every one, six months later, a widget was importing a repository implementation directly, and two services imported each other.

Nobody did it on purpose. A deadline, a quick fix, a review that missed one import line. The analyzer doesn't care, the tests pass, and the architecture diagram in the wiki is now fiction.

So I built arch_guard: a CLI, Dart library and analyzer plugin that reads every import, export and part in your project and tells you when the code no longer matches the architecture you designed: in the editor as you type, in dart test, and in CI.

Try it in 30 seconds

dart pub add --dev arch_guard
dart run arch_guard init     # detects your layout and writes arch_guard.yaml
dart run arch_guard          # checks the project

init looks at your folders and picks a preset: Clean Architecture, Riverpod, Bloc or feature-first. It then previews the first scan: how many files landed in each layer, what's already broken, and what to do next.

What it checks

1. Layer rules

The simplest config is one line:

# arch_guard.yaml
preset: clean_architecture

That means domain may only import core, and presentation may not import data. When something breaks a rule, you get the file, the line, and the rule:

❌ Layer Violation: [presentation] lib/features/auth/presentation/page.dart:3 -> [data] lib/features/auth/data/repo.dart
   Rule: `presentation` may only import `core`, `domain`, `presentation`.

The other presets:

riverpod: domain imports nothing else; data never imports application or presentation.
bloc: UI → bloc/cubit → repository → data provider, with models usable everywhere.
feature_first: each folder in lib/features becomes its own layer, and a feature may import only itself and shared code. This is the one I find catches the most: features quietly reaching into each other.

Presets are a starting point. Override just the part you disagree with:

preset: clean_architecture
layers:
  presentation:
    allowed_imports: [core, domain, presentation, data]   # we allow UI -> data here

2. Forbidden packages

Some rules aren't about your own folders. "The domain layer must not know about Flutter" is a package rule:

forbidden_packages: [dio]            # nowhere in the project
layers:
  domain:
    forbidden_packages: [flutter, "dart:io", "firebase_*"]

3. Circular dependencies, with a fix

arch_guard runs Tarjan's algorithm over the import graph and reports every group of files that import each other, with fan-in/fan-out, instability and the "hub" files. Each cycle also names the one import to remove:

Strongly Connected Component #1 (2 files)
  Representative Cycle Path:
  lib/widgets/nav.dart
  -> lib/screens/home.dart
  -> lib/widgets/nav.dart
  Suggested fix: remove lib/screens/home.dart:1 -> lib/widgets/nav.dart (breaks the cycle)

max_scc_size: 5 fails the run if a cycle group grows beyond 5 files, and dart run arch_guard --explain <file> shows why a file is in one.

4. Coupling limits and monorepos

metrics: { max_fan_out: 20, max_fan_in: 30 } stops files from turning into hubs; reports list the most coupled files.
In a Dart workspace or Melos-style packages/ + apps/ repo, workspace_rules say which packages may depend on which (apps/* → packages/*, never the reverse), and cycles across package boundaries are found too.

5. A graph you can actually look at

dart run arch_guard -f html -o build/reports

gives you an interactive graph that works offline. There's also Mermaid (paste it into a PR or README), Graphviz DOT and JSON.

In your editor

CI catching a bad import is good; never writing it is better. The companion
arch_guard_lint analyzer plugin reads the same arch_guard.yaml and underlines the import in VS Code, Android Studio and dart analyze:

# analysis_options.yaml (Dart 3.10 / Flutter 3.38+)
plugins:
  arch_guard_lint: ^0.2.0

[IDE clip: underlined import → quick fix]

layer_violation and forbidden_package on the offending import.
circular_dependency on the one import that closes each cycle, updated as you type, including unsaved changes.
Quick fixes: Remove this import, or Allow layer X to import Y, which edits allowed_imports in your config for you. There's deliberately no "allow" fix for forbidden packages: loosening a "never" rule should be a conscious edit.

In your tests

If you'd rather keep architecture rules next to the code, they also run in dart test / flutter test:

import 'package:arch_guard/testing.dart';
import 'package:test/test.dart';

void main() {
  test('architecture', () async {
    await expectArchitecture();
  });
}

It fails exactly when the CLI would, with a readable list of problems.

Adopting it on a codebase that's already messy

This was the part I cared most about. If a tool reports 200 violations on day one, it gets uninstalled on day one.

dart run arch_guard --update-baseline
git add arch_guard_baseline.json

That records today's problems. From then on, CI fails only on new cycles and violations (the IDE plugin stays quiet about baselined ones too). When someone fixes an old one, arch_guard tells you, so you can tighten the baseline and stop it from coming back.

For big PRs on big apps, --since origin/main reports only problems touching files changed on the branch, while still analysing the whole project.

Running it on every pull request

# .github/workflows/architecture.yml
name: Architecture
on: [pull_request]
permissions:
  contents: read
  pull-requests: write
jobs:
  arch_guard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: creatorpiyush/arch_guard@v1.8.0

The action downloads a checksum-verified binary (no Dart SDK setup), keeps a single PR comment up to date, and can upload SARIF so violations show up in GitHub Code Scanning. There's also a pre-commit hook and recipes for lefthook, plain git hooks and GitLab CI.

How it compares

DCM is a full linting suite with hundreds of rules and IDE integration; its free tier covers one seat up to 50k LOC. If you already use it, its banned-imports rule covers part of this.
import_lint shows import rules right in your editor as an analyzer plugin.
lakos focuses on graph metrics and DOT/JSON output.

arch_guard does one job: make architecture rules easy to adopt (presets, init, baselines) and enforce them everywhere you work: editor, tests and every PR.

Links

📦 pub.dev: https://pub.dev/packages/arch_guard and https://pub.dev/packages/arch_guard_lint
📖 Docs (a recipe per architecture): https://creatorpiyush.github.io/arch_guard/
🧪 Examples (one small project per feature, with real output): https://github.com/creatorpiyush/arch_guard/blob/main/example/example.md
⭐ GitHub: https://github.com/creatorpiyush/arch_guard

It's MIT-licensed. If your project uses a layout none of the presets fit, I'd really like to hear about it: open an issue or leave a comment with your folder structure, and I'll look at adding a preset.

Why your webhook signature check fails (and the bugs that pass it)

Piyush Anand — Sat, 03 Oct 2026 13:07:05 +0000

In July I wrote about why I built verihook: every provider signs webhooks differently, and I was tired of maintaining five slightly different HMAC functions. Since then verihook has grown to 40+ providers, adapters for ten frameworks, testing helpers and a docs site.

Supporting that many providers taught me where webhook verification actually goes wrong. It's rarely the HMAC. It's everything around it: the body, the secret, the URL, retries and tests. Here are the five mistakes I see most, including the worse ones that make verification pass when it shouldn't.

1. The body parser ate your signature

This is the most common failure by far:

app.use(express.json());

app.post('/webhooks/stripe', (req, res) => {
  const payload = JSON.stringify(req.body); // not the bytes Stripe signed
  // signature check fails with the right secret
});

The provider signed the exact bytes it sent. JSON.stringify(JSON.parse(body)) changes whitespace, escapes (é vs é) and number formatting. The fix is to verify the raw body before any parser runs: express.raw(), await request.text(), Fastify's rawBody, NestJS's rawBody: true.

verihook spots this case. When the body's size doesn't match content-length, the result says so:

const result = await verifyWebhook('stripe', req, secret);
// result.code: "INVALID_SIGNATURE"
// result.hint: "The body is 412 bytes but content-length is 431: it was modified
//   before verification, usually parsed as JSON and re-serialized. ..."

2. The wrong secret (that looks right)

A Stripe API key (sk_...) instead of the endpoint's signing secret (whsec_...).
The test-mode secret in production.
A Slack bot token instead of the signing secret.
A trailing newline or quotes from the .env file.

All four produce "signature mismatch" with no other clue. verihook recognizes the API key, the whitespace and the quotes from the secret's shape, and its hint names the mistake.

3. The proxy changed the URL

Twilio, Square and HubSpot sign the public URL they called. Behind ngrok, a load balancer or API Gateway, your server sees http://10.0.0.5:3000/... instead of https://api.example.com/..., and verification fails. Rebuild the URL from x-forwarded-proto and x-forwarded-host, or pass the public URL explicitly.

4. Verification passes, but you processed the event twice

Providers deliver at least once. A timeout makes them retry, and a valid signature accepts every copy. You need deduplication, and the key matters: if you key it on a header the signature doesn't cover (GitHub's x-github-delivery, say), an attacker can replay a captured webhook with a fresh header and walk past your dedupe store. verihook only keys on data the signature covers: a signed ID header, an ID inside the signed body, or a hash of the body.

const result = await verifyWebhook('stripe', req, secret, { dedupeStore });
if (result.code === 'DUPLICATE_EVENT') return res.status(200).end(); // stop the retries

5. Your tests pass because they test themselves

This one bit me. verihook's Paddle verifier read h= from the Paddle-Signature header. Its test signer also wrote h=. Every test passed. Paddle actually sends h1=, so every real Paddle webhook was rejected.

A test that signs with your code and verifies with your code proves the two agree, not that either matches the provider. What helps:

Known-good vectors from the provider's docs: a payload, secret and signature you didn't compute yourself.
Conformance tests against official SDKs. verihook's CI signs with the official Stripe, Octokit, Svix and Twilio SDKs and verifies with verihook, and the other way around.

What it looks like

// Next.js App Router
import { createWebhookHandler } from 'verihook/next';

export const POST = createWebhookHandler('stripe', process.env.STRIPE_WEBHOOK_SECRET!, async (payload, result) => {
  if (result.eventType === 'checkout.session.completed') {
    // result.event is typed
  }
});

There are one-line adapters for Express, Fastify, Hono, NestJS, Nuxt, SvelteKit, Remix, Astro and AWS Lambda. It runs on Node, Deno, Bun and edge runtimes, and importing one provider (verihook/stripe) costs about 4 kB. For tests, signWebhook() builds signed requests for every provider, and npx verihook simulate stripe sends one to your local server.

The docs have a page per provider with where to find the secret in each dashboard: creatorpiyush.github.io/verihook.

If a provider you use is missing, or a signature scheme looks wrong, I'd like to hear about it. Issues are open.