Superstack Laravel Package

Technical Evaluation

Architecture fit

nativephp/superstack is a starter application, not a composable library. Adopting it means forking a Laravel skeleton that bundles three distinct capability layers:

The architectural consequence is that your product's foundation is the fork, not a dependency. Every future Laravel, Filament, or NativePHP upgrade becomes a manual merge decision rather than a composer update. That is acceptable for a greenfield product where you intend to own the codebase outright; it is a poor fit where you expected to consume this as a versioned package.

Fit is strongest for: single-tenant internal tools, desktop-shipped operational apps, admin-heavy back-offices, and AI-agent-driven workflows where MCP is a genuine product requirement rather than a checkbox. Fit is weakest for: multi-tenant SaaS, regulated environments needing vendor support/SBOM provenance, and teams without desktop release engineering experience.

Integration feasibility

Low technical barrier, moderate organisational barrier. A Laravel team can clone, composer install, and have Filament running in under a day. The real cost sits in three places:

1. First divergence commit. You must decide on day one whether you track upstream or cut clean. Without a policy, the second git pull from upstream produces conflicts across composer.json, config, migrations, and Filament resources.
2. Desktop packaging pipeline. Code signing, notarization (macOS), SmartScreen reputation (Windows), and auto-update channels are new infrastructure most Laravel teams have never built. Budget real time here — this is usually the largest unbudgeted line item.
3. MCP surface design. Exposing app actions as agent tools is easy to prototype and hard to make safe. This needs an explicit capability model, not an incidental one.

Technical risk

• Upstream immaturity. 99 stars and an MIT starter imply a small maintainer surface and no compatibility guarantees. Treat the project as a reference architecture you fork, not a vendor.
• Compounding pre-1.0 dependencies. NativePHP (and by extension SuperNative) sits early in its lifecycle; major-version churn is likely and may be breaking at the runtime/packaging layer, which is precisely where your release pipeline lives.
• Starter drift. Security fixes in the starter (auth config, Filament policies, dependency pins) will not reach you automatically.
• MCP blast radius. Agent-callable tools are an authenticated, privileged API surface. Without scoping, per-tool authorization, rate limits, and audit logging, you have built a remote-control interface into your app and handed the keys to a non-deterministic client.
• Desktop trust model. A locally installed binary with a local database changes your data-governance story: backups, retention, DLP, and multi-device consistency become your problem.

Key questions

