# 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).

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`)

## 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`

## 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.