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](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](12-chatbot-guide.md#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](12-chatbot-guide.md) 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.