Core Laravel Package

Technical Evaluation

Architecture fit. catchadmin/core is not a general-purpose Laravel library — it is the shared runtime layer of the CatchAdmin admin framework. It supplies base classes (Catch\Base\CatchController, Catch\Base\CatchModel), a route macro (Route::adminResource), an Excel import/export subsystem (Catch\Support\Excel\Import, AsyncTaskInterface + AsyncTaskDispatch), and a set of imposed conventions: unsigned-integer Unix timestamps for created_at/updated_at/soft-delete, enum values starting at 1, 1 = Enabled / 2 = Disabled status fields, creator_id in fillable lists, $fields/$form/$searchable/$dataRange model metadata, and setBeforeGetList() for list query shaping.

The fit is therefore narrow and conditional. It is a good fit if the requirement is "adopt CatchAdmin as our back-office platform." It is a poor fit if the requirement is "add an admin CRUD layer to our existing Laravel app," because core's value is inseparable from the surrounding module system (modules/{ModuleName}/, storage/app/modules.json, installer and service-provider stubs, codegen that writes Vue files into web/src/views/...). The decision to adopt is a platform decision, not a package decision, and should be framed that way to stakeholders.

Integration feasibility. Composer-installable and MIT-licensed, but not self-sufficient. Every documented flow assumes a project skeleton plus a separately cloned Vue frontend (gitee.com/catchadmin/catch-admin-vue, branch v5) and php artisan catch:module:install --all. The install guidance starts from "a project root containing composer.json" and defers to a manual-install reference — there is no visible standalone quickstart. Realistically, integration means forking or adapting a template repository, not composer require into a running product.

Technical risk. High, driven by ecosystem signals rather than any judgement of code quality:

Key questions to resolve before commitment:

1. Is catchadmin/core byte-identical to what ships inside CatchAdmin Pro, and does the MIT grant survive the free/Pro split for the modules we need?
2. What is the supported Laravel/PHP version matrix, and what is the upgrade policy across Laravel majors?
3. Is there a release/versioning contract (semver, changelog, deprecation notices), or is 2024-09-10 a one-off cut?
4. How are upgrades delivered when codegen has already written generated files into our application code? Is regeneration idempotent?
5. Does Route::adminResource collide with macros we already register, and how does it interact with Sanctum/Passport?
6. Is there a maintained mirror of the Vue frontend outside Gitee (GitHub, Packagist dist), and what is the license on the frontend repo?
7. Who supports this commercially, with what SLA, and in what language?
8. How does $dataRange row-level permission filtering behave on large tables — is it SQL-side or post-filtered in PHP?

Integration Approach

Stack fit. PHP 8.3+, current Laravel, MySQL, Composer; Node 22+, Yarn, Vue 3 + Element Plus. This matches a conventional Laravel shop with a Vue frontend — no exotic runtime, no nonstandard infrastructure. The unfamiliar surface is convention, not technology.

Migration path. Three viable shapes, in descending order of preference:

• Sidecar (recommended for brownfield). Deploy CatchAdmin as a separate application on an admin subdomain, sharing the primary database read/write through a deliberately thin contract. Legacy domain code stays untouched; CatchAdmin owns only admin-facing tables and read models. Cost: a second deploy target, duplicated auth or SSO bridging.
• In-app coexistence. Install into the existing Laravel application but restrict CatchModel/CatchController usage to new modules only. Existing controllers keep Eloquent and standard route registration. Requires a written boundary rule and lint/review enforcement, because the framework's conventions will otherwise leak into legacy code.
• Greenfield admin behind an API. Build the back office fresh against the domain API. Cleanest adoption, highest build cost; only sensible if the current admin surface is being replaced anyway.

Do not plan a wholesale refactor of existing models onto CatchModel. The timestamp representation alone (integer Unix vs. Eloquent datetime) makes that a data-migration project with no product payoff.

Compatibility work items.

• Timestamps and soft deletes. Core expects unsignedInteger created_at/updated_at/deleted_at. Existing tables almost certainly use timestamp. Either keep CatchAdmin models pointed at framework-native tables with explicit casts, or introduce views/adapter models at the boundary. Resolve this in the spike, not in sprint 4.
• Status semantics. 1 = Enabled / 2 = Disabled versus common 0/1 or boolean flags. Plan a mapping layer; do not silently reinterpret existing rows.
• Route macros. Audit registered macros before adopting Route::adminResource; confirm no collision and that route caching still works.
• Frontend toolchain. Pin Node/Yarn versions in CI; the v5 branch and Yarn assumption are fixed constraints, not preferences.
• Async execution. AsyncTaskInterface and AsyncTaskDispatch imply a queue worker. Confirm queue driver, worker capacity, and monitoring exist before enabling import/export in production.

