Arch Viewer Laravel Package

Product Decisions This Supports

• Build vs. buy for architecture documentation. The core decision is whether we keep hand-writing and hand-maintaining architecture docs (module maps, context diagrams, onboarding guides, ADRs) or derive the structural half of them from the code. open-solid/arch-viewer is a generator for OpenSolid projects — it converts class, namespace, and module dependencies into an explorable map. That makes "automate derivation" a real option with a known cost, instead of a vague aspiration.

• Whether to invest in architecture governance, and in which half. Auto-generated structural docs are the cheap half of governance; the expensive half is enforcement (dependency rules, layer boundaries that fail the build). This package informs only the first half — it documents, it doesn't police. The product decision it supports is: do we want visibility into architectural drift now, with gating (Deptrac/PHPat/Arkitect) as a separate, later investment?

• Onboarding and knowledge-transfer roadmap. A generated map of modules and their dependencies is a concrete onboarding accelerator: it turns "better docs" into measurable line items — time-to-first-PR, ramp-up cost per hire, count of "where does this live?" questions per sprint.

• Standardizing on the OpenSolid stack (or not). Adopting this package is a soft commitment to OpenSolid's DDD/hexagonal conventions, because its value is derived from that structure and is near-zero without it. It's a data point in the larger platform decision: do we template our Laravel services on OpenSolid conventions, or keep architecture conventions ad hoc?

• Documentation-as-code in CI. If output is deterministic and diffable, we can regenerate on merge and flag when the architecture diagram changes without review. That's a workflow decision — where docs live, who owns them, whether they're allowed to rot — and it's testable cheaply.

• Prototype use cases worth naming: a living architecture section in the repo; a per-service module catalog for a platform team; design-review and post-incident input ("which module actually owns this?"); technical-diligence collateral for architecture-heavy engagements.

• Decision-log framing: Assess / spike, not Adopt. Zero stars, zero dependents, no score, single-vendor origin. The decision this supports today is "is a one-to-two-day evaluation worth it?" — not "should this be a production dependency?"

When to Consider This Package

Consider it only when all of these hold:

• We are already on OpenSolid conventions. The generator has little to describe otherwise.
• We need structural docs more than prose. Module maps and dependency views are the ask; we accept generated, utilitarian output.
• Stale-but-cheap-to-regenerate is acceptable. These are internal, advisory docs — not contractual, customer-facing, or audit artifacts.
• Someone can read and fork the source. It's small and single-purpose. Budget for a vendored copy or internal fork from day one; assume we are the maintainers.
• It runs as a non-blocking, CI-adjacent step first, so a generation failure never breaks a release.

Look elsewhere when:

• We're not on OpenSolid. Reach for C4/Structurizr, phpDocumentor, or Markdown + Mermaid instead.
• We need enforcement, not documentation. That's Deptrac/PHPat/Arkitect — a different tool and a different conversation.
• Procurement or security review requires maintenance evidence — release cadence, security policy, responsive issue tracker, cleared license. That's not disqualifying for a spike; it is disqualifying for an unexamined production dependency.
• We need vendor support, SLAs, or a roadmap commitment. There is no visible commercial backing.
• The bottleneck is authorship, not derivation. If nobody reads a generated diagram, automation just produces ignored artifacts faster.
• The docs must be editorial — narrative ADRs, trade-off reasoning, decision context. Generated structure cannot supply the "why."

Adoption path: spike in a branch → vendor/fork → internal-only pilot on one service → reassess. Do not put it on the critical path of a release process until output is confirmed stable across two consecutive runs. One due-diligence flag before installing: the declared package name and the source repository don't obviously match — confirm provenance and license as a hard gate, not a formality.

How to Pitch It (Stakeholders)

For executives — one paragraph. We spend real engineer-hours hand-maintaining architecture documentation that goes stale within a sprint, and new hires pay for that in ramp-up time. open-solid/arch-viewer is a small open-source generator that produces that documentation from the code itself, so it stays current by construction. The ask is not budget — it's roughly one to two engineer-days to evaluate against a single service. Risk is contained by design: it's a dev-only dependency producing static files, outside the request path and the build's critical path, and if the project is abandoned we fork a small tool we already understand. Success looks like onboarding docs that regenerate on merge, a measurable drop in "where does this live?" questions, and a reusable pattern for every service that shares the same conventions. Failure costs two days and yields a written recommendation either way.

For engineering leads. This is not a framework decision and it is not an enforcement tool — it documents, it doesn't police. It only pays off if we're genuinely on OpenSolid conventions, so the first hour is confirming that. Expect to vendor or fork: single-author project, no dependents, no release history to lean on. Treat the output as generated, reviewable, diffable text committed to the repo — not a wiki that drifts. Keep the first CI integration non-blocking, and watch for silent omission: constructs the generator doesn't recognize simply won't appear, and the output will still look complete. If what you actually want is a build that fails on layering violations, say so now — that's Deptrac/PHPat, and a separate decision.

Positioning line: Cheap, reversible experiment that attacks documentation rot and onboarding cost — with a vendor-risk caveat we've already priced in.