Sillbeam Laravel Package

Product Decisions This Supports

• Build vs. buy for modular monolith governance: Sillbeam is not a feature your product ships to customers—it is an architectural capability your engineering org can adopt or replicate internally. This release gives you a credible third-party baseline when deciding whether to build custom module-boundary tooling (a homegrown Composer/naming-convention + PHPStan/Deptrac setup) or buy into an opinionated layer. MIT licensing and Symfony-native integration lower the cost of a trial.
• Architecture roadmap and team-scaling decisions: Explicit Modules with declared dependencies, plus validation for circular dependencies and undeclared cross-module references, directly supports decisions about when to split a monolith into separately owned bounded contexts, how to onboard new squads without trampling shared code, and where to enforce contracts in CI.
• Platform standardization: If you run multiple application surfaces (admin, customer portal, API, partner/private builds) on one Symfony runtime, the optional Projects concept is the decision-relevant feature. It is a composition mechanism for shared vs. private modules—not a multi-tenancy or isolation story. Use it to model "one codebase, several product surfaces," and explicitly not to model customer data isolation.
• Technical due diligence / risk register: Pre-1.0 status, PHP 8.4 and Symfony 7.4/8.x minimums, and incomplete static analysis (dynamic class references are not covered) are constraints that should appear in the risk register before it touches a revenue-critical path.
• Ecosystem fit check (important for this org): The release targets Symfony, not Laravel. If the current portfolio is Laravel-first, this package does not apply to existing services. It is relevant only to a Symfony 7.4/8.x initiative, a greenfield service where Symfony is on the table, or as a design reference whose concepts (module boundaries, dependency validation, composition over inheritance of a container) can inform an equivalent internal Laravel convention.
• Use cases worth piloting: greenfield Symfony service expected to grow past ~5 feature areas; a monolith showing circular-dependency pain in code review; a repository shared across multiple branded/downstream surfaces; teams already comfortable with Symfony autowiring, attributes, and DoctrineBundle.

When to Consider This Package

Consider adoption when most of the following hold:

• You have, or are actively starting, a Symfony 7.4 or 8.x application on PHP 8.4+ and Composer 2. (Confirm hosting, CI images, and any legacy PHP 8.1–8.3 services—this is a hard floor.)
• Architectural drift is an observed, named problem: cross-module static calls, unclear ownership, or reviewer fatigue around import discipline.
• You want enforcement in tooling (sillbeam:architecture) rather than a wiki page and goodwill.
• You need composition of shared modules across multiple application surfaces and are comfortable that Projects share one container and infrastructure.
• Your team is willing to pin to ^0.1.0 and absorb public-API change; you can isolate the dependency behind a small number of modules so a future migration is cheap.
• You do not require Doctrine—it is optional, so non-Doctrine or custom-persistence stacks are not blocked.

Look elsewhere, or defer, when any of the following hold:

• Your stack is Laravel. There is no Laravel integration in this release; forcing it is not a supported path.
• You need tenant isolation, per-tenant containers, or data segregation. Projects explicitly do not provide this. Reach for a real multi-tenancy solution instead.
• Your architecture depends on dynamically resolved class references (service locators, string-based container lookups, runtime plugin discovery). Static dependency analysis will silently miss those edges, so validation gives false confidence.
• You are pre-product-market-fit with a small team and a single surface—the module/project ceremony likely costs more than the coordination it saves. Start with simpler conventions and revisit.
• You require a stable, versioned public API with a support commitment. This is explicitly pre-1.0.
• You need documented production references, security review artifacts, or a commercial SLA. The release ships docs, a changelog, and an MIT license—not a support contract.

Adoption guardrails if you proceed: pin the exact minor, wrap the bundle registration and route import in your own config layer, write an ADR recording the version and the rationale, and set an explicit review trigger for the 0.2/1.0 releases (API stability is the main unresolved risk).

How to Pitch It (Stakeholders)

For executives: This is a low-cost, MIT-licensed architectural control, not a product dependency. It lets us enforce module boundaries automatically instead of relying on code review, which reduces coordination overhead as engineering headcount grows and makes ownership boundaries auditable. Cost of trial is measured in days, not quarters, and it is reversible because it sits on top of standard Symfony—we can remove it without rewriting the application. Two caveats to state plainly: it is a pre-1.0 release, so its interface may change; and it is Symfony-only, so it applies to Symfony initiatives, not our Laravel services—for those it is a design reference at most. It does not solve tenant isolation, and it does not catch every dependency edge.

For engineering leadership: Sillbeam adds declared module dependencies, dependency-graph validation (circular and cross-boundary violations), and optional composition of shared/private modules across several application surfaces—while keeping native Symfony services, routing, autowiring, and configuration overrides intact. Doctrine entity mappings are automatic per active module, and optional. Tooling is two console commands, so the operational surface is small. The honest limits: static analysis misses dynamic class resolution, so it complements—not replaces—runtime tests and review; Projects share one container, so they are a packaging story, not a security boundary.

For the engineering team: Value shows up in CI as a failing build when someone reaches across a module boundary, and in sillbeam:architecture as a readable map of what depends on what. Requirements are strict—PHP 8.4+, Symfony 7.4/8.x—so verify images before committing. Plan for the Flex recipe to be absent: expect manual bundle and route registration. Treat the public API as unstable: keep usage concentrated, avoid spreading module metadata into business logic, and track the changelog for the 0.2 and 1.0 releases before widening adoption.