Sequencing (indicative, one senior Laravel dev plus part-time Vue):

1. Spike, 2 weeks. Install from the template, stand up auth + RBAC, build one real module by hand, generate one module with codegen, run one async import and one export. Exit criteria: documented answer to the timestamp/status mapping and a working upgrade re-pull.
2. Scaffold and identity, 2–3 weeks. Module skeleton, service providers, storage/app/modules.json registration, menu/permission wiring, CI for both apps.
3. First production module, 3 weeks. Thin controller (CatchController), model with $fields/$form/$searchable, Route::adminResource before the //next marker, Vue list page with catch-table plus form/create.vue using useCreate/useShow and inject('closeDialog').
4. Data-in/out, 2 weeks. Import classes under modules/{Module}/Excel/Import/, $start matched to the real first data row, $importMaxNum respected, async path for large files, export classes under Excel/Export/.
5. Hardening, ongoing. Internal fork with pinned commit, upgrade rehearsal, ADRs capturing the conventions from the skill docs as our own spec.

Budget roughly 9–11 weeks to a first production module with one experienced developer, plus part-time frontend. Assume an internal fork from day one rather than consuming upstream directly.

Operational Impact

Maintenance. Plan to own the code. With 5 stars, zero dependents, and a single release in September 2024, the practical model is an internal fork you patch yourself and periodically rebase. Bug fixes, Laravel-major upgrades, and security patches to the framework layer become your backlog, not a vendor's. Additionally, codegen writes generated controllers, routes, and Vue pages directly into the repository, so any upstream generator change becomes a merge exercise across every module you have generated.

Support. No commercial support path is visible for the core package; the Pro tier may offer one — verify before signing off. Documentation is Chinese-first and structured as agent skills (catchadmin-backend, catchadmin-codegen, catchadmin-import, catchadmin-frontend, catchadmin-install, catchadmin-module, catchadmin-upload), which is genuinely useful as executable convention guidance but is not an API reference and will not answer "what does this method return." Assign named owners (one backend, one frontend) and convert the skill rules into internal ADRs so knowledge is not held by a single person.

Scaling. The underlying scaling story is conventional Laravel: horizontal app servers, a queue worker pool for AsyncTaskInterface jobs, standard DB tuning. Pressure points specific to this stack:

• $dataRange row-level permission filters applied to list queries can produce expensive predicates on large tables — validate execution plans early and index creator_id and any scoped columns.
• Import throughput is chunked (200 rows per chunk in the documented example) with a 5,000-row default ceiling; the async path is mandatory above that. Size the worker pool against peak upload concurrency, not average.
• Admin list endpoints backed by catch-table tend to request wide column sets; pagination and column projection need to be deliberate.

Failure modes to instrument and rehearse:

• Upstream dormancy — no release for a year-plus; treat as expected, not exceptional. Mitigation: fork, pinned commit, owned patch stream.
• Frontend source loss or relocation — the Vue repo lives on Gitee at a branch ref (v5). Mirror it internally on day one; do not let a build depend on reachability of an external host.
• Generator drift — regenerating a module after an upstream change can silently overwrite hand edits. Enforce a review gate and a "generated files are committed, never hand-edited" rule, or a marker-based diff.
• Data-permission leakage — a misconfigured $dataRange either over-broadens visibility (a data incident) or over-narrows it (an apparent outage). Needs an explicit test matrix, not just a config review.
• Timestamp/status mismatch at the boundary — silent timezone or semantics errors when CatchAdmin models touch legacy tables. Cover with contract tests on any shared table.
• Partial async import — a mid-chunk failure can leave a partially written dataset. Design for idempotent re-runs and a status the operator can see.
• Route macro collision or route-cache failure — manifests as a 404 storm at deploy. Include route:cache and config:cache in the pre-deploy smoke test.
• Toolchain rot — Node 22/Yarn pins age faster than the PHP side; treat frontend dependency upgrades as scheduled maintenance.

Ramp-up. Laravel developers should reach productivity on core conventions in roughly one to two weeks, given the model metadata ($fields, $form, $searchable, $dataRange) and the thin-controller pattern. Vue developers typically need a few days on catch-table, useCreate, useShow, and the dialog closeDialog injection contract. The real onboarding cost is not the code — it is the absence of prose documentation. Schedule a half-day conventions workshop, record the output as internal documentation, and require every new module to match the nearest existing module's shape before introducing new patterns. Treat the first module as a training artifact: build it by hand, then verify codegen reproduces something equivalent.