Google Module

Overview

The Google module integrates two Google Cloud services:

1. Google Places API — address autocomplete and place detail parsing for business onboarding
2. GCP Secret Manager — runtime secret retrieval for addon configuration

Architecture

google/
├── google.module.ts                         # Module definition
├── application/
│   ├── places.service.ts                    # Places business logic + address parsing
│   └── secrets.service.ts                   # Secret Manager access with local fallback
├── domain/
│   ├── places-service.domain.ts             # IPlacesService port + domain types
│   └── secrets-service.domain.ts            # ISecretsService port
├── infrastructure/
│   ├── google-credentials.factory.ts        # Shared credential extraction helper
│   ├── places.providers.ts                  # PlacesClient DI provider
│   └── secrets.providers.ts                 # SecretManagerServiceClient DI provider
└── interfaces/
    ├── places.controller.ts                 # HTTP endpoints
    └── query/
        └── get-places-predictions.query.ts  # Query DTO with validation

Layer responsibilities:

• Domain — defines IPlacesService, ISecretsService interfaces and domain types (PlacePrediction, ParsedAddress, ParsedPlaceData). No framework or SDK dependencies.
• Application — implements service interfaces. PlacesService calls the Google Places gRPC client and maps responses to domain types. SecretsService reads secrets from GCP Secret Manager (or local env vars in dev).
• Infrastructure — factory providers that instantiate Google Cloud SDK clients using Firebase credentials.
• Interfaces — thin HTTP controller for Places endpoints.

Domain Concepts

PlacePrediction

Autocomplete suggestion with a placeId and display text.

ParsedPlaceData

Result of fetching a place by ID, containing:

• parsedPoint — geographic coordinates ({ x: latitude, y: longitude })
• parsedAddress — structured address (municipality, department, country, postal code)

Guatemalan Postal Code Lookup

Google Places does not always return postal codes for Guatemalan addresses. The service includes a fallback lookup table (@/raw/guatemala.raw) that maps address component names to postal codes.

API Endpoints

GET /places/autocomplete

Search for place predictions based on a text query.

Parameter	Type	Required	Default	Description
search	string	yes	—	Search text
latitude	number	no	14.6353928	Center latitude
longitude	number	no	-90.5075376	Center longitude
radius	number	no	50000	Radius in meters

Response: PlacePrediction[]

[
  { "placeId": "ChIJ...", "text": "Zone 10, Guatemala City" }
]

GET /places/:id

Fetch a Google Place by ID and return parsed address and point data.

Parameter	Type	Required	Description
id	string	yes	Google Place ID

Response: ParsedPlaceData

{
  "parsedPoint": { "x": 14.5965, "y": -90.5135 },
  "parsedAddress": {
    "postalCode": "01010",
    "department": "guatemala",
    "municipality": "guatemala",
    "countryId": "gt"
  }
}

Secrets Service

Used internally by other modules (not exposed via HTTP).

• accessSecretLastVersionValue(name) — get latest version of a secret
• accessSecretVersionValue({ name, version }) — get specific version

When LOCAL_SECRETS=true is set, secrets are read from environment variables via ConfigService instead of calling GCP.

Consumers

Module	Service Used	Purpose
Users (onboarding)	PlacesService	Address lookup during business onboarding
Addons	SecretsService	Fetch payment gateway configuration

Configuration

Required environment variables:

Variable	Description
FIREBASE_CLIENT_EMAIL	GCP service account email
FIREBASE_PRIVATE_KEY	GCP service account private key
FIREBASE_PROJECT_ID	GCP project ID
LOCAL_SECRETS	Set to "true" to read secrets from env vars instead of Secret Manager