Merge #100: Add DDD Layer Placement Guide to Contributing Documentation

585027d docs: [#79] replace specific code examples with generic patterns (copilot-swe-agent[bot])
e5d5f99 docs: [#79] clarify infrastructure layer directory organization (copilot-swe-agent[bot])
444fbe9 docs: [#79] add comprehensive DDD layer placement guide (copilot-swe-agent[bot])
018fad5 Initial plan (copilot-swe-agent[bot])

Pull request description:

  The project lacked clear guidelines on DDD layer placement, leading to architectural violations like the config module being placed in domain when it belonged in application (#75). Contributors needed explicit rules to distinguish between domain entities, DTOs, and infrastructure concerns.

  ## Changes

  ### Documentation Added

  - **`docs/contributing/ddd-layer-placement.md`** - Comprehensive guide with:
    - Layer specifications for Domain, Application, Infrastructure (`adapters/` + `infrastructure/`), and Presentation
    - Decision flowchart mapping code characteristics to correct layer
    - Generic, illustrative patterns demonstrating common architectural concepts (value objects, command handlers, adapters for external tools, CLI definitions)
    - Common mistakes section showing wrong placements with corrections

  - **Critical nuance on serde usage** - Distinguishes acceptable from problematic patterns:

  ```rust
  // ✅ Domain entity with serde for persistence (acceptable pragmatic trade-off)
  #[derive(Serialize, Deserialize)]
  pub struct EnvironmentName(String);

  // ❌ DTO in domain layer (wrong - belongs in application)
  #[derive(Serialize, Deserialize)]
  pub struct ConfigDto {
      pub name: String,  // Raw primitive, no domain validation
  }
  ```

  ### Documentation Updated

  - **`docs/contributing/README.md`** - Expanded quick reference table with all contributing guides, DDD placement listed first
  - **`.github/copilot-instructions.md`** - Added layer placement as Essential Rule #1

  ### Examples Approach

  The guide uses generic, illustrative code patterns rather than specific codebase examples. This makes the documentation more maintainable (no updates needed when actual code changes) while still effectively demonstrating the architectural principles and common patterns like command handlers, repository implementations, and external tool adapters.

  ## Resolves

  Closes #79
  Related to #75 (the violation that exposed this gap)

  <!-- START COPILOT CODING AGENT SUFFIX -->

  <details>

  <summary>Original prompt</summary>

  >
  > ----
  >
  > *This section details on the original issue you should resolve*
  >
  > <issue_title>Add DDD Layer Placement Guide to Contributing Documentation</issue_title>
  > <issue_description># Add DDD Layer Placement Guide to Contributing Documentation
  >
  > ## 📋 Issue Information
  >
  > - **Type**: Documentation Enhancement
  > - **Priority**: High
  > - **Related Issue**: #75 - Move config module to correct DDD layer
  > - **Parent Epic**: None (standalone improvement)
  >
  > ## 🎯 Problem Statement
  >
  > The project lacks clear guidelines on which code belongs in which DDD layer (Domain, Application, Infrastructure, Presentation). This has led to violations like the config module (#75) being placed in the domain layer when it clearly belongs in the application layer.
  >
  > Without explicit documentation, contributors (including AI assistants) may:
  >
  > - Place DTOs in the domain layer
  > - Mix infrastructure concerns (file I/O, HTTP) with domain logic
  > - Create unclear boundaries between layers
  > - Make code harder to maintain and test
  >
  > ## 💡 Proposed Solution
  >
  > Create a comprehensive guide `docs/contributing/ddd-layer-placement.md` that clearly documents each layer's purpose, rules, red flags, examples, and includes a decision flowchart.
  >
  > ## 📝 Implementation Plan
  >
  > See detailed specification: [docs/issues/add-ddd-layer-placement-guide.md](https://github.com/torrust/torrust-tracker-deployer/blob/main/docs/issues/add-ddd-layer-placement-guide.md)
  >
  > ## ✅ Acceptance Criteria
  >
  > > **Note for Contributors**: These criteria define what the PR reviewer will check. Use this as your pre-review checklist before submitting the PR to minimize back-and-forth iterations.
  >
  > - [ ] Document created at `docs/contributing/ddd-layer-placement.md`
  > - [ ] All four layers documented with clear rules and examples
  > - [ ] Nuanced guidance on serde usage included (entities vs DTOs)
  > - [ ] Decision flowchart included for quick reference
  > - [ ] Real code examples from the codebase
  > - [ ] Linked from `docs/contributing/README.md`
  > - [ ] Referenced in `.github/copilot-instructions.md`
  > - [ ] All linters pass (markdownlint, cspell)
  > - [ ] Document follows project markdown conventions
  >
  > ## 🏷️ Labels
  >
  > documentation, enhancement, DDD, contributing-guide</issue_description>
  >
  > ## Comments on the Issue (you are @copilot in this section)
  >
  > <comments>
  > </comments>
  >

  </details>

  - Fixes #79

  <!-- START COPILOT CODING AGENT TIPS -->
  ---

  💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.

ACKs for top commit:
  josecelano:
    ACK 585027d

Tree-SHA512: ebb14adfc94ea7a36c98c32943c0a7d49f507ef6c8980aff987258032e1e116e64064a7947a4bb77ab0c1c236045adf17a9411492743b6c65ed92d5943a9bed2

Author: josecelano

.github/copilot-instructions.md

@@ -64,14 +64,16 @@ These principles should guide all development decisions, code reviews, and featu
 
 ## 🔧 Essential Rules
 
-1. **Before creating branches**: Read [`docs/contributing/branching.md`](../docs/contributing/branching.md) for naming conventions (`{issue-number}-{short-description}`)
+1. **Before placing code in DDD layers**: Read [`docs/contributing/ddd-layer-placement.md`](../docs/contributing/ddd-layer-placement.md) for comprehensive guidance on which code belongs in which layer (Domain, Application, Infrastructure, Presentation). This guide includes rules, red flags, examples, and a decision flowchart to help you make the right architectural decisions.
 
-2. **Before committing**: Read [`docs/contributing/commit-process.md`](../docs/contributing/commit-process.md) for conventional commits
+2. **Before creating branches**: Read [`docs/contributing/branching.md`](../docs/contributing/branching.md) for naming conventions (`{issue-number}-{short-description}`)
+
+3. **Before committing**: Read [`docs/contributing/commit-process.md`](../docs/contributing/commit-process.md) for conventional commits
 
    - **With issue branch**: `{type}: [#{issue}] {description}` (when branch name starts with `{issue-number}-`)
    - **Without issue branch**: `{type}: {description}` (when working on main or branch without issue number prefix)
 
-3. **Before committing**: Always run the pre-commit verification script - all checks must pass before staging files or creating commits, regardless of the tool or method used:
+4. **Before committing**: Always run the pre-commit verification script - all checks must pass before staging files or creating commits, regardless of the tool or method used:
 
    ```bash
    ./scripts/pre-commit.sh
@@ -85,17 +87,17 @@ These principles should guide all development decisions, code reviews, and featu
    - Git clients: GitHub Desktop, GitKraken, etc.
    - CI/CD: Any automated commits or merges
 
-4. **Before working with Tera templates**: Read [`docs/contributing/templates.md`](../docs/contributing/templates.md) for correct variable syntax - use `{{ variable }}` not `{ { variable } }`. Tera template files have the `.tera` extension.
+5. **Before working with Tera templates**: Read [`docs/contributing/templates.md`](../docs/contributing/templates.md) for correct variable syntax - use `{{ variable }}` not `{ { variable } }`. Tera template files have the `.tera` extension.
 
-5. **When adding new Ansible playbooks**: Read [`docs/contributing/templates.md`](../docs/contributing/templates.md) for the complete guide. **CRITICAL**: Static playbooks (without `.tera` extension) must be registered in `src/infrastructure/external_tools/ansible/template/renderer/mod.rs` in the `copy_static_templates` method, otherwise they won't be copied to the build directory and Ansible will fail with "playbook not found" error.
+6. **When adding new Ansible playbooks**: Read [`docs/contributing/templates.md`](../docs/contributing/templates.md) for the complete guide. **CRITICAL**: Static playbooks (without `.tera` extension) must be registered in `src/infrastructure/external_tools/ansible/template/renderer/mod.rs` in the `copy_static_templates` method, otherwise they won't be copied to the build directory and Ansible will fail with "playbook not found" error.
 
-6. **When handling errors in code**: Read [`docs/contributing/error-handling.md`](../docs/contributing/error-handling.md) for error handling principles. Prefer explicit enum errors over anyhow for better pattern matching and user experience. Make errors clear, include sufficient context for traceability, and ensure they are actionable with specific fix instructions.
+7. **When handling errors in code**: Read [`docs/contributing/error-handling.md`](../docs/contributing/error-handling.md) for error handling principles. Prefer explicit enum errors over anyhow for better pattern matching and user experience. Make errors clear, include sufficient context for traceability, and ensure they are actionable with specific fix instructions.
 
-7. **Understanding expected errors**: Read [`docs/contributing/known-issues.md`](../docs/contributing/known-issues.md) for known issues and expected behaviors. Some errors that appear red in E2E test output (like SSH host key warnings) are normal and expected - not actual failures.
+8. **Understanding expected errors**: Read [`docs/contributing/known-issues.md`](../docs/contributing/known-issues.md) for known issues and expected behaviors. Some errors that appear red in E2E test output (like SSH host key warnings) are normal and expected - not actual failures.
 
-8. **Before making engineering decisions**: Document significant architectural or design decisions as Architectural Decision Records (ADRs) in `docs/decisions/`. Read [`docs/decisions/README.md`](../docs/decisions/README.md) for the ADR template and guidelines. This ensures decisions are properly documented with context, rationale, and consequences for future reference.
+9. **Before making engineering decisions**: Document significant architectural or design decisions as Architectural Decision Records (ADRs) in `docs/decisions/`. Read [`docs/decisions/README.md`](../docs/decisions/README.md) for the ADR template and guidelines. This ensures decisions are properly documented with context, rationale, and consequences for future reference.
 
-9. **When organizing code within modules**: Follow the module organization conventions in [`docs/contributing/module-organization.md`](../docs/contributing/module-organization.md). Use top-down organization with public items first, high-level abstractions before low-level details, and important responsibilities before secondary concerns like error types.
+10. **When organizing code within modules**: Follow the module organization conventions in [`docs/contributing/module-organization.md`](../docs/contributing/module-organization.md). Use top-down organization with public items first, high-level abstractions before low-level details, and important responsibilities before secondary concerns like error types.
 
 ## 🧪 Build & Test
 

docs/contributing/README.md

@@ -4,12 +4,20 @@ This guide will help you understand our development practices and contribution w
 
 ## 📋 Quick Reference
 
-| Topic                                | File                                     |
-| ------------------------------------ | ---------------------------------------- |
-| Creating roadmap issues              | [roadmap-issues.md](./roadmap-issues.md) |
-| Branching conventions                | [branching.md](./branching.md)           |
-| Commit process and pre-commit checks | [commit-process.md](./commit-process.md) |
-| Code quality and linting             | [linting.md](./linting.md)               |
+| Topic                                | File                                                 |
+| ------------------------------------ | ---------------------------------------------------- |
+| DDD layer placement (architecture)   | [ddd-layer-placement.md](./ddd-layer-placement.md)   |
+| Creating roadmap issues              | [roadmap-issues.md](./roadmap-issues.md)             |
+| Branching conventions                | [branching.md](./branching.md)                       |
+| Commit process and pre-commit checks | [commit-process.md](./commit-process.md)             |
+| Code quality and linting             | [linting.md](./linting.md)                           |
+| Module organization within files     | [module-organization.md](./module-organization.md)   |
+| Error handling principles            | [error-handling.md](./error-handling.md)             |
+| Working with Tera templates          | [templates.md](./templates.md)                       |
+| Debugging techniques                 | [debugging.md](./debugging.md)                       |
+| Spell checking and dictionaries      | [spelling.md](./spelling.md)                         |
+| Known issues and expected behaviors  | [known-issues.md](./known-issues.md)                 |
+| Logging best practices               | [logging-guide.md](./logging-guide.md)               |
 
 ## 🚀 Getting Started