🧠 Context
I have begun refactoring portions of the codebase to improve modularity, maintainability, and testability. Two key refactor PRs have already been submitted:
These represent significant progress toward a cleaner architecture that is better aligned with SOLID principles and modern Laravel best practices.
❗ Problem Statement
While the initial refactors have improved certain areas, the following issues remain:
- Inconsistent service registration and resolution patterns
- Tight coupling between controllers and domain logic in some areas
- Limited automated test coverage on refactored components
- Lack of a clearly defined roadmap for completing the refactor effort
- Potential regressions due to incremental structural changes
Without an overarching tracking issue, further refactor work risks becoming fragmented or inconsistent.
🎯 Objectives
This issue aims to:
- Justify the need for continued refactoring
- Track remaining and future refactor work
- Define architectural direction and boundaries
- Provide a single reference point for related PRs
📦 Why This Refactor Matters
🔹 Improved Maintainability
By extracting business logic into dedicated services and enforcing clearer architectural boundaries, contributors can reason about the codebase more easily and make changes with reduced risk.
🔹 Better Testability
Services with well-defined responsibilities are easier to unit test. This reduces reliance on feature tests for logic validation and improves confidence in changes.
🔹 Enhanced Separation of Concerns
Controllers should handle HTTP concerns only. Business logic should reside in services. Domain logic should remain independent of transport layers.
🔹 Long-Term Scalability
A consistent architectural pattern ensures future features can be implemented without compounding technical debt.
🧩 Scope of Work
✅ Already Completed
🔄 Remaining / Future Work
This list should be updated as additional refactor opportunities are identified.
🤝 Contribution & Ownership
I am more than happy to take ownership of this refactor initiative and continue progressing it independently if needed.
However, in the spirit of maintaining a healthy open-source contribution model, it may be beneficial to break this work down into smaller, well-defined issues. This would allow other contributors to participate in discrete parts of the refactor (e.g. individual service extractions, test additions, or controller clean-ups) without needing to take on the entire architectural scope.
Where appropriate, follow-up issues can be created and linked to this one to encourage collaborative progress.
🧪 Risks & Mitigations
Risk: Merge Conflicts and Fragmentation
Mitigation:
- Keep refactor PRs focused and small
- Frequently rebase against the main branch
- Clearly reference this issue in all related PRs
Risk: Behavioural Regressions
Mitigation:
- Add or improve automated test coverage before modifying logic
- Avoid mixing structural refactors with functional changes
- Validate API contracts remain unchanged unless explicitly intended
📌 Definition of Done
The refactor initiative can be considered complete when:
- Controllers contain no business logic
- Services follow consistent binding and resolution patterns
- Extracted logic is covered by appropriate unit tests
- Architecture documentation reflects the implemented structure
- No outstanding structural inconsistencies remain
📝 Notes
- All refactor-related PRs should reference this issue (e.g.
Closes #<issue-number> where appropriate).
- This issue acts as an epic/tracking issue for the broader architectural improvements.
- Functional changes should be kept separate from structural refactors wherever possible.
Suggested Labels
refactorarchitecturetechnical-debtenhancementtesting
🧠 Context
I have begun refactoring portions of the codebase to improve modularity, maintainability, and testability. Two key refactor PRs have already been submitted:
🔄 Refactor: Additional Refactoring of Jobs #4549: Refactoring of service layers, service providers, and improvements to dependency resolution.
🔄 Refactor: VATSIM.net Webhook Processing (Improved Observability & Safety) #4545: Refactor of key domain logic and extraction of business logic into services.
🔄 Refactor: Remove Business Logic from Controllers & Introduce DTO-Oriented Services #4559: Remove Business Logic from Controllers
🔄 Refactor: standardise service binding patterns in service providers #4577: Standardise service binding patterns within service providers
These represent significant progress toward a cleaner architecture that is better aligned with SOLID principles and modern Laravel best practices.
❗ Problem Statement
While the initial refactors have improved certain areas, the following issues remain:
Without an overarching tracking issue, further refactor work risks becoming fragmented or inconsistent.
🎯 Objectives
This issue aims to:
📦 Why This Refactor Matters
🔹 Improved Maintainability
By extracting business logic into dedicated services and enforcing clearer architectural boundaries, contributors can reason about the codebase more easily and make changes with reduced risk.
🔹 Better Testability
Services with well-defined responsibilities are easier to unit test. This reduces reliance on feature tests for logic validation and improves confidence in changes.
🔹 Enhanced Separation of Concerns
Controllers should handle HTTP concerns only. Business logic should reside in services. Domain logic should remain independent of transport layers.
🔹 Long-Term Scalability
A consistent architectural pattern ensures future features can be implemented without compounding technical debt.
🧩 Scope of Work
✅ Already Completed
🔄 Remaining / Future Work
This list should be updated as additional refactor opportunities are identified.
🤝 Contribution & Ownership
I am more than happy to take ownership of this refactor initiative and continue progressing it independently if needed.
However, in the spirit of maintaining a healthy open-source contribution model, it may be beneficial to break this work down into smaller, well-defined issues. This would allow other contributors to participate in discrete parts of the refactor (e.g. individual service extractions, test additions, or controller clean-ups) without needing to take on the entire architectural scope.
Where appropriate, follow-up issues can be created and linked to this one to encourage collaborative progress.
🧪 Risks & Mitigations
Risk: Merge Conflicts and Fragmentation
Mitigation:
Risk: Behavioural Regressions
Mitigation:
📌 Definition of Done
The refactor initiative can be considered complete when:
📝 Notes
Closes #<issue-number>where appropriate).Suggested Labels
refactorarchitecturetechnical-debtenhancementtesting