Merge pull request #15 from mauriciozanettisalomao/feat/lfxv2-199-org-search-endpoint

[LFX-V2-199] Query Service: org search endpoint implementation

Author: mauriciozanettisalomao

CLAUDE.md

@@ -41,7 +41,7 @@ make lint
 # Or: golangci-lint run ./...
 
 # Run specific test
-go test -v -run TestResourceSearch ./internal/usecase/
+go test -v -run TestResourceSearch ./internal/service/
 ```
 
 ### Docker Operations
@@ -64,7 +64,7 @@ This service follows clean architecture principles with clear separation of conc
    - `model/`: Core business entities (Resource, SearchCriteria, AccessCheck)
    - `port/`: Interfaces defining contracts (ResourceSearcher, AccessControlChecker)
 
-2. **Use Case Layer** (`internal/usecase/`)
+2. **Service Layer** (`internal/service/`)
    - Business logic orchestration
    - Coordinates between domain and infrastructure
 
@@ -93,7 +93,7 @@ This service follows clean architecture principles with clear separation of conc
 
 1. HTTP request → Goa generated server (`gen/http/query_svc/server/`)
 2. Service layer (`cmd/query_svc/query_svc.go`)
-3. Use case orchestration (`internal/usecase/resource_search.go`)
+3. Use case orchestration (`internal/service/resource_search.go`)
 4. Domain interfaces called with concrete implementations
 5. Response formatted and returned through Goa
 

README.md

@@ -25,7 +25,7 @@ The implementation follows the clean architecture principles where:
 │   ├── domain/                     # Domain logic layer
 │   │   ├── model/                  # Domain models and entities
 │   │   └── port/                   # Domain interfaces/ports
-│   ├── usecase/                    # Business logic/use cases layer
+│   ├── service/                    # Business logic/use cases layer
 │   ├── infrastructure/             # Infrastructure layer
 │   └── middleware/                 # HTTP middleware components
 └── pkg/                            # Shared packages for internal and external services
@@ -47,10 +47,10 @@ The implementation follows the clean architecture principles where:
 - **ResourceSearcher Interface**: Defines the contract for resource search operations
 - **AccessControlChecker Interface**: Defines the contract for access control operations
 
-### Use Case Layer (`internal/usecase/`)
+### Service Layer (`internal/service/`)
 
 - **Business Logic**: Application-specific business rules and operations
-- **Use Case Orchestration**: Coordinates between domain models and infrastructure
+- **Service Orchestration**: Coordinates between domain models and infrastructure
 
 ### Infrastructure Layer (`internal/infrastructure/`)
 
@@ -62,6 +62,10 @@ The OpenSearch implementation includes query templates, a searcher, and a client
 
 The NATS implementation consists of a client, access control logic, and request/response models for messaging and access control.
 
+#### Clearbit Implementation
+
+The Clearbit implementation provides organization search capabilities using the Clearbit Company API. It includes a client for API communication, searcher for organization queries, and configuration management for API credentials and settings.
+
 ## Dependency Injection
 
 Dependency injection is performed in `cmd/main.go`, where the concrete implementations for resource search and access control are selected based on configuration and then injected into the service constructor.
@@ -106,15 +110,21 @@ SEARCH_SOURCE=mock ACCESS_CONTROL_SOURCE=mock go run cmd/main.go
 SEARCH_SOURCE=mock ACCESS_CONTROL_SOURCE=mock go run cmd/main.go -p 3000
 ```
 
-#### With OpenSearch and NATS
+#### With Production Services
 
 ```bash
-# Using OpenSearch and NATS (production-like setup)
+# production-like setup
 SEARCH_SOURCE=opensearch \
+ORG_SEARCH_SOURCE=clearbit \
 ACCESS_CONTROL_SOURCE=nats \
 OPENSEARCH_URL={{placeholder}} \
 OPENSEARCH_INDEX=resources \
 NATS_URL{{placeholder}} \
+CLEARBIT_CREDENTIAL=your_clearbit_api_key \
+CLEARBIT_BASE_URL=https://company.clearbit.com \
+CLEARBIT_TIMEOUT=30s \
+CLEARBIT_MAX_RETRIES=5 \
+CLEARBIT_RETRY_DELAY=2s \
 go run cmd/main.go
 ```
 
@@ -124,6 +134,10 @@ go run cmd/main.go
 
 - `SEARCH_SOURCE`: Choose between "mock" or "opensearch" (default: "opensearch")
 
+**Organization Search Implementation:**
+
+- `ORG_SEARCH_SOURCE`: Choose between "mock" or "clearbit" (default: "clearbit")
+
 **OpenSearch Configuration:**
 
 - `OPENSEARCH_URL`: OpenSearch URL (default: `http://localhost:9200`)
@@ -140,6 +154,14 @@ go run cmd/main.go
 - `NATS_MAX_RECONNECT`: Maximum reconnection attempts (default: "3")
 - `NATS_RECONNECT_WAIT`: Time between reconnection attempts (default: "2s")
 
