feat:Multiple Concurrent Goals with Priority-Weighted Allocation

.env.development

@@ -1,29 +1,109 @@
+```env
+# ============================================================
+# Application Configuration
+# ============================================================
+
+# Runtime environment.
+# "development" enables development-specific behavior and settings.
 NODE_ENV=development
+
+# Port on which the backend API runs.
 PORT=3000
 
+
+# ============================================================
+# CORS Configuration
+# ============================================================
+
+# Comma-separated list of frontend origins allowed to access
+# the backend API during local development.
 CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001,http://localhost:5173
 
+# Maximum amount of time, in seconds, that browsers can cache
+# CORS preflight responses.
+CORS_MAX_AGE=3600
+
+# Allow credentials such as cookies and authorization headers
+# in cross-origin requests.
+CORS_ALLOW_CREDENTIALS=true
+
+
+# ============================================================
+# Database Configuration
+# ============================================================
+
+# PostgreSQL connection string for the development database.
 DATABASE_URL=postgresql://dev_user:dev_password@localhost:5432/neuro_backend_dev
+
+# PostgreSQL database host.
 DB_HOST=localhost
+
+# PostgreSQL database port.
 DB_PORT=5432
+
+# PostgreSQL database username.
 DB_USER=dev_user
+
+# PostgreSQL database password.
+# Use a local development password only.
 DB_PASSWORD=dev_password
+
+# Name of the development PostgreSQL database.
 DB_NAME=neuro_backend_dev
-# # AI
-# ANTHROPIC_API_KEY=get_from_console.anthropic.com
-# BRIAN_API_KEY=get_from_brianknows.org
+
+
+# ============================================================
+# Authentication / JWT Configuration
+# ============================================================
+
+# Secret used to sign and verify JWT access tokens.
+# Use a strong secret even in development.
 JWT_SECRET=dev-jwt-secret-key
+
+# Lifetime of JWT access tokens.
 JWT_EXPIRY=24h
+
+# Separate secret used to sign and verify refresh tokens.
 REFRESH_TOKEN_SECRET=dev-refresh-secret
 
+
+# ============================================================
+# AI / External API Configuration
+# ============================================================
+
+# Anthropic API key used by the application for AI functionality.
+# Replace the development placeholder with a valid API key when needed.
 ANTHROPIC_API_KEY=sk-dev-anthropic-key
+
+# OpenAI API key used by the application for OpenAI functionality.
+# Replace the development placeholder with a valid API key when needed.
 OPENAI_API_KEY=sk-dev-openai-key
 
+# Brian API key for Brian-related integrations.
+# Add a valid development key if the integration is enabled.
+# BRIAN_API_KEY=get_from_brianknows.org
+
+
+# ============================================================
+# Logging Configuration
+# ============================================================
+
+# Log level for development.
+# "debug" provides detailed information useful during development.
 LOG_LEVEL=debug
+
+# Output logs as structured JSON.
 LOG_FORMAT=json
 
+
+# ============================================================
+# HTTP / Server Configuration
+# ============================================================
+
+# Maximum amount of time the server waits for an HTTP request
+# before timing out, in milliseconds.
 SERVER_TIMEOUT=30000
-MAX_REQUEST_SIZE=10mb
 
-CORS_MAX_AGE=3600
-CORS_ALLOW_CREDENTIALS=true
+# Maximum size allowed for incoming HTTP request bodies.
+MAX_REQUEST_SIZE=10mb
+```

.env.example

