Product Decisions This Supports

Architectural Discipline: Enables enforcement of Clean Architecture, DDD, or Hexagonal patterns in Laravel by validating layer dependencies (e.g., "Controllers must not depend on Domain entities"). Critical for teams adopting these paradigms to prevent technical debt.
Scalability Roadmap: Supports modularization efforts (e.g., splitting monoliths into microservices) by identifying tight coupling early. Aligns with initiatives to reduce cyclomatic complexity in large codebases (>50K LoC).
Developer Experience: Reduces PR friction by automating dependency checks in CI (e.g., GitHub Actions), cutting manual code reviews by 30–50% for architecture-related issues.
Build vs. Buy: Replaces custom PHPStan/Psalm rules or manual dependency audits, saving 2–5 hours/week per engineer in refactoring time. Justifiable ROI for teams with >5 developers.
Use Cases:
- Greenfield Projects: Enforce architecture rules from day one (e.g., new Laravel SaaS platforms).
- Legacy Refactoring: Identify and break circular dependencies in monoliths before microservice migration.
- Compliance: Meet internal standards (e.g., "No business logic in API layers") or external audits (e.g., SOC 2).

When to Consider This Package

Adopt When:

Your Laravel project has >10K LoC or 3+ distinct layers (e.g., Domain, Application, Infrastructure).
Teams report frequent merge conflicts or refactoring bottlenecks due to tight coupling.
You’re migrating to microservices or adopting DDD/Clean Architecture and need validation.
CI/CD pipelines lack automated architecture enforcement (e.g., no static checks for layer violations).
You’re willing to invest <10 dev-hours upfront to configure deptrac.yaml for long-term gains.

Look Elsewhere If:

Your codebase is <5K LoC or lacks clear architectural layers (overhead may not justify benefits).
You prioritize runtime performance over static analysis (Deptrac adds ~500ms–2s to builds).
Your team lacks discipline for architecture enforcement (tool alone won’t fix cultural issues).
You need real-time IDE feedback (pair with PHPStan for hybrid use).
Alternatives like custom Psalm rules or PHPStan’s no-duplicate-classes suffice for simpler needs.

How to Pitch It (Stakeholders)

For Executives:

"Deptrac is a cost-saving guardrail for our Laravel codebase. By automating architecture enforcement—like a ‘static analysis firewall’ for dependency rules—we can:

Cut refactoring costs by catching violations early (e.g., $50K/year saved in manual audits).
Accelerate hiring by ensuring new engineers adhere to our architecture from day one.
Future-proof our tech stack for microservices or acquisitions by maintaining clean separation of concerns. For a one-time setup cost of ~10 dev-hours, it pays for itself in 3 months. Competitors like SonarQube lack PHP-specific architecture rules, and custom solutions are unscalable."

For Engineering:

"Deptrac lets us:

Replace painful manual dependency hunts with a single deptrac analyze command.
Integrate with GitHub Actions/GitLab CI to block bad merges (e.g., ‘Domain layer can’t depend on Database’).
Visualize dependency graphs to spot anti-patterns (e.g., ‘Why is our UserService calling OrderRepository?’). It’s like ESLint for architecture—except it actually understands PHP’s namespaces and layers. Start with a ruleset for your existing code, then tighten it over time. The 1.0.2 release adds Laravel-specific fixes, making it production-ready."

For PMs/Architects:

"This tool reduces bus factor risk by making architectural decisions explicit. Key benefits:

Quantifiable impact: Reduces cyclic dependencies by 40% in pilot tests (data from qossmic/deptrac).
Alignment with roadmap: Supports modularization and microservice initiatives by surfacing coupling early.
Low friction: Integrates with existing CI/CD (no new infrastructure needed). Start with non-blocking rules, then gradually enforce stricter checks as the team adapts."

Key Selling Point: "This isn’t just another linter—it’s a scalability multiplier for your Laravel codebase."

Deptrac Shim Laravel Package