Instruction file imported from DennyAzevedo/vibroacustico (.cursor/rules/backend/laravel-architecture-and-boundaries.mdc). Copyright stays with the author.

Laravel architecture and boundaries

Choose the least complex architecture that satisfies current requirements.

• Use a simple monolith for limited complexity, one-team ownership, shared transactions, and operational simplicity.
• Use a modular monolith when distinct business capabilities need enforced internal boundaries but one deployment remains desirable.
• Extract a service only for concrete independent deployment, scaling, ownership, failure isolation, security, or runtime requirements.
• Define modules around business capabilities, with clear ownership of tables, models, rules, and workflows.
• Avoid bidirectional module dependencies and direct writes to another module's owned data.
• Domain code must not depend on requests, sessions, controllers, Blade, Livewire, Eloquent, queues, or facades when a pure domain boundary is intentionally used.
• Prefer direct application calls inside one deployment; use events for decoupled reactions, queues for delayed/retryable work, and HTTP or messaging only across real deployment boundaries.
• Keep immediately consistent changes in one local transaction and model eventual consistency explicitly.
• Introduce read models, CQRS, outbox, brokers, or event sourcing only when reporting, scale, reliability, or change patterns justify them.
• Evolve architecture incrementally with characterization tests, reversible steps, migration controls, comparison, and rollback.