# SyRF Monorepo Dependency Map
# Single Source of Truth for Service/Library Dependencies
# Used for: Docker builds, CI/CD workflows, documentation
# Last Updated: 2026-04-24
# Format: YAML for machine readability and human clarity

metadata:
  version: "1.0.0"
  description: "Authoritative dependency map for SyRF monorepo"
  usage:
    - "Docker build context determination"
    - "CI/CD workflow path triggers"
    - "Impact analysis for changes"
    - "Documentation reference"

# Core libraries with no dependencies on other internal libs
libraries:
  SharedKernel:
    path: "src/libs/kernel"
    project: "SyRF.SharedKernel/SyRF.SharedKernel.csproj"
    type: "library"
    description: "Core domain models and interfaces"
    depends_on: []  # No internal dependencies
    external_packages:
      - "MongoDB.Bson"
      - "MongoDB.Driver"
      - "MassTransit"
    critical: true
    impact: "Changes affect ALL services"

  Mongo.Common:
    path: "src/libs/mongo"
    project: "SyRF.Mongo.Common/SyRF.Mongo.Common.csproj"
    type: "library"
    description: "MongoDB utilities and base repositories"
    depends_on:
      - "SharedKernel"
    external_packages:
      - "MongoDB.Driver"
      - "Polly"
      - "Serilog"
    critical: true
    impact: "Changes affect all services except Quartz"

  WebHostConfig.Common:
    path: "src/libs/webhostconfig"
    project: "SyRF.WebHostConfig.Common/SyRF.WebHostConfig.Common.csproj"
    type: "library"
    description: "Web host configuration and middleware"
    depends_on:
      - "SharedKernel"  # Only internal dep post PR #2591 (previously pulled Mongo.Common + AppServices)
    external_packages:
      - "Serilog.AspNetCore"
      - "Swashbuckle.AspNetCore"
      - "MassTransit.RabbitMQ"
      - "OpenTelemetry.Instrumentation.AspNetCore"
    critical: false
    impact: "Changes affect API, PM, and Quartz services"

  AppServices:
    path: "src/libs/appservices"
    project: "SyRF.AppServices/SyRF.AppServices.csproj"
    type: "library"
    description: "Application service layer (including S3 file services — S3Settings, IS3PostSigner, S3PostSigner moved here from SharedKernel in PR #2591)"
    depends_on:
      - "SharedKernel"
      - "Mongo.Common"
    external_packages:
      - "FluentValidation"
      - "AutoMapper"
    critical: false
    impact: "Changes affect API and PM services only"

  API.Messages:
    path: "src/libs/api"
    project: "SyRF.API.Messages/SyRF.API.Messages.csproj"
    type: "library"
    description: "API message contracts"
    depends_on:
      - "SharedKernel"
    external_packages:
      - "MassTransit"
    critical: false
    impact: "Changes affect API service only"

  ProjectManagement.Core:
    path: "src/libs/project-management/SyRF.ProjectManagement.Core"
    project: "SyRF.ProjectManagement.Core.csproj"
    type: "library"
    description: "PM domain logic"
    depends_on:
      - "AppServices"  # Added in PR #2591 (direct ref; previously transitive via WebHostConfig)
      - "SharedKernel"
    external_packages: []
    critical: false
    impact: "Changes affect API and PM services"

  ProjectManagement.Application:
    path: "src/libs/project-management/SyRF.ProjectManagement.Application"
    project: "SyRF.ProjectManagement.Application.csproj"
    type: "library"
    description: "PM application services (orchestration without domain logic)"
    depends_on:
      - "ProjectManagement.Core"
    external_packages: []
    critical: false
    impact: "Changes affect API and PM services"

  ProjectManagement.Messages:
    path: "src/libs/project-management/SyRF.ProjectManagement.Messages"
    project: "SyRF.ProjectManagement.Messages.csproj"
    type: "library"
    description: "PM message contracts"
    depends_on:
      - "SharedKernel"
    external_packages:
      - "MassTransit"
    critical: false
    impact: "Changes affect PM and Quartz services"

  ProjectManagement.Mongo.Data:
    path: "src/libs/project-management/SyRF.ProjectManagement.Mongo.Data"
    project: "SyRF.ProjectManagement.Mongo.Data.csproj"
    type: "library"
    description: "PM MongoDB data access layer"
    depends_on:
      - "SharedKernel"
      - "Mongo.Common"
      - "ProjectManagement.Core"
    external_packages:
      - "MongoDB.Driver"
    critical: false
    impact: "Changes affect API and PM services"

  S3FileSavedNotifier.Messages:
    path: "src/libs/s3-notifier"
    project: "SyRF.S3FileSavedNotifier.Messages/SyRF.S3FileSavedNotifier.Messages.csproj"
    type: "library"
    description: "S3 event message contracts"
    depends_on: []  # No internal dependencies
    external_packages:
      - "MassTransit"
    critical: false
    impact: "Changes affect S3-notifier service only"

