Filament Knowledge Base Laravel Package

Technical Evaluation

Architecture fit. guava/filament-knowledge-base is an additive Filament plugin: it registers native resources (categories, articles), a rich-text authoring surface, and built-in frontend reader routes per panel. Architecturally it is a thin CRUD layer plus a renderer, not a platform — which is exactly what makes it low-risk to try and easy to exit. Fit is strong where the product is a Laravel + Filament admin/operator panel and help content today lives in Notion, Confluence, or a Loom link. Fit is poor where the requirement is public, crawlable, SEO-grade documentation, headless content delivery, or multi-tenant isolation — the migration ships no tenant_id, so tenancy becomes your work, including scoping slug uniqueness or route-model binding will resolve the wrong article across tenants.

Integration feasibility. The install chain is conventional and short: composer require, publish migrations and config, php artisan migrate, then register the plugin inside a panel provider. There is no service container surgery and no schema coupling to your domain models. A TPM can reasonably scope a 2–3 day timeboxed spike covering: publish → migrate → create one category and one article → confirm the reader route renders → route:list | grep -i knowledge. That single loop exercises migrations, routing, policy registration and rendering, and surfaces most breakage. A production-grade integration (policies, seeded content, contextual deep links, sanitization, instrumentation) is realistically one to two sprints of part-time effort, not days.

Technical risk. Ranked by what would actually hurt:

The offsetting signal is real but thin: an actively landed community contribution (Polish translation in 3.3.2) shows the package is not dormant. That justifies a spike; it does not justify a roadmap commitment.

Key questions to answer before committing.

• Who owns the content — authoring, review cadence, and stale-content cleanup? No named owner means a graveyard of outdated screenshots within a quarter.
• Who owns upgrades, and is Filament major-version tracking in someone's actual backlog?
• Is the audience internal/operator (fits) or public-facing (does not fit)?
• Do we need multi-tenant panels, and can we absorb the tenancy work?
• Does compliance require a sanitization guarantee for author-supplied HTML/markdown?
• Does the plugin expose a read-only factory (->readOnly()-style) for read panels, or must policies carry that? Verify in source before promising a read-only experience.
• What is the measurement plan, given the package ships no analytics?
• What is the decision date and kill criterion for the pilot?

Integration Approach

Stack fit. Requires a Laravel application on a Filament major the package supports, composer/artisan access, and the ability to override views or subclass resources. Confirm the Filament constraint in the package composer.json against your installed version first — a mismatch here ends the evaluation cheaply. Best fit: a single admin panel, or a small number of panels where you deliberately loop registration. Remember registration is per panel; there is no global switch, and expecting the KB nav item to appear on a panel you didn't register it on is the most common integration confusion.

Migration path. Brownfield-friendly. Two workstreams run in parallel:

1. Technical — spike, policies, seeding pattern, route verification, sanitization.
2. Content — decide the category taxonomy before authoring, then migrate existing docs. Recommended pattern: bodies live as markdown files in database/kb/*.md, committed in the same PR as the feature they document, loaded by a seeder using updateOrCreate keyed on slug. This keeps diffs reviewable, survives a fork of the package, and makes the exit a data copy rather than a rewrite. Guard the seeder in production so an accidental db:seed cannot overwrite hand-edited articles.

Compatibility. Four things to verify explicitly, not assume:

• Filament major version constraint and PHP version.
• Whether the published migration has a tenant_id or a pivot vs. FK for categories — this determines whether "article belongs to many categories" is config or fork.
• Whether the configured route prefix collides with an existing route or catch-all.
• Which guard the public reader routes resolve against, and whether that matches the panel's auth model.

Sequencing.

1. Spike (2–3 days, branch, version-pinned). Install, publish, migrate, one category + one article, reader renders, route:list verified. Go/no-go gate.
2. Access model. Split authoring (admin panel) from reading (operator/customer panels) via policies — viewAny / create gates on capability strings, not role names.
3. Content pipeline. Category taxonomy signed off by product; markdown-in-repo + slug-keyed seeder established as the only authoring path for feature docs.
4. Contextual help wiring. Pick one high-friction screen and deep-link a hintAction to a specific article slug via a route helper. This is the highest-leverage pattern the package enables and the strongest signal on whether the pilot works.
5. Sanitization and rendering decision. Markdown (Str::markdown in your own view override) vs. RichEditor HTML purified on output. Locked before volume authoring.
6. Instrumentation. Article views, search-with-no-results, and support-contact rate on the pilot screen — built by you, since none is native.
7. Pilot (4–6 weeks) with a named content owner and a published success criterion.
8. Decision. Adopt / fork / exit, with the exit already cheap by construction.

Operational Impact

Maintenance. Low code surface, non-trivial discipline surface. Engineering owns: pinned constraint, changelog review on each bump, and a re-publish-and-diff of config and migrations with --force in a throwaway branch before upgrading — that is how renamed config keys and new columns get caught before staging. Patches are low-risk (3.3.2 was a translation fix); minor-line movement is where attention goes. Product/support operations owns content freshness on a stated review cadence. Neither owner is optional.

Support. No vendor SLA and no formal support channel — the issue tracker is best-effort. Mitigations: keep the KB shallow enough that engineering can read the source; treat route/permission breakage as an internal escalation path; and dogfood — the KB should document the KB. Realistically the support burden is not "the package breaks," it's "nobody updated the article."

Scaling. Admin-side read volume is negligible. The real ceilings are: built-in search is almost certainly SQL LIKE over title/body, so relevance tuning and synonym matching are unavailable — plan the indexable column (title + stripped body) now so a Scout driver is a model change, not a data migration. If the reader view caches, wire Article::saved → Cache::forget or readers will see stale edits. Public-scale traffic to the reader routes is out of scope by design.

Failure modes and their tells.

• Migration never published → package appears broken; migrate silently no-ops.
• Route prefix collision → reader 404s; diagnose with route:list, never hardcode /knowledge-base/....
• Nav visible but 403 on click → policy mismatch, not a plugin bug; check Gate::forUser($user)->allows('viewAny', Article::class).
• Stale content for readers → cache toggle; disable outside production.
• Wrong article across tenants → unscoped slug uniqueness.
• HTML injection → unsanitized RichEditor output reaching readers.
• Silent break on Filament major upgrade → dependency hygiene gap.
• Abandonment → mitigated entirely by keeping bodies in git and the model thin (slug, title, category, body).

Ramp-up. A Filament-fluent developer is productive in under a day; the spike is the onboarding. Content authors need a one-page style guide, a template, and a review cadence — without those the taxonomy flattens into a single undifferentiated category within weeks. Support/ops need to know how to find and link a slug. The PM's real ramp-up task is governance, not technology: name the content owner, set the review cadence, define the pilot's success metric (ticket deflection on the chosen screen, article usage, search-no-result rate), and schedule the adopt/fork/exit decision before the pilot starts drifting into permanence.