refactor(services): extract and organize APQ functionality into dedicated module structure

[BrynCooke]

Extract and organize APQ functionality into dedicated module structure

Task

Extract and organize APQ (Automatic Persisted Queries) functionality from the monolithic subgraph service into a well-structured, dedicated module hierarchy as part of the broader subgraph service refactoring effort.

Why

The subgraph service contained embedded APQ logic that made the service harder to test, maintain, and extend. APQ functionality was scattered across different locations, making it difficult to understand the complete APQ implementation and hindering future enhancements.

Benefits:

• Clear organization of APQ-related functionality in dedicated modules
• Better testability of APQ logic in isolation
• Foundation for future APQ enhancements and features
• Reduced complexity in the main subgraph service

How

This refactoring was completed in two phases:

Phase 1: Extraction

• Moved APQ error detection and handling logic from subgraph service into dedicated subgraph_apq module
• Created APQError enum and get_apq_error function for consistent error handling
• Added comprehensive test coverage for extracted APQ logic

Phase 2: Organization

• Consolidated all APQ modules under services/layers/apq/ directory structure:
  • services/layers/apq/mod.rs - General APQ layer functionality
  • services/layers/apq/subgraph.rs - Subgraph-specific APQ integration logic
• Updated import paths throughout the codebase to use new module structure

Technical Details

• Zero behavioral changes: All existing APQ functionality preserved
• Module organization: Follows established project pattern of grouping related functionality under layer directories
• Error handling: Centralized APQ error detection with consistent enum-based handling
• Import structure: Clean separation between general APQ layer and subgraph-specific integration
• Test coverage: Comprehensive tests for APQ error detection and handling logic

Review Strategy

Focus on these specific areas not covered by CI:

1. Module organization: Verify the new services/layers/apq/ structure follows project conventions and patterns used elsewhere in the codebase

2. Import consistency: Check that all import path updates are correct and follow Rust module visibility best practices

3. Code separation: Ensure clean logical separation between general APQ layer functionality (mod.rs) and subgraph-specific logic (subgraph.rs)

4. Error handling: Review that APQ error detection logic handles all edge cases correctly and maintains backward compatibility

5. Future extensibility: Assess whether the new structure will support adding new APQ features without further major refactoring

---

Checklist

Complete the checklist (and note appropriate exceptions) before the PR is marked ready-for-review.

• [ ] Changes are compatible[^1]
• [ ] Documentation[^2] completed
• [ ] Performance impact assessed and acceptable
• [ ] Metrics and logs are added[^3] and documented
• Tests added and passing[^4]
  • [ ] Unit Tests
  • [ ] Integration Tests
  • [ ] Manual Tests

Exceptions

Note any exceptions here

Notes

[^1]: It may be appropriate to bring upcoming changes to the attention of other (impacted) groups. Please endeavour to do this before seeking PR approval. The mechanism for doing this will vary considerably, so use your judgement as to how and when to do this. [^2]: Configuration is an important part of many changes. Where applicable please try to document configuration examples. [^3]: A lot of (if not most) features benefit from built-in observability and debug-level logs. Please read this guidance on metrics best-practices. [^4]: Tick whichever testing boxes are applicable. If you are adding Manual Tests, please document the manual testing (extensively) in the Exceptions.

[github-actions[bot]]

@BrynCooke, please consider creating a changeset entry in /.changesets/. These instructions describe the process and tooling.

[apollo-librarian[bot]]

✅ Docs preview has no changes

The preview was not built because there were no changes.

Build ID: beac5dc3add83864650e83a0