📌 Continue & Complete Refactor Work for Core Services

[MrAdder]

🧠 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:

• 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:

1. Justify the need for continued refactoring
2. Track remaining and future refactor work
3. Define architectural direction and boundaries
4. 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

• PR 🔄 Refactor: Additional Refactoring of Jobs #4549 – Service layer refactor and dependency improvements
• PR 🔄 Refactor: VATSIM.net Webhook Processing (Improved Observability & Safety) #4545 – Extraction of business logic into services
• PR 🔄 Refactor: Remove Business Logic from Controllers & Introduce DTO-Oriented Services #4559 – Remove remaining business logic from controllers & Identify and refactor tightly coupled domain logic
• PR 🔄 Refactor: standardise service binding patterns in service providers #4577 – Standardise service binding patterns within service providers
• PR 📝 Docs: Streamline Contributing, Issue, PR and Architecture Documentation #4613 - Document Refactor

🔄 Remaining / Future Work

• Add unit tests for all newly extracted services
• Standardise service binding patterns within service providers
• Update architecture and contributing documentation
• Review API response consistency after refactors
• Audit for duplicated logic introduced during refactors

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

• refactor
• architecture
• technical-debt
• enhancement
• testing

[linear]

TECH-519

[MrAdder]

@AxonC if you are still having issues with Teamspeak I can relook at its implementation if required and include it in the refactors