Capell Skeleton Laravel Package

Technical Evaluation

Architecture fit: The critical framing for a TPM is that this is a skeleton, not a library. You do not composer require it and receive upgrades; you scaffold a repository from it once and then own every line. That inverts the usual dependency risk model — the package's 1.0.x immaturity does not create a recurring upgrade tax, but it does mean there is no upstream merge stream to pull fixes from later. The artifact itself is hybrid: Composer-managed PHP plus a Node-built frontend for Capell's generated "Foundation" theme. It slots cleanly into a conventional Laravel application, but the boundary between "install" and "asset build" is the part that touches platform and CI.

Integration feasibility: Feasible for a Laravel-fluent team, and the leverage is real: skipped boilerplate for service providers, config, directory layout, and a working theme. The v1.0.4 release note is the signal to weigh — its entire content is "install the Node dependencies so the documented post-install build succeeds." That means the previously documented onboarding path was broken for at least one release cycle, so the install guide should be treated as unverified documentation, not a specification. The description also advertises use "as a reference for integrating Capell into an existing Laravel codebase," which conflates two decisions: adopting the Capell core packages, and adopting this skeleton. A TPM should separate them and evaluate the core packages' versioning independently.

Technical risk:

• Maturity and bus factor. Zero stars, a single patch line, and a release note that reads like a first adopter hit a wall. There is no visible ecosystem, no support matrix, and no evidence of CI covering the install path.
• Fork-and-own with no upgrade channel. Scaffolded code diverges immediately. Security patches or structural fixes to the skeleton will not reach us as a version bump; we must watch upstream and cherry-pick manually.
• Toolchain coupling. We inherit Node/npm registry availability, Node major-version drift, and transitive dependency churn from a package we are otherwise evaluating on its PHP surface. Node support range is unstated.
• Build-time ambiguity. Unknown whether compiled CSS ships in the scaffold, is built at install, or is built at deploy. Each implies a different failure mode and a different owning team.
• Unverified non-functional posture. License, security disclosure process, PHP/Laravel support range, and Laravel Cloud runtime assumptions (the description's stated deployment target) are all unconfirmed.
• Low score, low signal. The composite score reflects thin adoption evidence, not necessarily poor quality — but a TPM should not treat this as validation either.

Key questions:

1. Is Node required in production deploys, or only for developers regenerating theme assets?
2. Is a lockfile included with the theme scaffold, and does the documented build replace or merely unblock shipped CSS?
3. What are the supported Laravel/PHP and Node major versions, and is a matrix published?
4. Is the generated theme scaffold-once (ours to own) or regenerated on upgrade?
5. Who maintains this, what is the release cadence, and is there a CI example covering install → build → test?
6. What is the license, and is there a security contact?
7. Does the Laravel Cloud target imply constraints that reduce portability to our own infrastructure?

Integration Approach

Stack fit: Low incremental cost if we already run Composer plus a Vite/npm build in CI — one more dependency graph, one more cache key. If our deploy path is deliberately Node-free (Composer-only images), this introduces a new class of build infrastructure and should be scoped and budgeted as such rather than absorbed as "just a CMS install."

Migration path: There is no migration; this is greenfield adoption or nothing. The realistic path is a time-boxed spike in a throwaway Laravel app, following the v1.0.4 instructions literally with zero improvisation. Every deviation gets recorded. That transcript becomes both our internal runbook and our upstream bug report, and it converts an unverifiable doc into evidence. In parallel, confirm whether the same capability is reachable by pulling the Capell core packages into our own skeleton — that option preserves our own CI conventions and may be the better TPM recommendation regardless of spike outcome.

Compatibility: Two axes must be cleared before commitment: PHP/Laravel version support and Node version support. Neither is documented in the release note. Both get pinned explicitly in our own config once verified, and the pins live in the repo, not in a wiki.

Sequencing (gated, not parallel):

1. Spike (1–2 days): clean-room install at our target Laravel version; verify the documented build succeeds unaided and the theme renders.
2. Pin: capture exact Node, npm, and lockfile state from the spike and commit it.
3. CI proof: add an install-and-build job run from a cold cache to confirm reproducibility.
4. Deploy-model decision: compiled assets committed, built in CI, or built in the image — aligned with how we already handle frontend assets. Depends on step 1's outcome.
5. Go/no-go review against the key questions before any product code depends on it. Steps 1–5 must not run in parallel; step 4 is only meaningful after step 2, and step 3 is only meaningful once versions are pinned.

Operational Impact

Maintenance: Ongoing cost is dominated by frontend dependency rotation and by owning scaffolded application code indefinitely. Budget periodic Node/npm bumps and theme regeneration, and assign a named owner for the theme build — the most likely organisational failure for an artifact that sits between backend and frontend teams and has no upstream to push fixes.

Support: Upstream appears small and documentation-driven. Assume low bandwidth and no SLA. Plan to be self-sufficient on build issues, and keep knowledge in a versioned runbook rather than a chat thread. An internal fork with our pins committed is the practical support strategy.

Scaling: The asset build is a per-deploy cost, not a per-request one; caching keeps it cheap and it does not scale with traffic. Runtime scaling is ordinary Laravel — horizontal app servers, shared database and cache. The one item to flag now: if themes are ever compiled or rendered per-tenant rather than per-deploy, build cost becomes proportional to tenant count and must be precomputed.

Failure modes:

• Post-install build fails at deploy because Node deps were absent — precisely the failure v1.0.4 patches around. Mitigation: build in CI, never on the production host.
• Silent CSS regression where the build succeeds but emits stale or partial assets. Mitigation: smoke-test on a known selector or emitted asset hash.
• Cold-cache non-reproducibility from unpinned transitive dependencies. Mitigation: commit a lockfile, use npm ci.
• Registry outage or rate limiting blocking a release. Mitigation: cache or vendor dependency tarballs in our artifact store.
• Node major-version removal from a base image breaking builds months later. Mitigation: pin Node in the image, never rely on the runner default.
• Upstream divergence leaving our fork stranded from security fixes. Mitigation: subscribe to releases, schedule a quarterly diff against upstream.

Ramp-up: Low on the PHP side for Laravel developers; moderate on the build side for anyone who has not maintained a Node toolchain. Budget roughly one engineer-week to reach confident, repeatable installs plus a written runbook, front-loaded into the spike and CI proof. Given a lone docs-level patch release on a zero-star package, the governing TPM guidance is simple: nobody follows this install guide for the first time on a Friday, and no product commitment is made until step 3 produces a green build from a cold cache.