# Services and their complete dependency trees
services:
  api:
    path: "src/services/api"
    project: "SyRF.API.Endpoint/SyRF.API.Endpoint.csproj"
    type: "service"
    description: "Main REST API service"
    dockerfile: "SyRF.API.Endpoint/Dockerfile"
    port: 8080

    # Direct dependencies (from ProjectReference)
    direct_dependencies:
      - "SharedKernel"
      - "Mongo.Common"  # Added direct ref in PR #2591 (was transitive via WebHostConfig)
      - "AppServices"  # Added direct ref in PR #2591 (was transitive via WebHostConfig)
      - "WebHostConfig.Common"
      - "API.Messages"
      - "ProjectManagement.Application"
      - "ProjectManagement.Core"
      - "ProjectManagement.Messages"
      - "ProjectManagement.Mongo.Data"

    # Complete transitive closure (for Docker builds)
    all_dependencies:
      - "SharedKernel"
      - "Mongo.Common"
      - "AppServices"
      - "WebHostConfig.Common"
      - "API.Messages"
      - "ProjectManagement.Application"
      - "ProjectManagement.Core"
      - "ProjectManagement.Messages"
      - "ProjectManagement.Mongo.Data"

    # Files needed for Docker build
    docker_context:
      required_paths:
        - "src/services/api/"
        - "src/libs/kernel/"
        - "src/libs/mongo/"
        - "src/libs/appservices/"
        - "src/libs/webhostconfig/"
        - "src/libs/api/"
        - "src/libs/project-management/"
        - "Directory.Build.props"
        - "nuget.config"

    # CI/CD workflow triggers
    workflow_triggers:
      - "src/services/api/**"
      - "src/libs/kernel/**"
      - "src/libs/mongo/**"
      - "src/libs/appservices/**"
      - "src/libs/webhostconfig/**"
      - "src/libs/api/**"
      - "src/libs/project-management/**"

  project-management:
    path: "src/services/project-management"
    project: "SyRF.ProjectManagement.Endpoint/SyRF.ProjectManagement.Endpoint.csproj"
    type: "service"
    description: "DDD-based project management service"
    dockerfile: "SyRF.ProjectManagement.Endpoint/Dockerfile"
    port: 8081

    direct_dependencies:
      - "SharedKernel"
      - "API.Messages"
      - "S3FileSavedNotifier.Messages"
      - "AppServices"
      - "WebHostConfig.Common"
      - "ProjectManagement.Core"
      - "ProjectManagement.Messages"
      - "ProjectManagement.Mongo.Data"

    all_dependencies:
      - "SharedKernel"
      - "Mongo.Common"  # Via Mongo.Data
      - "API.Messages"
      - "S3FileSavedNotifier.Messages"
      - "AppServices"
      - "WebHostConfig.Common"
      - "ProjectManagement.Core"
      - "ProjectManagement.Messages"
      - "ProjectManagement.Mongo.Data"

    docker_context:
      required_paths:
        - "src/services/project-management/"
        - "src/libs/kernel/"
        - "src/libs/mongo/"
        - "src/libs/appservices/"
        - "src/libs/webhostconfig/"
        - "src/libs/project-management/"
        - "Directory.Build.props"
        - "nuget.config"

    workflow_triggers:
      - "src/services/project-management/**"
      - "src/libs/kernel/**"
      - "src/libs/mongo/**"
      - "src/libs/appservices/**"
      - "src/libs/webhostconfig/**"
      - "src/libs/project-management/**"

  quartz:
    path: "src/services/quartz"
    project: "SyRF.Quartz/SyRF.Quartz.csproj"
    type: "service"
    description: "Background job scheduler (MassTransit Job-Service host; decoupled from Mongo/AppServices in PR #2591)"
    dockerfile: "SyRF.Quartz/Dockerfile"
    port: 8082

    # Post PR #2591: Quartz's only ProjectReference is WebHostConfig.Common.
    # SharedKernel reaches Quartz transitively via WebHostConfig.Common.
    # Mongo.Common / AppServices / PM.Messages are NO LONGER compiled into Quartz.
    direct_dependencies:
      - "WebHostConfig.Common"

    all_dependencies:
      - "SharedKernel"  # Via WebHostConfig.Common
      - "WebHostConfig.Common"

    # NOTE: docker_context.required_paths and workflow_triggers below are
    # intentionally broader than all_dependencies — the CI trigger script
    # (.github/scripts/detect-service-changes.sh) still includes Mongo /
    # AppServices / PM.Messages paths as a conservative rebuild trigger.
    # Safe to narrow in a follow-up; left as-is here so the yaml matches
    # actual CI behaviour.
    docker_context:
      required_paths:
        - "src/services/quartz/"
        - "src/libs/kernel/"
        - "src/libs/webhostconfig/"
        - "Directory.Build.props"
        - "nuget.config"

    workflow_triggers:
      - "src/services/quartz/**"
      - "src/libs/kernel/**"
      - "src/libs/mongo/**"  # Conservative: kept for CI parity (quartz no longer compiles against Mongo.Common)
      - "src/libs/appservices/**"  # Conservative: kept for CI parity (quartz no longer compiles against AppServices)
      - "src/libs/webhostconfig/**"
      - "src/libs/project-management/SyRF.ProjectManagement.Messages/**"  # Conservative: kept for CI parity (quartz doesn't reference PM.Messages)

  web:
    path: "src/services/web"
    project: null  # Angular/Node.js project, not .NET
    type: "frontend"
    description: "Angular frontend application"
    dockerfile: "Dockerfile"
    port: 80
    framework: "Angular"

    direct_dependencies: []  # No .NET dependencies
    all_dependencies: []

    docker_context:
      required_paths:
        - "src/services/web/"
        # Node/Angular builds are self-contained

    workflow_triggers:
      - "src/services/web/**"
      # No library dependencies to trigger on

  s3-notifier:
    path: "src/services/s3-notifier"
    project: "SyRF.S3FileSavedNotifier.Endpoint/SyRF.S3FileSavedNotifier.Endpoint.csproj"
    type: "lambda"
    description: "AWS Lambda for S3 events"
    dockerfile: "SyRF.S3FileSavedNotifier.Endpoint/Dockerfile"
    port: null  # Lambda function
    deployment: "AWS Lambda"

    direct_dependencies:
      - "S3FileSavedNotifier.Messages"

    all_dependencies:
      - "S3FileSavedNotifier.Messages"

    docker_context:
      required_paths:
        - "src/services/s3-notifier/"
        - "src/libs/s3-notifier/"
        - "Directory.Build.props"
        - "nuget.config"

    workflow_triggers:
      - "src/services/s3-notifier/**"
      - "src/libs/s3-notifier/**"

  identity:
    path: "src/services/identity"
    project: "SyRF.Identity.Endpoint/SyRF.Identity.Endpoint.csproj"
    type: "service"
    description: "OpenIddict Identity/Authorization Server"
    dockerfile: "SyRF.Identity.Endpoint/Dockerfile"
    port: 8083

    direct_dependencies:
      - "SharedKernel"

    all_dependencies:
      - "SharedKernel"

    docker_context:
      required_paths:
        - "src/services/identity/"
        - "src/libs/kernel/"
        - "Directory.Build.props"
        - "nuget.config"

    workflow_triggers:
      - "src/services/identity/**"
      - "src/libs/kernel/**"

  user-guide:
    path: "user-guide"
    project: null  # Jekyll static site, not .NET
    type: "documentation"
    description: "Public-facing user documentation (Jekyll)"
    dockerfile: "Dockerfile"
    port: 80
    framework: "Jekyll"

    direct_dependencies: []  # No .NET dependencies
    all_dependencies: []

    docker_context:
      required_paths:
        - "user-guide/"
        # Jekyll builds are self-contained

    workflow_triggers:
      - "user-guide/**"
      # No library dependencies to trigger on

  docs:
    path: "docs"
    project: null  # MkDocs static site, not .NET
    type: "documentation"
    description: "Internal team documentation (MkDocs)"
    dockerfile: "Dockerfile"  # MANUALLY MAINTAINED - Do not regenerate
    dockerfile_ci: "Dockerfile.ci"  # For CI/CD with GitHub Actions checkout
    port: 80
    framework: "MkDocs"
    skip_dockerfile_generation: true  # Multi-repo build needs custom Dockerfiles

    direct_dependencies: []  # No .NET dependencies
    all_dependencies: []

    # IMPORTANT: This service aggregates docs from 3 repositories:
    # - syrf (this repo)
    # - cluster-gitops (public)
    # - camarades-infrastructure (private)
    #
    # Build strategy:
    # - CI/CD: Uses Dockerfile.ci with GitHub Actions checkout (GITHUB_TOKEN for private repos)
    # - Local: Uses Dockerfile with git clone (works for public repos, may fail for private)
    external_repositories:
      - repo: "camaradesuk/cluster-gitops"
        access: "public"
        docs_path: "docs/"
      - repo: "camaradesuk/camarades-infrastructure"
        access: "private"
        docs_path: "docs/"

    docker_context:
      required_paths:
        - "syrf/docs/"
        - "syrf/mkdocs.yml"
        - "syrf/requirements.txt"
        - "cluster-gitops/docs/"  # From GitHub Actions sparse checkout
        - "cluster-gitops/mkdocs.yml"
        - "camarades-infrastructure/docs/"  # From GitHub Actions sparse checkout (private)
        - "camarades-infrastructure/mkdocs.yml"
      optimization: "Uses sparse-checkout to fetch only docs/ and mkdocs.yml from external repos"

    workflow_triggers:
      - "docs/**"
      - "mkdocs.yml"
      - "requirements.txt"
      # No library dependencies to trigger on

