From d74e7553dcf933f37bf6ee8f9b5ba061834fd569 Mon Sep 17 00:00:00 2001 From: ChrisAbner Date: Thu, 12 Nov 2026 14:06:51 -0500 Subject: [PATCH] docs: add Krayin CRM and Leantime case studies --- docs-site/.vitepress/config.mts | 2 + docs-site/case-studies/index.md | 11 +++-- docs-site/case-studies/krayin.md | 72 ++++++++++++++++++++++++++++ docs-site/case-studies/leantime.md | 77 ++++++++++++++++++++++++++++++ 4 files changed, 158 insertions(+), 4 deletions(-) create mode 100644 docs-site/case-studies/krayin.md create mode 100644 docs-site/case-studies/leantime.md diff --git a/docs-site/.vitepress/config.mts b/docs-site/.vitepress/config.mts index 242299a..fc72b19 100644 --- a/docs-site/.vitepress/config.mts +++ b/docs-site/.vitepress/config.mts @@ -88,6 +88,8 @@ export default defineConfig({ { text: 'Bagisto', link: '/case-studies/bagisto' }, { text: 'Advising App', link: '/case-studies/advisingapp' }, { text: 'LaravelEcomm', link: '/case-studies/laravelecomm' }, + { text: 'Krayin CRM', link: '/case-studies/krayin' }, + { text: 'Leantime', link: '/case-studies/leantime' }, ], }, { diff --git a/docs-site/case-studies/index.md b/docs-site/case-studies/index.md index 3714a55..171ea28 100644 --- a/docs-site/case-studies/index.md +++ b/docs-site/case-studies/index.md @@ -1,23 +1,26 @@ # Case studies -We ran Cordon Modulith on three open source Laravel applications, one for each kind of module structure it supports. The goal was to check that it works on real code, find false positives, and see what kind of coupling grows in real modular monoliths. +We ran Cordon Modulith on five open source Laravel applications, covering every kind of module structure it supports. The goal was to check that it works on real code, find false positives, and see what kind of coupling grows in real modular monoliths. | Application | Structure | Modules | Files | Violations (default config) | Violations (public API declared) | Time | |---|---|---|---|---|---|---| | [Bagisto](./bagisto) | Namespaces (`packages/Webkul/*`) | 42 | 1,997 | 1,086 | 325 | 6.1 s | | [Advising App](./advisingapp) | InterNACHI/modular | 37 | 2,463 | 1,363 | 1,355 | 4.5 s | | [LaravelEcomm](./laravelecomm) | nwidart/laravel-modules | 29 | 1,098 | 904 | 522 | 2.7 s | +| [Krayin CRM](./krayin) | Namespaces (`packages/Webkul/*`) | 20 | 632 | 475 | 159 | 0.8 s | +| [Leantime](./leantime) | Plain folders (`app/Domain/*`) | 45 | 522 | 587 | 310 | 1.1 s | -All three were analysed in October 2026 on Laravel 13 and PHP 8.4. Each page lists the exact commit. The violation counts are those of Cordon 0.2.0, which reports one `cycles` violation per dependency inside a cycle (167, 201 and 127 here); they were recomputed at the same commits on 2026-11-04. Before 0.2.0, each group of tangled modules was a single violation. +Krayin and Leantime were added on 2026-11-12, analysed with Cordon 0.4.0 and `host.paths` set to `[]`, in a Docker container limited to 2 CPUs. The first three were analysed in October 2026 on Laravel 13 and PHP 8.4. Each page lists the exact commit. The violation counts are those of Cordon 0.2.0, which reports one `cycles` violation per dependency inside a cycle (167, 201 and 127 here); they were recomputed at the same commits on 2026-11-04. Before 0.2.0, each group of tangled modules was a single violation. **Re-checked with 0.4.0 (2026-11-11).** At the same commits and with the same configs, 0.4.0 reports exactly the same errors as 0.3.1 in all three apps (`internal_access` and `cycles`, byte for byte). What changes is that 0.4.0 also analyses the code outside the modules by default (the [`host`](../guide/configuration) module: `app`, `routes`, `database`), so more files are read (2,012, 3,041 and 1,165) and two new kinds of warning appear. Warnings never fail the build: `host_access` (1, 216 and 114: code outside the modules using a module's internals) and `public_api_leak` (1, 37 and 1: a public class exposing an internal one). Setting `host.paths` to `[]` gives back the figures in the table. ## What we found -- **No false positives.** We checked every one of the 2,858 `internal_access` reports by machine: the reported line contains the class (or its import alias), and the class is declared in the module Cordon named. We then read a sample of each kind by hand. Every report pointed at a real reference: inheritance, constructor injection, static calls, Eloquent relations or `instanceof`. +- **No false positives.** In the first three apps we checked every one of the 2,858 `internal_access` reports by machine: the reported line contains the class (or its import alias), and the class is declared in the module Cordon named. We then read a sample of each kind by hand. Every report pointed at a real reference: inheritance, constructor injection, static calls, Eloquent relations or `instanceof`. In Krayin and Leantime we read 25 and 20 reports at random by hand, with the same result. - **Most of the first report is configuration, not coupling.** Out of the box, Cordon only treats `Contracts`, `Events`, `Data`, `Enums` and `Exceptions` as public. Real apps share more on purpose: a `Core` module every other module extends, repositories meant as the access layer, facades. Declaring those removed 83% of Bagisto's `internal_access` reports and half of LaravelEcomm's. See [what we declared and why](#how-we-declared-the-public-api). - **What remains is real.** A handful of models used by almost every module (`User` in 25 of 29 modules in LaravelEcomm, `Student` in 21 of 37 in Advising App), order status constants read straight from the `Order` model, and storefront code reaching into sales internals. -- **Cycles are the norm.** In all three apps, most modules belong to one large group that depends on itself: 30 of 42 modules in Bagisto, 29 of 37 in Advising App, 25 of 29 in LaravelEcomm. Counting direct back-and-forth pairs (`A` uses `B` and `B` uses `A`): 26, 54 and 34. +- **Cycles are the norm.** In all five apps, at least half of the modules belong to one large group that depends on itself: 30 of 42 modules in Bagisto, 29 of 37 in Advising App, 25 of 29 in LaravelEcomm, 19 of 20 in Krayin and 24 of 45 in Leantime. Counting direct back-and-forth pairs (`A` uses `B` and `B` uses `A`): 26, 54, 34, 25 and 32. +- **Declaring a public API never removes a cycle.** It removes access reports, but in all five apps the cycle groups are exactly the same before and after. In Leantime some cycles go only through services, which are public there. - **Fast enough for CI.** Between 3 and 6 seconds and under 160 MB of memory for 1,000 to 2,500 files, on a developer machine (8 cores, Docker on WSL2). These are snapshots of how the code is organised, not judgments. Many of these dependencies are deliberate trade-offs, and none of these projects claims to enforce module boundaries. They show what happens when boundaries are only a folder convention. diff --git a/docs-site/case-studies/krayin.md b/docs-site/case-studies/krayin.md new file mode 100644 index 0000000..beb1902 --- /dev/null +++ b/docs-site/case-studies/krayin.md @@ -0,0 +1,72 @@ +# Krayin CRM + +[Krayin CRM](https://github.com/krayin/laravel-crm) is an open source CRM built by Webkul, the team behind Bagisto. It uses the same layout: 20 packages under `packages/Webkul`, each with its own service provider, Concord model proxies and repositories. The packages cover contacts (`Contact`), the sales pipeline (`Lead`, `Quote`, `Product`), activities and email (`Activity`, `Email`, `EmailTemplate`), automation (`Automation`, `WebForm`) and a shared kernel (`Core`, `DataGrid`). + +**Analysed:** commit [`ed6deeb`](https://github.com/krayin/laravel-crm/tree/ed6deebfcb8c616eaf352c893a10a6d8e666fc6e) on the `2.2` branch, November 2026, with Cordon 0.4.0 and PHP 8.4. + +## Results + +| | Default config | Public API declared | +|---|---|---| +| Modules | 20 | 20 | +| Files analysed | 632 | 632 | +| Cross-module references | 467 | 467 | +| `internal_access` | 368 | 52 | +| `cycles` | 107 dependencies in 1 group of 19 modules | 107 dependencies in 1 group of 19 modules | +| Time | 0.8 s | 0.8 s | + +We read 25 reports at random by hand. All 25 pointed at a real reference. + +## Configuration + +Krayin shares Bagisto's conventions, so we declared the same things: the shared kernel, repositories, facades and the model proxies. + +```php +// config/cordon.php +'resolver' => 'namespace', + +'resolvers' => [ + 'namespace' => ['path' => 'packages/Webkul', 'namespace' => 'Webkul'], +], + +'host' => ['paths' => []], + +'public_namespaces' => ['Contracts', 'Events', 'Data', 'Enums', 'Exceptions', 'Repositories', 'Facades'], + +'modules' => [ + 'Core' => ['open' => true], + 'DataGrid' => ['open' => true], + // and every Models\*Proxy class, listed per module, for example: + 'Lead' => ['public' => ['Models\\LeadProxy', 'Models\\PipelineProxy', 'Models\\ProductProxy', 'Models\\SourceProxy', 'Models\\StageProxy', 'Models\\TypeProxy']], +], +``` + +The first report was mostly configuration. The base repository `Core\Eloquent\Repository` alone had 40 references, and the repositories of `Attribute`, `Contact` and `Lead` another 81. Declaring the kernel, the repositories and the proxies removed 316 of the 368 reports. + +## What remains + +The remaining 52 reports are small and easy to read: + +| Class | References | From modules | +|---|---|---| +| `Attribute\Traits\CustomAttribute` | 6 | 5 | +| `Activity\Traits\LogsActivity` | 5 | 5 | +| `Admin\Notifications\Common` | 4 | 1 | +| `Attribute\Models\AttributeValue` | 3 | 2 | + +The two traits are extension points: every entity with custom attributes uses `CustomAttribute`, and every entity that logs changes uses `LogsActivity`. That is intended, so the fix is to declare them public. `Automation` sending a mail class that lives in `Admin` is the same pattern as `Sales` sending a `Shop` mail in Bagisto. + +## A cycle between two classes + +19 of the 20 packages belong to one group of mutually dependent modules, with 25 direct back-and-forth pairs. The smallest one fits in two files: + +```php +// packages/Webkul/Attribute/src/Models/AttributeValue.php +use Webkul\Activity\Traits\LogsActivity; + +// packages/Webkul/Activity/src/Traits/LogsActivity.php +use Webkul\Attribute\Contracts\AttributeValue; +use Webkul\Attribute\Repositories\AttributeValueRepository; +``` + +The activity log knows about attribute values, and attribute values log activity. Declaring the trait public makes the access legal, but the cycle stays: `Attribute` and `Activity` still cannot change on their own. diff --git a/docs-site/case-studies/leantime.md b/docs-site/case-studies/leantime.md new file mode 100644 index 0000000..ab6b575 --- /dev/null +++ b/docs-site/case-studies/leantime.md @@ -0,0 +1,77 @@ +# Leantime + +[Leantime](https://github.com/Leantime/leantime) is an open source project management system. It is not built on a module package: its 45 modules are plain folders under `app/Domain`, each with its own controllers, services, repositories, models and templates. They cover projects and tickets (`Projects`, `Tickets`, `Sprints`, `Timesheets`), planning boards (`Canvas`, `Goalcanvas`, `Blueprints`, `Ideas`), users and access (`Users`, `Auth`, `Ldap`, `Oidc`) and the app shell (`Menu`, `Setting`, `Notifications`). + +**Analysed:** commit [`bbba712`](https://github.com/Leantime/leantime/tree/bbba712e69e43971cb103033ac6048bd073d1e63) (release v3.14.0), November 2026, with Cordon 0.4.0 and PHP 8.4. Cordon does not analyse Blade templates, so the 380 `*.blade.php` files are not part of these numbers. + +## Results + +| | Default config | Public API declared | +|---|---|---| +| Modules | 45 | 45 | +| Files analysed | 522 | 522 | +| Cross-module references | 766 | 766 | +| `internal_access` | 443 | 166 | +| `cycles` | 144 dependencies in 1 group of 24 modules (plus 1 group of 2) | same | +| Time | 1.2 s | 1.1 s | + +We read 20 reports at random by hand. All 20 pointed at a real reference. + +## Configuration + +Leantime's own layering says how modules should talk: controllers call services, services call repositories. So we declared the services as the public API, plus the `Permissions` classes, which only hold constants. + +```php +// config/cordon.php +'resolver' => 'namespace', + +'resolvers' => [ + 'namespace' => ['path' => 'app/Domain', 'namespace' => 'Leantime\\Domain'], +], + +'host' => ['paths' => []], + +'public_namespaces' => ['Contracts', 'Events', 'Data', 'Enums', 'Exceptions', 'Services', 'Permissions'], +``` + +Services were the biggest part of the first report: `Projects\Services\Projects` alone had 52 references and `Tickets\Services\Tickets` 27. Declaring them removed 277 of the 443 reports. + +## What remains + +Most of the remaining 166 reports skip the service layer and go straight to another module's repository (115) or model (42): + +| Class | References | From modules | +|---|---|---| +| `Auth\Models\Roles` | 23 | 16 | +| `Setting\Repositories\Setting` | 20 | 12 | +| `Users\Repositories\Users` | 19 | 13 | +| `Tickets\Repositories\Tickets` | 14 | 11 | +| `Notifications\Models\Notification` | 13 | 9 | + +```php +// app/Domain/Auth/Services/Auth.php +public SettingRepository $settingsRepo; + +// app/Domain/Connector/Controllers/Providers.php +Auth::authOrRedirect([Roles::$owner, Roles::$admin, Roles::$manager, Roles::$editor]); +``` + +`Roles` is a set of role constants read by 16 modules, a good candidate for an enum. The repositories are the more interesting part: `Users` and `Setting` both have a service, yet a dozen modules read their repositories directly. Declaring `Repositories` public as well would bring the report down to 89, but it would also hide the fact that the service layer is being bypassed. We left them reported. + +Declaring the services surfaced 27 `public_api_leak` warnings: public service methods that take or return internal models, such as `Blueprints\Services\TemplateRegistry::get()` returning a `CanvasTemplate` model. + +## Cycles through public services + +24 of the 45 modules belong to one group of mutually dependent modules, with 32 direct back-and-forth pairs. Some of those cycles go only through services, which are public here: + +```php +// app/Domain/Menu/Services/Menu.php +use Leantime\Domain\Projects\Services\Projects as ProjectService; + +// app/Domain/Projects/Hxcontrollers/ProjectCard.php +use Leantime\Domain\Menu\Services\Menu; +``` + +Every reference is legal, and `Menu` and `Projects` still depend on each other. Declaring a public API removes access reports. It never removes a cycle. + +Leantime has the smallest cycle group of the five apps we measured (53% of its modules). Its modules are also the smallest: 12 files each on average, against 32 to 67 in the other four.