@@ -1,81 +1,245 @@
+```env
+# ============================================================
 # Application Environment
+# ============================================================
+
+# Runtime environment for the backend application.
+# "development" enables development-specific behavior.
 NODE_ENV=development
+
+# Port on which the backend API will run.
 PORT=3000
 
-# Stellar
+
+# ============================================================
+# Stellar / Blockchain Configuration
+# ============================================================
+
+# Stellar network used by the application.
+# Options typically include testnet or mainnet.
 STELLAR_NETWORK=testnet
-# STELLAR_RPC_URL is optional — derived from STELLAR_NETWORK by default.
-# Set this only if you need a custom RPC endpoint (e.g., self-hosted or devnet).
+
+# Optional custom Stellar RPC endpoint.
+# By default, the application derives the RPC URL from STELLAR_NETWORK.
+# Set this only when using a custom RPC endpoint, self-hosted node,
+# or another development network.
 # STELLAR_RPC_URL=https://soroban-testnet.stellar.org
+
+# Stellar secret key for the application's agent wallet.
+# Replace this placeholder with a valid development/testnet secret key.
 STELLAR_AGENT_SECRET_KEY=your_agent_stellar_secret_key_here
+
+# Contract ID of the deployed Vault contract.
+# Replace this placeholder with the appropriate testnet contract ID.
 VAULT_CONTRACT_ID=your_deployed_contract_id_here
+
+# Stellar testnet USDC token contract/address.
+# Replace this placeholder with the correct testnet USDC contract address.
 USDC_TOKEN_ADDRESS=testnet_usdc_contract_address_here
 
-# AI
-ANTHROPIC_API_KEY=get_from_console.anthropic.com
+
+# ============================================================
+# AI / External API Configuration
+# ============================================================
+
+# Anthropic API key used for AI functionality.
+# Obtain a development API key from the Anthropic console.
+ANTHROPIC_API_KEY=your-anthropic-key-here
+
+# Brian API key used for Brian-related integrations.
+# Obtain a key from the Brian platform if this integration is enabled.
 BRIAN_API_KEY=get_from_brianknows.org
-# # AI
-# ANTHROPIC_API_KEY=get_from_console.anthropic.com
-# BRIAN_API_KEY=get_from_brianknows.org
-# Database
-DATABASE_URL=postgresql://postgres:password@localhost:5432/neurowealth
-
-# Wallet encryption
-# Generate with: openssl rand -hex 32
-WALLET_ENCRYPTION_KEY=generate_with_openssl_rand_hex_32
-# CORS Configuration - Production Security
-CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001
 
+# OpenAI API key used for OpenAI-related functionality.
+OPENAI_API_KEY=your-openai-key-here
+
+
+# ============================================================
 # Database Configuration
+# ============================================================
+
+# PostgreSQL connection URL for local development.
+# Keep this consistent with the individual DB_* variables below.
 DATABASE_URL=postgresql://user:password@localhost:5432/neuro_backend
+
+# PostgreSQL database host.
 DB_HOST=localhost
+
+# PostgreSQL database port.
 DB_PORT=5432
+
+# PostgreSQL database username.
 DB_USER=postgres
+
+# PostgreSQL database password.
+# Use a secure local development password where appropriate.
 DB_PASSWORD=password
+
+# Name of the local development database.
 DB_NAME=neuro_backend
 
-# Authentication
+
+# ============================================================
+# Wallet Encryption
+# ============================================================
+
+# Encryption key used to protect encrypted wallet/private-key data.
+# IMPORTANT: Generate a strong random value for development.
+#
+# Generate a 32-byte hexadecimal key with:
+# openssl rand -hex 32
+WALLET_ENCRYPTION_KEY=generate_with_openssl_rand_hex_32
+
+
+# ============================================================
+# Authentication / JWT Configuration
+# ============================================================
+
+# Secret used to sign and verify JWT access tokens.
+# Use a strong random value even during development.
 JWT_SECRET=your-secret-key-here
+
+# Lifetime of an access token.
 JWT_EXPIRY=24h
+
+# Separate secret used to sign and verify refresh tokens.
 REFRESH_TOKEN_SECRET=refresh-secret-key
 
-# API Keys
-ANTHROPIC_API_KEY=your-anthropic-key-here
-OPENAI_API_KEY=your-openai-key-here
 
-# Logging
+# ============================================================
+# Logging Configuration
+# ============================================================
+
+# Minimum log level emitted by the application.
+# Common values include debug, info, warn, and error.
 LOG_LEVEL=info
+
+# Log output format.
+# JSON is useful when logs are consumed by structured logging tools.
 LOG_FORMAT=json
 
-# Server
+
+# ============================================================
+# HTTP / Server Configuration
+# ============================================================
+
+# Maximum amount of time the server waits for an HTTP request
+# before timing out, in milliseconds.
 SERVER_TIMEOUT=30000
+
+# Maximum size of incoming HTTP request bodies.
 MAX_REQUEST_SIZE=10mb
 
-# CORS Specific
+
+# ============================================================
+# CORS Configuration
+# ============================================================
+
+# Comma-separated list of frontend origins allowed to make
+# cross-origin requests to the backend.
+#
+# Local development frontends:
+# - http://localhost:3000
+# - http://localhost:3001
+CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001
+
+# Maximum time, in seconds, that browsers may cache CORS
+# preflight responses.
 CORS_MAX_AGE=3600
+
+# Allow cookies and other credentials to be included in
+# cross-origin requests.
 CORS_ALLOW_CREDENTIALS=true
 
-# ── Real-time WebSocket streaming (#316) ─────────────────────────────────────
-# See docs/WEBSOCKET_STREAMING.md. All optional — the defaults shown are what
-# the code uses when the variable is unset.
+
+# ============================================================
+# Real-time WebSocket Streaming (#316)
+# ============================================================
+#
+# See docs/WEBSOCKET_STREAMING.md for the complete WebSocket
+# streaming configuration and implementation details.
+#
+# All WebSocket settings below are optional.
+# If a variable is not provided, the application uses its
+# corresponding default value.
+
+# WebSocket endpoint path.
 WS_PATH=/api/v1/ws
+
+# Interval between WebSocket heartbeat/ping checks, in milliseconds.
 WS_HEARTBEAT_INTERVAL_MS=30000
+
+# Maximum amount of time an idle WebSocket connection can remain
+# inactive before it is closed, in milliseconds.
 WS_IDLE_TIMEOUT_MS=90000
+
+# Maximum number of events that can be buffered for a connection.
 WS_MAX_BUFFERED_EVENTS=256
+
+# Maximum total size of buffered events, in bytes.
 WS_MAX_BUFFERED_BYTES=1048576
+
+# Maximum number of simultaneous WebSocket connections allowed
+# for a single user.
 WS_MAX_CONNECTIONS_PER_USER=5
+
+# Maximum number of handshake attempts allowed within the
+# configured handshake window.
 WS_HANDSHAKE_MAX=30
+
+# Time window used for limiting WebSocket handshake attempts,
+# in milliseconds.
 WS_HANDSHAKE_WINDOW_MS=60000
+
+# Maximum number of messages a client may send within the
+# configured message rate-limit window.
 WS_MESSAGE_MAX=50
+
+# Message rate-limit window, in milliseconds.
 WS_MESSAGE_WINDOW_MS=10000
+
+# Maximum size of an individual WebSocket message, in bytes.
 WS_MAX_MESSAGE_BYTES=4096
+
+# Maximum number of events that can be replayed when a client
+# reconnects and requests missed events.
 WS_REPLAY_MAX_EVENTS=1000
+
+# Interval at which the server re-checks the user's session,
+# in milliseconds.
 WS_SESSION_RECHECK_MS=60000
+
+# Time window used to coalesce multiple events into a single
+# delivery, in milliseconds.
 WS_COALESCE_WINDOW_MS=250
+
+# Delay before retrying a WebSocket drain operation,
+# in milliseconds.
 WS_DRAIN_RETRY_AFTER_MS=2000
-# Cross-pod fan-out channel. Requires REDIS_URL; without it delivery is
-# pod-local and clients close the gap with `resume afterSeq`.
+
+
+# ============================================================
+# Redis / Cross-Pod Event Fan-out
+# ============================================================
+
+# Redis pub/sub channel used to distribute user events across
+# multiple application pods/instances.
+#
+# Requires REDIS_URL to be configured.
+# Without Redis, event delivery remains pod-local and clients
+# can recover missed events using `resume afterSeq`.
 WS_EVENT_CHANNEL=neurowealth:user-events
-# Durable stream retention — bounded by age AND by rows per user.
+
+
+# ============================================================
+# Durable User Event Stream Retention
+# ============================================================
+
+# Maximum age of persisted user events.
+# Events older than this value can be removed during retention cleanup.
 RETENTION_USER_EVENTS_DAYS=7
+
+# Maximum number of persisted events retained per user.
+# Retention is bounded by both age and this per-user row limit.
 USER_EVENT_STREAM_MAX_PER_USER=5000
+```