Synapse Laravel Package

Technical Evaluation

Architecture fit. Synapse is a dev-tooling package in the Telescope/Horizon lineage: a service provider registers routes, a React SPA shell, publishable config and migrations, and console commands. It is explicitly not on the request path of your application — it is a browser dashboard over agent executions. That distinction drives the entire evaluation: it is an observability/authoring surface for the Laravel AI SDK (laravel/ai), not a runtime dependency of your AI features.

The architectural choices are disciplined and appropriate. Three self-contained synapse_* tables; a hard rule against touching the SDK's agent_conversations table; discovery, invocation, approval and recording split into distinct namespaces (Chat/, Discovery/); a repository layer for cascade deletes shared by prune, clear and endpoint delete. Committed dist/ assets inlined at request time removes Node from the deployment story entirely, which is the right call for a dev-only package.

Integration feasibility. High in the narrow case, zero in the broad case. The hard prerequisite is that you already run the Laravel AI SDK. Synapse is a companion tool — it offers value only to teams that have agents to chat with, test, and approve. Because it registers its own routes, views, and migrations under a publish-only model, installation is one Composer command plus a gate stub and a config publish. There is no interception of your application code, no service container surgery, no event listeners on your models.

The real integration risk is version coupling: Synapse tracks the internals of laravel/ai — discovery of agent metadata, tool call shape, streaming event format. An SDK that shifts its contract invalidates the dashboard's parsing. That is a tight, non-negotiable coupling.

Technical risk. Ranked:

1. Upstream SDK volatility (high). The dependency on laravel/ai is the whole product. If the SDK is pre-1.0 or iterating on streaming/tool-call contracts, Synapse upgrades become forced marches.
2. Exposure surface (medium, but severe if triggered). The dashboard can invoke agents, approve tool calls, and read conversation history. The viewSynapse gate is the only guard, and it is a published stub — meaning the failure mode of a forgotten publish is a default gate. Confirm default-deny in your environment matrix before anything else.
3. Adoption evidence (medium). 60 stars, 0 dependents, single vendor. Pre-commit gates, Pest, PHPStan level 5 and Pint are genuine quality signals, but they measure internal hygiene, not field-hardening. The browser e2e suite — the only cover for the PHP → SSE → React boundary where the docs admit "hardest bugs live" — is a manual pre-release gate, not CI. That is a reasonable trade-off for a maintainer, and a red flag for an adopter who needs regression confidence on upgrade.
4. Token spend (low–medium). It is designed to be driven with Agent::fake() in tests, but nothing structurally prevents a developer from pointing it at a real provider.
5. Blast radius (low). It is a dev tool. A broken Synapse dashboard degrades developer experience; it does not take down your product.

Key questions for the vendor / spike:

• Which laravel/ai versions are supported, and is that range enforced in composer.json or merely documented?
• What is the gate's default state when the published provider stub is absent — deny, or fall through to APP_ENV?
• Are migrations publish-only and additive, or can synapse:install mutate/reshape existing tables on upgrade?
• What is the retention default, and does the scheduled prune run without operator opt-in?
• Does the dashboard require an SSE-capable web server (no output buffering, no proxies that flatten streams)?
• Is there a documented upgrade path (UPGRADE.md exists — how complete is it for major versions)?

Integration Approach

Stack fit. Clean for Laravel 11/12 + Livewire-free frontends; the SPA is self-contained and ships compiled. No Node toolchain, no Vite config changes, no npm audit surface added to your app. The only stack-level question is whether your environment serves large inline asset responses acceptably (asset tags are inlined at request time — fine for a dev tool, unexamined for a shared staging box).

Migration path. Treat it as an additive, reversible dev dependency:

1. composer require --dev redberry/synapse.
2. Publish config (snapse-config) and the gate stub (snapse-* provider) — review the gate before first boot.
3. Run the install command to publish the three synapse_* migrations; optionally point them at a dedicated connection via SYNAPSE_DB_CONNECTION to keep dev telemetry out of your primary schema.
4. Set SYNAPSE_ENABLED and the viewSynapse gate to explicit local-only.
5. Verify asset serving and SSE streaming in your actual local runtime (Sail, Herd, DDEV, Valet) — this is where first-install friction lands.

Rollback is composer remove plus dropping three tables. That reversibility is the strongest argument for a spike.

Compatibility. Pin the SDK and the dashboard together in composer.json and upgrade them as a pair. Do not allow a floating laravel/ai constraint alongside Synapse. Verify PHP/Laravel matrix against your target versions explicitly — with zero dependents there is no community signal, so you are the compatibility test.

Sequencing.

Stop at phase 2 if the gate cannot be made default-deny or the SDK constraint cannot be pinned.

Operational Impact

Maintenance. Low ongoing cost, one sharp edge: the SDK coupling means Synapse upgrades are reactive, triggered by laravel/ai upgrades rather than chosen on your own schedule. Budget an upgrade-and-verify task per SDK bump, and require a manual pass of the maintainer's browser e2e suite (or your own smoke test of chat, stream, tool detail, approval) after each. Pin exact versions; a floating constraint on either side turns a routine upgrade into an unplanned incident.

Support. Single-vendor, single-repo. No dependents means no Stack Overflow corpus, no third-party tutorials, no one else's bug reports to learn from. Escalation is GitHub issues against a 60-star project — response time is a courtesy, not a contract. Internally, name an owner. This is not a package to let the team adopt organically and hope someone understands.

Scaling. Scales in the direction that matters (per-developer, one dashboard per local environment) and not in the direction it wasn't built for. Do not run a shared multi-tenant instance: concurrent browser sessions stream SSE against a shared conversation store, and the maintainer's own guidance notes that parallel suites race on the migration/testbench surface. If a shared staging instance is genuinely wanted, provision it as a single-tenant, gate-restricted, retention-capped deployment and accept that this is off the intended path.

Failure modes.

• Gate misconfiguration — dashboard exposed beyond local. Highest severity, lowest detectability. Mitigate with an explicit automated test asserting denial.
• SDK drift — dashboard loads but tool calls, token counts, or streams render empty/garbled. Silent, not loud; developers quietly stop trusting it.
• SSE broken by infrastructure — proxy buffering or output buffering flattens the stream. Presents as a hung UI, frequently misdiagnosed as a package bug.
• Stale committed assets — a version skew between published PHP and inlined dist/ after a partial upgrade. Rare but confusing; resolved by clean reinstall.
• Uncontrolled token spend — real provider calls from the playground. Bound by policy and by Agent::fake() discipline.
• Migration collisions — low, since tables are namespaced and publish-only, but confirm the install command is idempotent on re-run.

Ramp-up. Fast for anyone fluent in Laravel dev tooling — the mental model transfers directly from Telescope and Horizon, and the UI vocabulary (agents, tool calls, approvals, tokens) is self-explanatory to anyone already building with the AI SDK. Expect under an hour to first productive use. The non-trivial learning is operational, not conceptual: understanding that this is a development surface, that the gate is the only thing between it and the internet, and that its correctness is chained to an external SDK. That framing needs to come from you, not from the README.