Arch Viewer Laravel Package

Technical Evaluation

Architecture fit. open-solid/arch-viewer is a documentation generator scoped to OpenSolid projects: it inspects OpenSolid constructs (aggregates, commands, queries, events, handlers) and emits architecture documentation, presumably as static Markdown or HTML. It is developer tooling, not a runtime dependency — it belongs in require-dev, runs on demand or in CI, and never touches the request path. That makes its architectural blast radius low by construction, which is the strongest point in its favor and the reason this is even a viable spike. The caveat is that its value is entirely contingent on the host application actually following OpenSolid conventions; if the codebase only borrows a few traits, the output will be thin or misleading.

Integration feasibility. Mechanically trivial — a Composer require-dev entry, a published config, and a console entry point. The real feasibility question is fidelity, not installation: does the generator's model of the codebase match ours? A generator that silently skips handlers registered through a custom service provider, or misreads attributes versus annotations, produces documentation worse than none because it is confidently wrong. This must be validated against a real bounded context, not a sample repo.

Technical risk. High, concentrated in supply-chain and longevity. Zero stars, zero dependents, no score, and single-vendor origin means effectively no external scrutiny: no community bug reports, no third-party usage evidence, no security review, no signal that anyone but the author has run it. Version constraints against OpenSolid core are likely tight, so an OpenSolid upgrade can break the generator without warning. License and provenance require explicit confirmation before any code enters our build. Treat this as unvetted third-party source, not an adopted library.

Key questions. What license, and is the repo actively maintained (last commit, open issues, release cadence)? Which PHP/Laravel/OpenSolid versions are supported, and how tightly pinned? What is the output format, and is it deterministic enough to diff in CI? Does it discover constructs statically (reflection/AST) or via runtime container bootstrapping — the former is far safer for CI? Can output be scoped to one bounded context, or is it all-or-nothing? Is there a documented extension point for our conventions? Who is the maintainer, and what is our fallback if the repo disappears tomorrow?

Integration Approach

Stack fit. Assume a Laravel/PHP monolith using OpenSolid for domain modeling. The package fits in the documentation/quality lane alongside PHPStan, Pint, and Deptrac — a dev-only tool in the same review workflow, not in the deployable artifact. Confirm PHP and Laravel constraint compatibility against our supported matrix first; a mismatch ends the evaluation cheaply.

Migration path. There is no migration — nothing in production depends on it. Frame this as a time-boxed spike: vendor or fork the source into a scratch branch, point it at one representative bounded context, and compare the output to a hand-written architecture summary. Write go/no-go criteria down before the spike — coverage of our constructs, output determinism, install and runtime cost. If it fails, the fallback is a short in-house script over reflection plus a static docs page, roughly 1–2 engineer-days given the narrow scope.

Compatibility. Two axes: toolchain (PHP/Laravel/OpenSolid constraints) and semantic compatibility with our coding conventions. The second is the one that bites. Run the spike against our messiest, most convention-divergent module, not the cleanest one — that is where silent omission shows up.

Sequencing.

1. License and maintenance check — hard gate, cheap to run, ends the evaluation if it fails.
2. Constraint resolution in a throwaway branch.
3. Spike against one bounded context; diff generated docs against the manual summary.
4. Decide: adopt as require-dev, fork-and-maintain, or build the in-house equivalent.
5. If adopted, wire into an optional, non-blocking CI job first; only then consider making architectural drift a build failure.

Success criteria to agree up front. Generated docs committed as reviewable text with a visible timestamp and commit SHA; stable across two consecutive runs; a measurable reduction in onboarding time-to-first-PR and in "where does this live?" interruptions. If those metrics can't be stated, the spike shouldn't be funded.

Operational Impact

Maintenance. Effectively zero upstream maintenance guarantee. With no dependents and no visible contributor base, assume we are the maintainers from day one. Budget for a fork: pin to a commit, mirror the repository internally, and record the decision in the dependency register. As a dev-only tool the ongoing cost is small but non-zero — it will need attention at every OpenSolid or PHP upgrade, and that recurring cost should be named in the adoption decision, not discovered later.

Support. No community, no commercial backing, no Stack Overflow corpus. The internal escalation path is "read the source." That is acceptable for a documentation tool and disqualifying for anything else, which reinforces the require-dev-only stance and should be written into the decision record.

Scaling. Two dimensions. Repository scale: generation time and memory grow with codebase size, and unknown-quality reflection walks can be slow on a large monolith — measure on the real repo before wiring into every PR. Organizational scale: as more teams adopt OpenSolid, a shared generator with no upstream responsiveness becomes a coordination bottleneck, and each divergence becomes a local patch we own.

Failure modes.

• Silent omission — unrecognized constructs simply don't appear; the most dangerous failure because output looks complete.
• Stale docs — manual generation drifts from code and loses credibility within a quarter.
• Upstream break — an OpenSolid or PHP bump breaks the generator mid-upgrade, blocking unrelated maintenance.
• Abandonment — the repo is archived or deleted; our pinned fork becomes the only copy.
• CI flakiness — non-deterministic output makes a blocking docs check fail spuriously and get disabled.

Mitigations are cheap and should be mandatory: vendor/mirror the source, commit generated docs with a visible timestamp and commit SHA, keep CI non-blocking initially, and document the exit path to the in-house alternative.

Ramp-up. Low for users — one command, read the output. Moderate for maintainers, who need to understand both the generator's internals and OpenSolid's reflection surface. Half a day for a developer to evaluate and integrate, plus one to two days of contingent fork ownership if adopted. Given zero adoption signals, I would fund the spike but not plan around the package; the expected outcome is either a cheap win or a fast, well-informed decision to build the 200-line version ourselves. Either result is worth the two days.