Foundation Laravel Package

Technical Evaluation

Architecture fit. Orchestra Foundation is the runtime/bootstrap layer for Orchestra Platform, not an installable library. That distinction drives every program decision downstream: adopting it means adopting an application skeleton that owns bootstrapping, service-provider registration, routing conventions, ACL registration, theming, and often the user model. The architectural payoff is the extension model — a feature becomes an installable unit with its own provider, routes, migrations, config, and optional admin UI. That is genuinely valuable only if modularity is a real product requirement: separate teams or partners shipping capabilities without touching core, per-client white-labeling, or a future extension marketplace. If every feature lands in one repo owned by one team, the module machinery is overhead. Also note the fit boundary: module boundaries are not a tenancy story, and the platform semantics are pure cost if the requirement is CRUD plus auth.

Integration feasibility. Feasible, but only on two paths. Greenfield: composer create-project orchestra/platform, php artisan orchestra:install, log in at /admin, then port domain logic deliberately into extensions. Or a satellite admin service isolated behind a route prefix and a separate database connection. Grafting Foundation onto an existing production Laravel app is a poor trade and should be ruled out at the start. The first-use loop to validate — install and enable one extension, confirm the admin menu, ACL gate, and theme render — exercises the entire stack and is the correct spike target.

Technical risk. The risk profile is concentrated and must be stated plainly to stakeholders. Effectively one upstream maintainer, zero visible dependents, low composite score, no commercial support. The Composer constraint on the Laravel major is a hard lock; a Laravel security release Foundation hasn't caught up to will freeze the program on an unsupported framework. The most common in-flight failure is two-idiom drift — engineers applying native Laravel conventions (policy-based authorization, auto-discovery, Livewire/Inertia layouts) inside a Foundation app, producing inconsistent authorization and duplicated admin chrome. And the exit cost is the sleeper: failure means rewriting the application's structural seams, not swapping a package. Evidence weight matters here — we are evaluating the architecture and its source, not a proven market choice.

Key questions.

• Is pluggable modularity a validated roadmap requirement, or an aspirational diagram?
• Who is the named internal owner of the fork, and is that staffing committed before product code is written?
• Which Laravel major are we pinning to, and what does the tagged release history say about the supported matrix and commit cadence — not the README?
• Greenfield or satellite: which is actually available given the current application estate?
• What is the realistic alternative cost (Filament or Nova plus Spatie permissions plus a homegrown loader) in engineer-weeks, and what is the measured exit-cost estimate?
• What does the hiring profile look like, and does the team already know the Orchestra lineage?
• Who signs the ADR recording this as a platform bet rather than a Composer line item?

Integration Approach

Stack fit. Laravel-native PHP. The value proposition is coherence: ACL/RBAC, theming, admin scaffolding, resource routing, centralized settings via Orchestra\Memory, and a module loader as one pre-integrated system — no owning of every seam between Filament/Nova, Spatie, and a custom loader. Keep domain logic in portable service classes; keep Foundation-specific wiring (routes, menus, ACL registration) at the edges. Use Orchestra\Memory for per-extension settings rather than adding a settings table, and register themes through the theme API rather than hardcoding paths.

Migration path. Two sanctioned routes, one forbidden. Sanctioned: (1) greenfield skeleton with domain logic ported deliberately; (2) satellite admin service behind a route prefix and separate DB connection. Forbidden: retrofitting Foundation onto a production Laravel app. When bridging to native Laravel features — policies, Sanctum, queue jobs — do it inside the extension, not by reworking Foundation bootstrapping. Maintain a thin, documented patch layer for Foundation itself; no vendor edits, because vendor edits make the fork-and-own posture painful.

Compatibility. Pin the Laravel major and select the matching Foundation release line, reading tagged releases rather than the README — Foundation histories track specific majors. Forbid automatic major framework upgrades in CI and require a spike for each minor bump. Verify the supported matrix, commit cadence, and issue responsiveness before committing. Note the v5.1.1 fix: email.username no longer needs encryption in orchestra:configure-email; earlier patches can produce mangled mail config, so confirm the exact patch level before debugging SMTP.

Sequencing.

1. Week 0 — pin and gate. Fix the Laravel major, identify the matching Foundation line, name the fork owner, draft the ADR skeleton.
2. Weeks 1–2 — time-boxed spike. Stand up the skeleton, build one real extension end to end across the extension → admin surface → permission gate loop, exercise ACL, confirm the version matrix, attempt a minor framework bump to measure upgrade cost, and produce a written exit-cost estimate.
3. Gate review. Default to no. Adopt only if the spike passes, the build-vs-buy math favors it (roughly: we would otherwise spend more than ~six engineer-weeks rebuilding module management and ACL), the exit-cost estimate says we can walk away inside a sprint, and an owner is named. Record the decision in the ADR.
4. Governance before volume. Set module ownership, naming prefix, and dependency-direction rules before the module count grows. Set the CI policy that blocks automatic Laravel major upgrades.
5. Build-out. Incremental extension delivery inside the boundary, with the onboarding doc and code-review enforcement of the extension boundary landing alongside the first production extension.

Operational Impact

Maintenance. Plan for fork-and-own, not vendor dependency. That means a named internal maintainer, a thin documented patch layer, a documented upgrade runbook, and a standing budget line for keeping the fork current with Laravel security releases. Upgrade cadence is not under our control upstream; our cadence is. Treat every Laravel major as a program-level migration with a spike and a rollback plan, and every minor as a tested bump in CI.

Support. No commercial support and effectively a single upstream maintainer means the escalation path is internal, full stop. Bus factor is one on both sides — upstream and, until we staff it, ours. Verify issue responsiveness and commit cadence against tagged releases during the spike and re-check quarterly as a vendor-concentration signal in the risk register. Communicate to stakeholders that adopting this is adopting a fork, and the cost of the head start on architecture is the cost of ownership.

Scaling. Technically this is standard Laravel scaling — the constraints are organizational and architectural, not throughput. The real scaling limit is module sprawl: the extension model makes it trivially easy to spawn small modules faster than one team can absorb, multiplying maintenance surface. Governance rules (owner, prefix, dependency direction) are therefore a scaling control, not bureaucracy. Watch ACL registration at boot as module count rises, and manage cache/compiled-artifact behavior in deploy procedures. Module boundaries do not deliver data isolation; do not let a multi-tenancy requirement get conflated with the extension story.

Failure modes and diagnostics. Bake these into the runbook and on-call docs:

• Extension installed but not enabled — menu items and routes silently absent.
• Extension migrations not re-run, or ACL rows not seeded.
• Stale compiled/route/config caches after provider or route changes.
• Wrong admin route prefix in config/orchestra/foundation.php — silently 404s everything downstream.
• Auth guard mismatch between the admin area and auth.guards.
• Upstream lag on a Laravel security release, freezing us on an unsupported framework.
• Two-idiom drift producing inconsistent authorization and duplicated admin chrome across modules.
• Lockout risk: new resources not cross-checked against the default admin role.

Ramp-up. The hiring pool is narrower than "Laravel developer," and sparse documentation and examples shift onboarding burden onto us. Budget roughly one to two weeks for an experienced Laravel engineer to become productive, anchored on the extension → admin surface → permission gate loop as the training exercise, backed by the ADR and an onboarding doc written during the spike. Enforce the extension boundary in code review from the first PR — this is the highest-leverage control against the most common failure mode. Set expectations with leadership that the team is learning a platform lineage, not just a package, and that the learning tax is paid up front in exchange for the module model being available later rather than retrofitted.