# Dependency analysis summary
analysis:
  total_services: 7
  total_libraries: 9
  circular_dependencies: 0

  library_usage:
    SharedKernel:
      used_by: ["api", "project-management", "quartz"]
      critical: true
      change_impact: "high"

    Mongo.Common:
      used_by: ["api", "project-management"]  # Quartz dropped its transitive dep in PR #2591
      critical: true
      change_impact: "medium"

    WebHostConfig.Common:
      used_by: ["api", "project-management", "quartz"]
      critical: false
      change_impact: "medium"

    AppServices:
      used_by: ["api", "project-management"]  # Quartz dropped its transitive dep in PR #2591
      critical: false
      change_impact: "medium"

    API.Messages:
      used_by: ["api"]
      critical: false
      change_impact: "low"

    ProjectManagement.Core:
      used_by: ["project-management"]
      critical: false
      change_impact: "low"

    ProjectManagement.Core.Dtos:
      used_by: ["project-management"]
      critical: false
      change_impact: "low"

    ProjectManagement.Messages:
      used_by: ["project-management", "s3-notifier"]  # Quartz doesn't actually reference PM.Messages (csproj confirms)
      critical: false
      change_impact: "medium"

    S3FileSavedNotifier.Messages:
      used_by: ["s3-notifier"]
      critical: false
      change_impact: "low"

