batch upload impl

api/queryAPI/README.md

@@ -0,0 +1,119 @@
+# 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
+```go
+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:
+
+```go
+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.