1. Is the target deliverable a desktop binary or a web app that happens to use Filament? The answer changes infra, scaling, and support entirely.
2. Does your product genuinely require MCP, or is it a differentiator you could defer by one release?
3. Who owns upstream tracking — is there a named maintainer and a cadence for rebasing onto the starter?
4. What is the licence and support posture of the NativePHP runtime components specifically (separate from this repo's MIT)?
5. What data lives in the local install, and is any of it synchronised to a server? If yes, what is the conflict-resolution model?
6. Which MCP clients must be supported at launch, and what is the minimum viable tool set?
7. Does your team already ship signed desktop installers? If not, is that capability being hired or bought?

Integration Approach

Stack fit

Strong if you are already a Laravel/PHP shop with Filament familiarity — you inherit conventions, Eloquent, policies, queues, and the existing talent pool. The PHP-only proposition (no JS/Electron split, no separate desktop stack) is the package's core economic argument and it holds for CRUD-shaped products. It fits poorly where the UI demands heavy client-side interactivity, real-time collaboration, or where the team's centre of gravity is TypeScript.

Migration path

Treat this as greenfield fork-and-own, not incremental adoption into an existing app. Recommended shape:

• Create a private repository seeded from the starter, with upstream added as a read-only remote.
• Immediately land a FORK.md documenting what you changed and why, and a policy that all local modifications are isolated (custom Filament resources, service providers, config overrides) to reduce future merge surface.
• Pin every dependency explicitly; add a lockfile-diff review step to PRs.
• If you already have a Laravel app, do not graft this in. Extract the pieces you want: Filament as a package, NativePHP as a build target, MCP as a thin adapter. The starter's value is the wiring, and wiring does not transplant cleanly.

Compatibility

• Confirm Laravel and Filament major versions align with your support policy; Filament major upgrades are non-trivial and will gate your Laravel upgrade cadence.
• Confirm the NativePHP/SuperNative runtime's supported OS versions and its PHP version constraint — a runtime/PHP mismatch is a hard blocker, not a warning.
• The AGENTS.md/Laravel Boost bootstrap pins PHP 8.5 tooling in its install instructions; verify your CI images and developer machines can meet that, or the agent-assist workflow will fail on first run.
• MCP client compatibility is client-specific; validate against your actual target clients rather than the spec.

Sequencing

1. Spike (1–2 weeks). Fork, get Filament running, build and sign a throwaway desktop binary on both macOS and Windows. This de-risks the single hardest unknown first.
2. Decide the trust model. Desktop-local, desktop-with-sync, or web. Everything downstream depends on this.
3. Stand up the release pipeline — signing, notarization, auto-update channel, versioning — before feature work, not after.
4. Build the domain on Filament, keeping the starter's structure intact to preserve merge-ability.
5. Add MCP last, behind an explicit capability registry with per-tool authz and audit logging. Ship it feature-flagged.
6. Formalise upstream tracking once you have divergence: a scheduled review of upstream commits, triaged into adopt/defer/ignore.

Operational Impact

Maintenance

Ongoing maintenance load is materially higher than a normal Composer dependency, because you inherit ownership of the entire application shell plus a desktop distribution channel. Recurring obligations:

• Rebase onto upstream starter changes (security patches, dependency pins) on a fixed cadence.
• Track NativePHP runtime releases, which may lag or lead your Laravel version.
• Re-sign and re-notarize on every release; certificate and provisioning-profile rotation is a calendar item, not a task.
• Keep the MCP tool schema and its documentation synchronised with actual app capabilities.

Support

Support surface expands from "the web app" to "the installed app on an unknown OS version." Expect OS-update breakages, antivirus and SmartScreen false positives, and installation/permissions tickets. You will need per-platform reproduction environments — a support cost teams routinely underestimate. There is no upstream vendor to escalate to; community channels only.

Scaling

• Desktop path: does not scale horizontally in the usual sense. Each install is an independent node with its own database; your scaling problem becomes distribution and update reach (CDN, staged rollout, version telemetry) rather than request throughput. If you add server sync, you inherit conflict resolution and per-device identity — a significant, ongoing engineering cost.
• Web path (Filament panel only): conventional Laravel scaling applies — standard web tier, queue workers, managed DB. The starter itself introduces no unusual scaling constraint; Filament panels are stateless behind normal session handling.
• MCP path: tool calls are user-equivalent workloads; they should be rate-limited and queued like any privileged API. Agent clients can generate bursty, high-volume traffic that looks nothing like human usage — plan quotas accordingly.

Failure modes

Ramp-up

Fast for the Laravel/Filament layer — a competent Laravel developer is productive within days. Slow for the two novel layers:

• Desktop release engineering: signing, notarization, installers, auto-update. Assume 2–4 weeks for a first reliable pipeline, longer without prior experience.
• MCP/agent integration: the conceptual model (tools, capabilities, client auth) is new to most teams, and the security review bar is higher because the caller is non-deterministic. Budget a security review before any external exposure.

The AGENTS.md/Laravel Boost bootstrap is a genuine onboarding accelerant for AI-assisted development, but it also means agent-generated code becomes part of the review surface — ensure human review gates on anything touching auth, policies, MCP tool definitions, or the release pipeline.

Recommendation. Adopt as a greenfield foundation for a single-tenant, admin-heavy, desktop-shipped product, with explicit fork ownership and the desktop pipeline de-risked in week one. Do not adopt if you need multi-tenant SaaS, vendor-backed support, or a low-maintenance dependency you can upgrade on rails — in those cases, take Filament and NativePHP individually and leave the starter behind.