query-orchestration/docs/ai.generated/07-configuration-management.md

Configuration Management

This document reflects the current configuration model implemented under internal/serviceconfig.

Loading Model

Configuration is loaded through:

1. .env (if present)
2. Environment variables
3. Struct defaults (envDefault)

Runtime initialization is handled by serviceconfig.InitializeConfig.

Core Configuration (internal/serviceconfig/common.go)

• PORT (default 8080)
• BASE_URL (default http://localhost)
• Embedded config domains:
  • auth
  • thread pool
  • logger
  • observability
  • database
  • aws
  • queue

Database Configuration (internal/serviceconfig/database/config.go)

Required:

• PGUSER
• PGPASSWORD
• PGHOST
• PGPORT
• PGDATABASE

Optional:

• DB_NOSSL (default false)

AWS/Object Store Configuration

AWS (internal/serviceconfig/aws/config.go)

• AWS_REGION (required)
• AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN (optional; SDK chain also supported)
• AWS_ENDPOINT_URL (optional global endpoint override)
• AWS_PROFILE (optional)

Object Store (internal/serviceconfig/objectstore/config.go)

• BUCKET (required)
• AWS_ENDPOINT_URL_S3 (optional S3-specific endpoint)
• AWS_S3_USE_PATH_STYLE (default false)

Queue Client (internal/serviceconfig/queue/config.go)

• AWS_ENDPOINT_URL_SQS (optional SQS-specific endpoint)

Queue URL Variables (service-specific)

Active flow:

• STORE_EVENT_URL
• DOCUMENT_INIT_URL
• DOCUMENT_SYNC_URL
• DOCUMENT_CLEAN_URL
• CLIENT_SYNC_URL

Compatibility/deprecated flow (still used by some deployment files):

• DOCUMENT_TEXT_URL
• QUERY_SYNC_URL
• QUERY_URL
• QUERY_VERSION_SYNC_URL

Per-runner listener queue URL:

• QUEUE_URL (required by runner base config)

Authentication / Authorization

From internal/serviceconfig/auth/config.go:

• COGNITO_REGION (default us-east-2)
• COGNITO_USER_POOL_ID (required)
• COGNITO_CLIENT_SECRET (required)
• COGNITO_DOMAIN (required)
• COGNITO_CLIENT_ID (required)
• DISABLE_AUTH (default false)
• NO_JWT_VALIDATION (default false)
• PERMIT_IO_API_KEY (optional but required for full Permit.io operation)
• PERMIT_IO_PDP_URL (default http://localhost:7766)
• COGNITO_ENVIRONMENT_ID (optional, default empty) - Scopes this server instance to a specific environment within a shared Cognito user pool. When set, only users tagged with this environment ID (or untagged legacy users) are visible to admin operations and EULA compliance. Must be lowercase alphanumeric with underscores allowed in middle positions, max 50 characters. Empty string means no scoping (backward compatible).

Two-pool service accounts (optional; see 13-two-pool-service-accounts.md):

• COGNITO_SVC_USER_POOL_ID (default empty) - Cognito user pool id for service accounts ("pool B"). Empty disables the feature; queryAPI then validates tokens only against COGNITO_USER_POOL_ID. Setting this turns on multi-issuer validation.
• COGNITO_SVC_JWKS_URL (default derived) - JWKS endpoint for pool B. When unset, queryAPI computes https://cognito-idp.<COGNITO_REGION>.amazonaws.com/<COGNITO_SVC_USER_POOL_ID>/.well-known/jwks.json at startup. Override only for testing against a fake JWKS server.
• COGNITO_SVC_APP_CLIENT_ID (default empty) - App client id for pool B. Consumed by the cmd/auth_related/service.account.tool CLI and by service-account callers issuing InitiateAuth; queryAPI itself does not read it at runtime.

Auth path customization:

• COGNITO_LOGIN_PATH (default /login)
• COGNITO_CALLBACK_PATH (default /login-callback)
• COGNITO_HOME_PATH (default /home)
• COGNITO_LOGOUT_PATH (default /logout)
• HEALTH_PATH (default /health)

Local development bootstrap, active only when DISABLE_AUTH=true:

• LOCAL_DEV_CLIENT_ID (optional) - Creates this client at queryAPI startup when it does not already exist.
• LOCAL_DEV_CLIENT_NAME (optional) - Display name for LOCAL_DEV_CLIENT_ID; defaults to the client ID.
• LOCAL_DEV_EULA_VERSION (optional) - Creates or updates this local EULA version and marks it current.
• LOCAL_DEV_EULA_TITLE (optional) - Title for the local EULA; defaults to AArete DoczyAI Terms of Use.
• LOCAL_DEV_EULA_AUTO_ACCEPT_SUBJECT (optional) - Cognito subject/user key to mark as accepted for the local EULA.
• LOCAL_DEV_EULA_AUTO_ACCEPT_EMAIL (optional) - Email for the auto-accepted user; defaults to the subject value.

Rate Limiting

From internal/serviceconfig/ratelimit/config.go:

• RATE_LIMIT_GLOBAL_RATE
• RATE_LIMIT_GLOBAL_BURST
• RATE_LIMIT_DEFAULT_RATE
• RATE_LIMIT_DEFAULT_BURST
• RATE_LIMIT_EXPIRES_IN
• RATE_LIMIT_ENDPOINT_OVERRIDES (JSON)

Defaults:

• Global: 500 rps, burst 1000
• Per-IP: 5 rps, burst 10

M6 behavior change (plan §10 M6 + §11): RATE_LIMIT_ENDPOINT_OVERRIDES now changes ACTUAL throttling behavior, not only the RateLimit and Retry-After response headers. Each (IP, route) tuple gets its own budget when the route has an override entry. Operators upgrading from pre-M6 deployments should review existing overrides for unintended tightening. Override map keys use Echo's path template form (:clientId, :sessionId), NOT the OpenAPI {clientId} form. See Chatbot Guide → Rate-limit overrides for the chatbot turn-endpoint example.

Chatbot (FastAPI agent service)

From internal/serviceconfig/chatbot/config.go. Plan §8.

Variable	Default	Validation	Purpose
CHATBOT_SERVICE_URL	(required, notEmpty)	env-loader rejects empty	FastAPI base URL.
CHATBOT_API_KEY	(required, notEmpty)	env-loader rejects empty	Sent verbatim as the X-API-Key header.
CHATBOT_REQUEST_TIMEOUT_SECONDS	60	>= 1	Per-attempt FastAPI HTTP timeout.
CHATBOT_MAX_TURN_CHARS	2000	1 <= x <= 65536	Caps prompt and answer.text rune count. Upper bound (chatbot.MaxTurnCharsCeiling) tracks the OpenAPI prompt.maxLength so the configured cap is always reachable.
CHATBOT_RECENT_TURNS	5	1 <= x <= 5	Conversation-history length and session-list preview cap.

Validated at startup via chatbot.ChatbotConfig.Validate(), called between serviceconfig.InitializeConfig and cfg.InitializeAuthConfig in cmd/queryAPI/main.go. The process exits with status 1 on validation failure.

Derived constants (not env-driven):

• chatbot.StateMaxBytes = 64 * 1024 — session-state cap on persist.
• chatbot.MaxTurnCharsCeiling = 65536 — upper bound on CHATBOT_MAX_TURN_CHARS, mirroring the OpenAPI BotTurnAddRequest.prompt.maxLength in serviceAPIs/queryAPI.yaml. Changing one requires changing the other.
• chatbot.ChatbotConfig.InflightGraceSeconds() = 2 * RequestTimeoutSeconds per plan §8 literal.

See Chatbot Guide for the complete configuration reference, including the grace-window floor.

Logging and Observability

• LOG_LEVEL (default INFO)
• ENABLE_OTEL (default false)

Notes

• Some deployment files still include legacy query/text environment variables because deprecated compatibility services remain in compose definitions.
• For API/runtime behavior, prefer serviceAPIs/queryAPI.yaml plus internal/serviceconfig/* as source of truth.