# Docker optimization recommendations
docker_optimization:
  use_dockerignore: true
  suggested_dockerignore: |
    # Exclude everything by default
    **

    # Include only what's needed (per service)
    !src/services/{service}/
    !src/libs/
    !Directory.Build.props
    !nuget.config

    # Re-exclude unnecessary files
    **/*.md
    **/.git*
    **/bin/
    **/obj/
    **/.vs/

  build_strategy:
    recommendation: "Use BuildKit for better caching"
    multi_stage: true
    cache_mounts: true
    estimated_improvement: "30-40% faster builds"

# CI/CD workflow optimization
workflow_optimization:
  path_filters:
    description: "Use precise path filters to avoid unnecessary builds"
    current_issue: "src/libs/** triggers all .NET services"

    recommended_filters:
      api:
        precise:
          - "src/services/api/**"
          - "src/libs/kernel/**"
          - "src/libs/mongo/**"
          - "src/libs/appservices/**"
          - "src/libs/webhostconfig/**"
          - "src/libs/api/**"

      project_management:
        precise:
          - "src/services/project-management/**"
          - "src/libs/kernel/**"
          - "src/libs/mongo/**"
          - "src/libs/appservices/**"
          - "src/libs/webhostconfig/**"
          - "src/libs/project-management/**"

      quartz:
        precise:
          - "src/services/quartz/**"
          - "src/libs/kernel/**"
          - "src/libs/mongo/**"
          - "src/libs/appservices/**"
          - "src/libs/webhostconfig/**"
          - "src/libs/project-management/SyRF.ProjectManagement.Messages/**"

      web:
        precise:
          - "src/services/web/**"
          # No library dependencies

      s3_notifier:
        precise:
          - "src/services/s3-notifier/**"
          - "src/libs/s3-notifier/**"

      user_guide:
        precise:
          - "user-guide/**"
          # No library dependencies

      docs:
        precise:
          - "docs/**"
          - "mkdocs.yml"
          - "requirements.txt"
          # No library dependencies

  build_matrix:
    description: "Services that can build in parallel"
    parallel_groups:
      - ["api", "project-management", "quartz"]  # Can build simultaneously
      - ["web"]  # Independent
      - ["s3-notifier"]  # Independent
      - ["user-guide", "docs"]  # Documentation services (independent)

# Usage instructions
instructions:
  for_docker_builds: |
    1. Reference docker_context.required_paths for each service
    2. Use suggested .dockerignore to minimize context
    3. Build from repository root with appropriate context

  for_ci_cd: |
    1. Use workflow_triggers for path-based triggers
    2. Reference all_dependencies for complete dependency tree
    3. Use build_matrix.parallel_groups for optimization

  for_developers: |
    1. Check impact analysis before modifying libraries
    2. SharedKernel changes affect multiple services
    3. Web service is independent (Angular, not .NET)

  validation: |
    Run: yamllint planning/DEPENDENCY-MAP.yaml
    Script: planning/scripts/validate-dependencies.sh