📝 Docs: Streamline Contributing, Issue, PR and Architecture Documentation

.github/CONTRIBUTING.md

@@ -1,65 +1,82 @@
-# Welcome
+# Contributing to Core
 
-Welcome to the VATSIM UK Core repository. VATSIM UK has a dedicated team who are members of the VATSIM UK staff team who are ultimately responsible for the upkeep and development of VATSIM UK systems. The team maintains a backlog of work outside of this repository, but issues of which open-source contributions are welcomed will be added under 'Issues' in this repository.
+Welcome, and thanks for your interest in contributing to VATSIM UK Core.
 
-If you don't see any interesting issues open but still want to contribute, please [reach out](https://github.com/VATSIM-UK/core/blob/main/.github/SUPPORT.md).
+## Before You Start
 
-Some issues simply can't be delegated to outside contributors as they may require elevated access.
+- Read the local setup guide: [setup.md](https://github.com/VATSIM-UK/core/blob/main/.github/setup.md)
+- Read the architecture guide: [docs/architecture.md](https://github.com/VATSIM-UK/core/blob/main/docs/architecture.md)
+- If you need help, use the support page: [SUPPORT.md](https://github.com/VATSIM-UK/core/blob/main/.github/SUPPORT.md)
 
-## Contributor license agreement
+## Contribution Scope
 
-By submitting code as an individual you agree that VATSIM UK can use your amendments, fixes, patches, changes, modifications, submissions and creations in the production of the UK Core and that the ownership of your submissions transfers to VATSIM UK in their entirety. More info on the licensing can be found in [LINCENSE](https://github.com/VATSIM-UK/core/blob/consolidate-dev-docs/LICENSE.md)
+Some work cannot be delegated publicly due to privileged access requirements. Publicly open issues are suitable for external contribution.
 
-## Contributing to the codebase
+If you are new to the project, start with issues labeled `good-first-issue` or `up-for-grabs`.
 
-If you're just getting started with GitHub (and project contributions) then we suggest you take a look at issues marked with both the "up-for-grabs" and/or "good-first-issue" labels. These issues will be of reasonable size and challenge while not being as overly complex as others and a good introduction for anyone who wants to start contributing to the project.
+## Contributor License Agreement
 
-If you're comfortable with contributing to Open Source projects on GitHub please ensure you read our expectations for issue tracking, feature proposals and merge requests.
+By submitting a contribution (including amendments, fixes, patches, changes, modifications, submissions, and creations) to this repository, you agree to license your contribution under the same terms as the project: the MIT License. You retain ownership of your contributions, but grant VATSIM UK and all recipients of the software a perpetual, worldwide, non-exclusive, royalty-free license to use, modify, and distribute your contributions as part of the project.
 
-## Running Core locally
+See [LICENSE.md](https://github.com/VATSIM-UK/core/blob/main/LICENSE.md) for the full license text.
 
-To run core locally, please read our [setup guide](https://github.com/VATSIM-UK/core/blob/main/.github/setup.md)
+## Issue Workflow
 
-## Issue Tracking
+- Search existing issues before opening a new one.
+- Use the issue template and provide complete reproduction/context details.
+- Add screenshots or documentation links when helpful.
+- If you cannot self-assign, comment on the issue to indicate you are taking it.
 
-If you require **support** with the Core Project, please read the [support page](https://github.com/VATSIM-UK/core/blob/main/.github/SUPPORT.md).
-When submitting an issue, there are a few guidelines we'd ask you to respect to make it easier to manage (and for others to understand):
+## Pull Request Workflow
 
-* **Search the issue tracker** before you submit your issue - it may already be present.
-* When opening an issue, a template is provided for you. Please provide as much information as requested to ensure others are able to act upon the requests or bug report.
-* Please ensure you add screenshots or documentation references for bugs/changes so we can quickly ascertain if the request is suitable.
+1. Fork the repository.
+2. Implement a focused change set for one issue.
+3. Add or update tests as required.
+4. Push to your fork and open a PR to `main`.
+5. Link the related issue in the PR description.
 
-**If you can't assign yourself to an issue** please comment on the issue to let people know you're taking it on.
+### PR Expectations
 
-## Pull Requests
+- PR title clearly describes the change.
+- PR description includes:
+  - What changed
+  - Why it changed
+  - How it was verified
+  - Whether behavior changed or should be identical
+- Include screenshots for UI changes.
+- Keep structural refactors and functional feature changes separate where possible.
 
-We welcome pull requests with fixes and improvements to the Core project. The features we really would like public support on are marked with "up-for-grabs" or "good first issue" but other improvements are also welcome - please ensure you read over the pull workflow below.
+## Architecture Expectations for New Work
 
-If you wish to add a new feature or you spot a bug that you wish to fix, **please open an issue for it first** on the [UK Core issue tracker](https://github.com/VATSIM-UK/core/issues).
+Core is actively being refactored. Contributions should follow the architecture standards from [docs/architecture.md](https://github.com/VATSIM-UK/core/blob/main/docs/architecture.md).
 
-The workflow for submitting a new pull request is designed to be simple, but also to ensure consistency from **all** contributors:
+In practice, this means:
 
-* Fork the project into your personal space on GitHub.com.
-* Create a new branch (with the name `issue-[issue_number]`, replacing [issue_number] with the issue number you're resolving), e.g. `issue-1234`.
-* Commit your changes.
-* *When writing commit messages, consider closing your issues via the commit message (by including "fix #22" or "fixes #22", for example).*
-* *The issues will be referenced in the first instance and then closed once the MR is accepted.*
-* Push the commit(s) to your fork.
-* Submit a pull request (PR) to the main branch.
-* The PR title should describe the change that has been made.
-* The PR description should confirm what changes have been made and how you know they're correct (with references).
-* *Please include any relevant screenshots to prove the changes work*
-* Ensure you link any relevant issues in the merge request (you can type hash and the issue ID, e.g. #275). Comment on those issues linking back to the PR (you can reference PRs in the same way as issues, using the format #pr-id).
-* Be prepared to answer any questions about your PR when it is reviewed for acceptance.
+- Keep controllers focused on HTTP concerns.
+- Move business/domain logic into services.
+- Prefer structured service outputs (DTO-style payloads or DTO classes).
+- Keep dependency injection and service bindings consistent.
+- For queued external integrations, use dedicated queues plus overlap/rate-limit protections.
 
-**Please** keep your changes in a single PR as small as possible (relating to one issue) as this makes it easier to review and accept. Large PRs with a small error will prevent the entire PR from being accepted.
+## Testing Requirements
 
-# Expectations
+Refactors and behavior changes require meaningful coverage:
 
-As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting merge requests or patches, and other activities.
+- Add unit tests for extracted or newly introduced services.
+- Keep feature tests validating external contracts (status codes, payload shape, auth behavior).
+- Add job configuration tests when queue names, middleware, retries, or backoff are part of the change.
 
-We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or favourite aircraft.
+PRs without adequate test coverage may be asked to add tests before merge.
 
-Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, issues and other contributions that are not aligned to this Code of Conduct.
+## Refactor PR Guidelines
 
-This Code of Conduct applies both within this project space and public spaces when an individual is representing the project or its community.
+For architectural PRs:
+
+- Keep behavior parity unless a functional change is explicitly intended and documented.
+- Highlight risk areas in the PR description.
+- Prefer smaller PRs for easier review and reduced merge conflicts.
+- Link related refactor work to the relevant open issue.
+
+## Code of Conduct
+
+By contributing, you agree to follow the project Code of Conduct: [CODE_OF_CONDUCT.md](https://github.com/VATSIM-UK/core/blob/main/.github/CODE_OF_CONDUCT.md).

.github/ISSUE_TEMPLATE.md

@@ -1,7 +1,35 @@
-# Summary of issue/change
+## Summary of Issue/Change
 
 < Enter text here >
 
-# Affected areas of the Core Project (if known)
+## Type
 
-< Enter text here >
+- [ ] Bug
+- [ ] Feature request
+- [ ] Refactor / technical debt
+- [ ] Documentation
+- [ ] Other
+
+## Problem Statement
+
+< What problem are you trying to solve? Include user impact where possible. >
+
+## Current vs Expected Behavior
+
+Current behavior:
+< Enter text here >
+
+Expected behavior:
+< Enter text here >
+
+## Affected Areas of Core (if known)
+
+< Enter text here >
+
+## Verification Plan
+
+< How should this be tested? Include automated and manual checks where possible. >
+
+## Additional Context
+
+< Links, screenshots, logs, or related issues/PRs. >

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,9 +1,31 @@
 Fixes #[issue_no]
 
-# Summary of changes
+## Summary of Changes
 
 < Please provide a sensible summary of changes for this merge request, ensuring all changes are explained. >
 
-# Screenshots (if necessary)
+## Type of Change
 
-< Please provide screenshots if this will facilitate a faster review of these changes>
+- [ ] Bug fix
+- [ ] Feature
+- [ ] Refactor (no intended functional change)
+- [ ] Documentation
+- [ ] Chore / maintenance
+
+## Verification
+
+- [ ] Unit tests added/updated where business logic changed
+- [ ] Feature/integration tests added/updated where contracts changed
+- [ ] Test suite run locally
+
+### Manual Validation
+
+< Describe manual checks performed and expected outcomes. >
+
+## Risk Assessment
+
+< Describe key regression risks and how they were mitigated. >
+
+## Screenshots (if necessary)
+
+< Please provide screenshots if this will facilitate a faster review of these changes. >

docs/architecture.md

@@ -0,0 +1,50 @@
+# Core Architecture
+
+A practical guide to architectural patterns for new work and refactors.
+
+## Principles
+
+- Separate transport concerns (HTTP, queue delivery) from domain/business logic.
+- Favor explicit constructor injection.
+- Prefer small, composable units that can be covered by focused tests.
+
+## Layer Boundaries
+
+### Controllers
+
+Handle HTTP concerns only: request/response, status codes, auth checks. Delegate all business logic to services. Controllers must not contain domain workflows, eligibility logic, or direct external integration behavior.
+
+### Services
+
+The home for domain/business logic. Each service should have one clear responsibility, typed inputs/outputs where practical, and no reliance on controller state. Return structured payloads (DTO-style arrays or DTO classes) that controllers pass through with minimal transformation.
+
+### Repositories and Integrations
+
+Isolate persistence and external API interaction from orchestration logic so services remain focused on decision-making.
+
+## Queue and Job Standards
+
+- Route work to dedicated queues per integration area.
+- Set explicit `$tries` and `$backoff`.
+- Use `WithoutOverlapping` for account/check-scoped work and `RateLimitedWithRedis` for downstream protection.
+- Log start, completion, and failure via `failed(Throwable $exception)`.
+- When adding a new queue, update Horizon configuration so it is actively consumed.
+
+## Webhook Processing Standards
+
+- Process action batches in deterministic order (e.g. sorted by timestamp).
+- Use explicit action-to-handler mapping rather than large `switch` blocks.
+- Log unknown actions clearly and return an explicit client error response.
+- Share repeated delta-parsing logic through a common helper or trait.
+
+## Service Provider Binding Standards
+
+- Use `$bindings` / `$singletons` for straightforward class mappings.
+- Use `register()` closures only when construction requires runtime configuration.
+- Avoid empty provider overrides.
+
+## Testing Expectations
+
+- Unit tests for newly extracted services and domain logic.
+- Job configuration tests where queue name, retries, or middleware are significant.
+- Feature/integration tests focused on contract parity (response shape, status codes, auth behavior).

readme.md

@@ -6,5 +6,6 @@ Core application for VATSIM UK
 ## Getting Started
 
  - [Setup guide](https://github.com/VATSIM-UK/core/blob/main/.github/setup.md)
+ - [Architecture guide](https://github.com/VATSIM-UK/core/blob/main/docs/architecture.md)
  - [Contributing guide](https://github.com/VATSIM-UK/core/blob/main/.github/CONTRIBUTING.md)
  - [Support page](https://github.com/VATSIM-UK/core/blob/main/.github/SUPPORT.md)