query-orchestration/api/queryAPI

queryAPI Package

This directory contains the REST API implementation for the Query Orchestration platform. The code here serves as the HTTP interface layer between external clients and the internal business logic.

Architecture Overview

Controllers Struct (controllers.go)

The Controllers struct is the central architectural component that implements the Service Layer/Facade pattern for the entire REST API.

Purpose

• OpenAPI Contract Implementation: Implements the ServerInterface interface generated from serviceAPIs/queryAPI.yaml
• Service Aggregation: Consolidates 11 different business services into a single, cohesive API layer
• Dependency Injection Container: Provides clean separation between HTTP handlers and business logic

Structure

type Controllers struct {
    svc *Services           // Aggregated business services
    cfg ConfigProvider     // Combined auth & object storage configuration
}

Pattern Benefits

1. Single Responsibility: Each handler method focuses solely on HTTP↔Service translation
2. Testability: Services can be easily mocked for unit testing
3. Modularity: New services can be added without changing the controller pattern
4. Type Safety: Ensures compile-time checking against OpenAPI specification

Key Architectural Components

1. Generated Code (api.gen.go)

• DO NOT EDIT: This file is auto-generated from serviceAPIs/queryAPI.yaml
• Contains all request/response types and the ServerInterface interface
• Regenerated via task generate command
• Ensures API contract consistency

2. Handler Files

Each file implements specific domain endpoints:

• client.go - Client management operations
• collector.go - Query collector configuration
• documents.go - Document upload and management
• export.go - Export operations
• query.go - Query execution and management
• status.go - Health check and status endpoints
• authHandlers.go - Authentication flow handlers (login, logout, callbacks)

3. Service Dependencies

The Controllers struct aggregates these internal services:

• Export Service - Manages export processes
• Collector Service - Handles query collections
• Query Service - Query execution logic
• Client Service - Client entity management
• Document Service - Document processing
• DocumentUpload Service - S3 upload handling
• DocumentBatch Service - Batch document operations

4. Authentication Integration

• Uses AWS Cognito for JWT-based authentication
• Permit.io integration for RBAC (Role-Based Access Control)
• Authentication middleware validates tokens before reaching handlers
• ConfigProvider interface provides auth configuration access

Handler Pattern

All handlers follow a consistent pattern:

func (s *Controllers) HandlerName(ctx echo.Context, params...) error {
    // 1. Bind/validate request data
    req := RequestType{}
    if err := ctx.Bind(&req); err != nil {
        return echo.NewHTTPError(http.StatusBadRequest, err)
    }
    
    // 2. Call appropriate service method
    result, err := s.svc.ServiceName.Method(ctx.Request().Context(), ...)
    if err != nil {
        return echo.NewHTTPError(http.StatusBadRequest, "Error message")
    }
    
    // 3. Return formatted response
    return ctx.JSON(http.StatusOK, ResponseType{...})
}

Testing Structure

• *_test.go files provide unit tests for each handler group
• test_helpers.go contains shared test utilities and fixtures
• Tests use mocked services to validate handler logic in isolation
• Integration tests exist at the service layer level

Important Notes for Maintenance

1. OpenAPI-First Development: Always update serviceAPIs/queryAPI.yaml first, then regenerate code
2. Service Layer Separation: Business logic belongs in internal/ services, not in handlers
3. Error Handling: Use Echo's HTTPError for consistent error responses
4. Context Propagation: Always pass ctx.Request().Context() to service methods for proper cancellation
5. No Direct Database Access: All data operations must go through service layer
6. Consistent Status Codes: Follow REST conventions (201 for creation, 200 for success, 400 for client errors)

Development Workflow

1. Modify OpenAPI spec in serviceAPIs/queryAPI.yaml
2. Run task generate to update generated code
3. Implement/update handler methods in Controllers
4. Add/update tests for new functionality
5. Run task lint to ensure code quality
6. Run task test:functional to validate changes

Configuration

The ConfigProvider interface combines:

• Authentication configuration (Cognito settings, JWT validation)
• Object storage configuration (S3 bucket settings)
• Base service configuration (ports, logging, database)

This unified configuration is injected into Controllers at startup, providing all necessary runtime settings.