Environment Variables

Config Flow

flowchart LR
    A["Shell env / CI secrets"] --> B["CDK Stack<br/>(process.env at synth time)"]
    B --> C["Lambda environment<br/>properties"]
    C --> D["Runtime code<br/>(process.env in handler)"]

    E["Cloudflare Pages<br/>dashboard"] --> F["NEXT_PUBLIC_*<br/>build-time vars"]
    G[".env.local files"] --> F

Environment variables flow through two paths:

1. Backend: Shell env → CDK stack reads process.env → sets Lambda environment properties → available as process.env in handler
2. Frontend: Set in Cloudflare Pages dashboard or .env.local → bundled at build time via NEXT_PUBLIC_* or VITE_* prefix

---

CDK Deploy-Time Variables

These are read by the CDK stack during cdk synth/cdk deploy and passed to Lambda environments:

Variable	Required	Description
CDK_DEFAULT_ACCOUNT	Yes	AWS account ID
CDK_DEFAULT_REGION	No	AWS region (defaults to us-east-1)
SENTRY_DSN	No	Sentry DSN for Lambda error tracking
SENTRY_RELEASE	No	Sentry release version
XERO_CLIENT_ID	No	Xero OAuth app client ID
XERO_CLIENT_SECRET	No	Xero OAuth app client secret
XERO_REDIRECT_URI	No	Xero OAuth redirect URI
SLACK_SIGNING_SECRET	No	Slack app signing secret for request verification
SLACK_BOT_TOKEN	No	Slack bot user OAuth token
ANTHROPIC_API_KEY	No	Anthropic API key for Claude title generation
SES_SENDER_EMAIL	No	SES-verified sender email address
CONTACT_EMAIL	No	Email to receive lead form submissions

---

Lambda Runtime Variables

Automatically configured by the CDK stack for each Lambda function.

Common (All Lambdas)

Variable	Value
CODE_VERSION	Hardcoded version string (e.g., 2025-01-27-cors-fix)
SENTRY_TRACES_SAMPLE_RATE	1.0
SENTRY_DSN	From deploy env
SENTRY_RELEASE	From deploy env
NODE_OPTIONS	--import @sentry/aws-serverless/awslambda-auto

task-sync

Variable	Source
TASKS_TABLE_NAME	task-time-tasks
USER_POOL_ID	Cognito user pool

time-entry-sync

Variable	Source
TIME_ENTRIES_TABLE_NAME	task-time-time-entries
TASKS_TABLE_NAME	task-time-tasks
CUSTOMERS_TABLE_NAME	task-time-customers
CUSTOMER_USERS_TABLE_NAME	task-time-customer-users
TIME_BILLS_TABLE_NAME	task-time-time-bills
PILLARS_TABLE_NAME	task-time-pillars
XERO_TOKENS_TABLE_NAME	task-time-xero-tokens
XERO_CLIENT_ID	From deploy env
XERO_CLIENT_SECRET	From deploy env
USER_POOL_ID	Cognito user pool

customer-sync

Variable	Source
CUSTOMERS_TABLE_NAME	task-time-customers
CUSTOMER_USERS_TABLE_NAME	task-time-customer-users
PILLARS_TABLE_NAME	task-time-pillars
CUSTOMER_FOCUS_TABLE_NAME	task-time-customer-focus
TIME_BILLS_TABLE_NAME	task-time-time-bills
TIME_ENTRIES_TABLE_NAME	task-time-time-entries
TASKS_TABLE_NAME	task-time-tasks
SES_SENDER_EMAIL	From deploy env
CONTACT_EMAIL	From deploy env
USER_POOL_ID	Cognito user pool

status-check

Variable	Source
TASKS_TABLE_NAME	task-time-tasks

active-timer-sync

Variable	Source
ACTIVE_TIMERS_TABLE_NAME	task-time-active-timers

xero-sync

Variable	Source
XERO_CLIENT_ID	From deploy env
XERO_CLIENT_SECRET	From deploy env
XERO_REDIRECT_URI	From deploy env
XERO_TOKENS_TABLE_NAME	task-time-xero-tokens

slack-integration

Variable	Source
SLACK_SIGNING_SECRET	From deploy env
SLACK_BOT_TOKEN	From deploy env
ANTHROPIC_API_KEY	From deploy env
TASKS_TABLE_NAME	task-time-tasks
CUSTOMERS_TABLE_NAME	task-time-customers
PILLARS_TABLE_NAME	task-time-pillars
SLACK_CHANNEL_MAPPINGS_TABLE_NAME	task-time-slack-channel-mappings
USER_POOL_ID	Cognito user pool

---

Frontend Variables (Web Portal)

Set in apps/web/.env.local or the Cloudflare Pages dashboard for production:

Variable	Description
NEXT_PUBLIC_API_BASE_URL	API Gateway base URL (e.g., https://xxx.execute-api.us-east-1.amazonaws.com/prod)
NEXT_PUBLIC_COGNITO_USER_POOL_ID	Cognito user pool ID
NEXT_PUBLIC_COGNITO_CLIENT_ID	Cognito app client ID
NEXT_PUBLIC_COGNITO_REGION	AWS region (e.g., us-east-1)
NEXT_PUBLIC_SENTRY_DSN	Sentry DSN for frontend error tracking
NEXT_PUBLIC_DOCS_URL	URL of the deployed MKDocs documentation site

Frontend Variables (Desktop App)

Set in apps/desktop/.env:

Variable	Description
VITE_API_BASE_URL	API Gateway base URL
VITE_COGNITO_USER_POOL_ID	Cognito user pool ID
VITE_COGNITO_CLIENT_ID	Cognito app client ID
VITE_COGNITO_REGION	AWS region
VITE_SENTRY_DSN	Sentry DSN for desktop error tracking

Deployment Script Variables

Required by scripts/deploy.sh:

Variable	Description
SENTRY_AUTH_TOKEN	Sentry API authentication token
SENTRY_ORG	Sentry organization slug
SENTRY_PROJECT_WEB	Sentry project name for web app
SENTRY_PROJECT_HOMEPAGE	Sentry project name for homepage
SENTRY_PROJECT_DESKTOP	Sentry project name for desktop app
SENTRY_PROJECT_LAMBDAS	Sentry project name for Lambda functions