+**Clearbit Configuration:**
+
+- `CLEARBIT_CREDENTIAL`: Clearbit API key (required for organization search)
+- `CLEARBIT_BASE_URL`: Clearbit API base URL (default: `https://company.clearbit.com`)
+- `CLEARBIT_TIMEOUT`: HTTP client timeout for API requests (default: "10s")
+- `CLEARBIT_MAX_RETRIES`: Maximum number of retry attempts for failed requests (default: "3")
+- `CLEARBIT_RETRY_DELAY`: Delay between retry attempts (default: "1s")
+
 **Server Configuration:**
 
 - `-p`: HTTP port (default: "8080")
@@ -184,6 +206,59 @@ GET /query/resources?name=committee&type=committee&v=1
 }
 ```
 
+## Clearbit API Integration
+
+The service integrates with Clearbit's Company API to provide enriched organization data for search operations. This integration allows the service to fetch detailed company information including industry classification, employee count, and domain information.
+
+### Clearbit API Setup
+
+#### 1. Obtain API Credentials
+
+To use Clearbit integration, you need to obtain an API key from Clearbit:
+
+1. Sign up for a Clearbit account at [https://clearbit.com](https://clearbit.com)
+2. Navigate to your API settings to generate an API key
+3. Copy the API key for use in your environment configuration
+
+#### 2. Configure Environment Variables
+
+Set the required environment variables for Clearbit integration:
+
+```bash
+# Required: Clearbit API key
+export CLEARBIT_CREDENTIAL=your_clearbit_api_key_here
+
+# Optional: Custom configuration (defaults shown)
+export CLEARBIT_BASE_URL=https://company.clearbit.com
+export CLEARBIT_TIMEOUT=30s
+export CLEARBIT_MAX_RETRIES=3
+export CLEARBIT_RETRY_DELAY=1s
+
+# Set organization search source to use Clearbit
+export ORG_SEARCH_SOURCE=clearbit
+```
+
+#### 3. API Usage and Features
+
+The Clearbit integration supports the following search operations:
+
+**Search by Company Name:**
+- Searches for companies using their registered business name
+- Falls back to domain-based search for additional data enrichment
+
+**Search by Domain:**
+- More accurate search method using company domain names
+- Provides comprehensive company information
+
+#### 4. Error Handling
+
+The Clearbit integration includes robust error handling:
+
+- **404 Not Found**: Returns appropriate "organization not found" errors
+- **Rate Limiting**: Automatic retry with exponential backoff
+- **Network Issues**: Configurable retry attempts with delays
+- **API Errors**: Proper error propagation with context
+
 ### Testing
 
 The clean architecture makes testing straightforward:

charts/lfx-v2-query-service/Chart.yaml

@@ -5,5 +5,5 @@ apiVersion: v2
 name: lfx-v2-query-service
 description: LFX Platform V2 Query Service chart
 type: application
-version: 0.2.5
+version: 0.4.0
 appVersion: "latest"

cmd/main.go

@@ -7,21 +7,15 @@ import (
 	"context"
 	"flag"
 	"fmt"
-	"log"
 	"log/slog"
 	"os"
 	"os/signal"
-	"strconv"
 	"sync"
 	"syscall"
 	"time"
 
-	querysvcapi "github.com/linuxfoundation/lfx-v2-query-service/cmd/query_svc"
+	"github.com/linuxfoundation/lfx-v2-query-service/cmd/service"
 	querysvc "github.com/linuxfoundation/lfx-v2-query-service/gen/query_svc"
-	"github.com/linuxfoundation/lfx-v2-query-service/internal/domain/port"
-	"github.com/linuxfoundation/lfx-v2-query-service/internal/infrastructure/mock"
-	"github.com/linuxfoundation/lfx-v2-query-service/internal/infrastructure/nats"
-	"github.com/linuxfoundation/lfx-v2-query-service/internal/infrastructure/opensearch"
 	logging "github.com/linuxfoundation/lfx-v2-query-service/pkg/log"
 	"goa.design/clue/debug"
 )
@@ -61,15 +55,16 @@ func main() {
 	)
 
 	// Initialize the resource searcher based on configuration
-	resourceSearcher := searcherImpl(ctx)
-	accessControlChecker := accessControlCheckerImpl(ctx)
+	resourceSearcher := service.SearcherImpl(ctx)
+	accessControlChecker := service.AccessControlCheckerImpl(ctx)
+	organizationSearcher := service.OrganizationSearcherImpl(ctx)
 
 	// Initialize the services.
 	var (
 		querySvcSvc querysvc.Service
 	)
 	{
-		querySvcSvc = querysvcapi.NewQuerySvc(resourceSearcher, accessControlChecker)
+		querySvcSvc = service.NewQuerySvc(resourceSearcher, accessControlChecker, organizationSearcher)
 	}
 
 	// Wrap the services in endpoints that can be invoked from other services
@@ -93,7 +88,7 @@ func main() {
 	ctx, cancel := context.WithCancel(ctx)
 
 	// Setup the JWT authentication which validates and parses the JWT token.
-	querysvcapi.SetupJWTAuth(ctx)
+	service.SetupJWTAuth(ctx)
 
 	// Start the servers and send errors (if any) to the error channel.
 	addr := ":" + *port
@@ -141,128 +136,3 @@ func main() {
 
 	slog.InfoContext(ctx, "exited")
 }
-
-func searcherImpl(ctx context.Context) port.ResourceSearcher {
-
-	var (
-		resourceSearcher port.ResourceSearcher
-		err              error
-	)
-
-	// Search source implementation configuration
-	searchSource := os.Getenv("SEARCH_SOURCE")
-	if searchSource == "" {
-		searchSource = "opensearch"
-	}
-
-	opensearchURL := os.Getenv("OPENSEARCH_URL")
-	if opensearchURL == "" {
-		opensearchURL = "http://localhost:9200"
-	}
-
-	opensearchIndex := os.Getenv("OPENSEARCH_INDEX")
-	if opensearchIndex == "" {
-		opensearchIndex = "resources"
-	}
-
-	switch searchSource {
-	case "mock":
-		slog.InfoContext(ctx, "initializing mock resource searcher")
-		resourceSearcher = mock.NewMockResourceSearcher()
-
-	case "opensearch":
-		slog.InfoContext(ctx, "initializing opensearch resource searcher",
-			"url", opensearchURL,
-			"index", opensearchIndex,
-		)
-		opensearchConfig := opensearch.Config{
-			URL:   opensearchURL,
-			Index: opensearchIndex,
-		}
-
-		resourceSearcher, err = opensearch.NewSearcher(ctx, opensearchConfig)
-		if err != nil {
-			log.Fatalf("failed to initialize OpenSearch searcher: %v", err)
-		}
-
-	default:
-		log.Fatalf("unsupported search implementation: %s", searchSource)
-	}
-
-	return resourceSearcher
-
-}
-
-func accessControlCheckerImpl(ctx context.Context) port.AccessControlChecker {
-
-	var (
-		accessControlChecker port.AccessControlChecker
-		err                  error
-	)
-
-	// Access control implementation configuration
-	accessControlSource := os.Getenv("ACCESS_CONTROL_SOURCE")
-	if accessControlSource == "" {
-		accessControlSource = "nats"
-	}
-
-	natsURL := os.Getenv("NATS_URL")
-	if natsURL == "" {
-		natsURL = "nats://localhost:4222"
-	}
-
-	natsTimeout := os.Getenv("NATS_TIMEOUT")
-	if natsTimeout == "" {
-		natsTimeout = "10s"
-	}
-	natsTimeoutDuration, err := time.ParseDuration(natsTimeout)
-	if err != nil {
-		log.Fatalf("invalid NATS timeout duration: %v", err)
-	}
-
-	natsMaxReconnect := os.Getenv("NATS_MAX_RECONNECT")
-	if natsMaxReconnect == "" {
-		natsMaxReconnect = "3"
-	}
-	natsMaxReconnectInt, err := strconv.Atoi(natsMaxReconnect)
-	if err != nil {
-		log.Fatalf("invalid NATS max reconnect value %s: %v", natsMaxReconnect, err)
-	}
-
-	natsReconnectWait := os.Getenv("NATS_RECONNECT_WAIT")
-	if natsReconnectWait == "" {
-		natsReconnectWait = "2s"
-	}
-	natsReconnectWaitDuration, err := time.ParseDuration(natsReconnectWait)
-	if err != nil {
-		log.Fatalf("invalid NATS reconnect wait duration %s : %v", natsReconnectWait, err)
-	}
-
-	//natsReconnectWait := flag.Duration("nats-reconnect-wait", 2*time.Second, "NATS reconnection wait time")
-
-	// Initialize the access control checker based on configuration
-	switch accessControlSource {
-	case "mock":
-		slog.InfoContext(ctx, "initializing mock access control checker")
-		accessControlChecker = mock.NewMockAccessControlChecker()
-
-	case "nats":
-		slog.InfoContext(ctx, "initializing NATS access control checker")
-		natsConfig := nats.Config{
-			URL:           natsURL,
-			Timeout:       natsTimeoutDuration,
-			MaxReconnect:  natsMaxReconnectInt,
-			ReconnectWait: natsReconnectWaitDuration,
-		}
-
-		accessControlChecker, err = nats.NewAccessControlChecker(ctx, natsConfig)
-		if err != nil {
-			log.Fatalf("failed to initialize NATS access control checker: %v", err)
-		}
-
-	default:
-		log.Fatalf("unsupported access control implementation: %s", accessControlSource)
-	}
-
-	return accessControlChecker
-}