# Configurations\n\nMode-specific Nickel configurations for all services (NOT manually edited).\n\n## Purpose\n\nConfigurations are **automatically generated** by composing:\n1. Service base defaults (defaults/{service}-defaults.ncl)\n2. Mode overlay (defaults/deployment/{mode}-defaults.ncl)\n3. User customization (values/{service}.{mode}.ncl)\n4. Schema validation (schemas/{service}.ncl)\n5. Constraint validation (validators/{service}-validator.ncl)\n\n## File Organization\n\n```\nconfigs/\n├── README.md                           # This file\n├── orchestrator.solo.ncl               # Orchestrator solo mode\n├── orchestrator.multiuser.ncl          # Orchestrator multi-user mode\n├── orchestrator.cicd.ncl               # Orchestrator CI/CD mode\n├── orchestrator.enterprise.ncl         # Orchestrator enterprise mode\n├── control-center.solo.ncl\n├── control-center.multiuser.ncl\n├── control-center.cicd.ncl\n├── control-center.enterprise.ncl\n├── mcp-server.solo.ncl\n├── mcp-server.multiuser.ncl\n├── mcp-server.cicd.ncl\n├── mcp-server.enterprise.ncl\n├── installer.solo.ncl\n├── installer.multiuser.ncl\n├── installer.cicd.ncl\n└── installer.enterprise.ncl\n```\n\n## Configuration Composition\n\nEach config is built from layers:\n\n```\n# configs/orchestrator.solo.ncl\nlet schemas = import "../schemas/orchestrator.ncl" in\nlet defaults = import "../defaults/orchestrator-defaults.ncl" in\nlet solo_defaults = import "../defaults/deployment/solo-defaults.ncl" in\nlet validators = import "../validators/orchestrator-validator.ncl" in\n\n{\n  # Merge: base defaults + mode overrides + user customization\n  orchestrator = defaults.orchestrator & solo_defaults.services.orchestrator & {\n    # User customization goes here (from values/orchestrator.solo.ncl)\n  },\n} | schemas.OrchestratorConfig  # Apply schema validation\n```\n\n## Example Configuration\n\n### Base Defaults\n\n```\n# defaults/orchestrator-defaults.ncl\norchestrator = {\n  workspace = {\n    name = "default",\n    path = "/var/lib/provisioning/orchestrator",\n    enabled = true,\n  },\n  server = {\n    host = "127.0.0.1",\n    port = 9090,\n    workers = 4,\n  },\n  queue = {\n    max_concurrent_tasks = 5,\n  },\n}\n```\n\n### Solo Mode Override\n\n```\n# defaults/deployment/solo-defaults.ncl\nservices.orchestrator = {\n  workers = 2,                    # Fewer workers\n  queue_max_concurrent_tasks = 3,  # Limited concurrency\n  storage_backend = 'filesystem,\n}\n```\n\n### Generated Config\n\n```\n# configs/orchestrator.solo.ncl (auto-generated)\n{\n  orchestrator = {\n    workspace = {\n      name = "default",           # From base defaults\n      path = "/var/lib/provisioning/orchestrator",\n      enabled = true,\n    },\n    server = {\n      host = "127.0.0.1",         # From base defaults\n      port = 9090,                # From base defaults\n      workers = 2,                # OVERRIDDEN by solo mode\n    },\n    queue = {\n      max_concurrent_tasks = 3,   # OVERRIDDEN by solo mode\n    },\n  },\n}\n```\n\n## Updating Configurations\n\n**DO NOT manually edit** configs/ files. Instead:\n\n1. **Modify service defaults** (defaults/{service}-defaults.ncl)\n2. **Modify mode overrides** (defaults/deployment/{mode}-defaults.ncl)\n3. **Modify user values** (values/{service}.{mode}.ncl)\n4. **Regenerate configs** (via TypeDialog or manual rebuild)\n\n### Regenerating Configs\n\n#### Via TypeDialog (Recommended)\n\n```\nnu provisioning/.typedialog/provisioning/platform/scripts/configure.nu orchestrator solo\n```\n\nAutomatically:\n1. Loads existing config as defaults\n2. Shows form with validated constraints\n3. User edits configuration\n4. Generates updated config\n\n#### Manual Rebuild\n\n```\n# (Future) Script to rebuild all configs from sources\nnu provisioning/.typedialog/provisioning/platform/scripts/generate-configs.nu orchestrator solo\n```\n\n## Config Types\n\n### Orchestrator (Workflow Engine)\n- Workspace configuration\n- Server settings\n- Storage backend (filesystem, RocksDB, SurrealDB)\n- Queue configuration (concurrency, retries, timeout)\n- Batch workflow settings\n- Optional: monitoring, rollback, extensions\n\n### Control Center (Policy/RBAC)\n- Workspace configuration\n- Server settings\n- Database configuration\n- Security (JWT, RBAC, encryption)\n- Optional: compliance, audit logging\n\n### MCP Server (Protocol Server)\n- Workspace configuration\n- Server settings\n- MCP capabilities (tools, prompts, resources)\n- Optional: custom tools, resource limits\n\n### Installer (Setup Automation)\n- Target configuration\n- Provider settings\n- Pre-flight checks\n- Installation options\n\n## Configuration Values Hierarchy\n\n```\n1. Explicit user customization (values/{service}.{mode}.ncl)\n2. Mode-specific defaults (defaults/deployment/{mode}-defaults.ncl)\n3. Service base defaults (defaults/{service}-defaults.ncl)\n4. Common shared defaults (defaults/common/*.ncl)\n```\n\n## Validation Levels\n\nConfigurations are validated at three levels:\n\n### 1. Schema Validation\nType checking when config is evaluated:\n\n```\n| schemas.OrchestratorConfig\n```\n\n### 2. Constraint Validation\nRange checking via validators:\n\n```\nmax_concurrent_tasks = validators.ValidConcurrentTasks 5\n```\n\n### 3. Business Logic Validation\nService-specific rules in validators.\n\n## Usage in Rust Services\n\nConfigs are exported to TOML for Rust services:\n\n```\n# Generate TOML\nnu provisioning/.typedialog/provisioning/platform/scripts/generate-configs.nu orchestrator solo\n\n# Output: provisioning/platform/config/orchestrator.solo.toml\n```\n\nRust services load the TOML:\n\n```\nlet config_path = "provisioning/platform/config/orchestrator.solo.toml";\nlet config = Config::from_file(config_path)?;\n```\n\n## Deployment Mode Specifics\n\n### Solo Mode Config\n- Minimal resources (2 CPU, 4GB)\n- Filesystem storage (no DB infrastructure)\n- Single worker, low concurrency\n- Simplified security (no MFA)\n\n### MultiUser Mode Config\n- Team resources (4 CPU, 8GB)\n- PostgreSQL or SurrealDB\n- Moderate concurrency (4-8 workers)\n- RBAC enabled\n\n### CI/CD Mode Config\n- Ephemeral (cleanup after run)\n- API-driven (no UI/forms)\n- High concurrency (8+ workers)\n- Minimal security overhead\n\n### Enterprise Mode Config\n- Production HA (16+ CPU, 32+ GB)\n- SurrealDB cluster with replication\n- High concurrency (16+ workers)\n- Full security (MFA, KMS, compliance)\n\n## Testing Configurations\n\n```\n# Typecheck a config\nnickel typecheck provisioning/.typedialog/provisioning/platform/configs/orchestrator.solo.ncl\n\n# Evaluate and view\nnickel eval provisioning/.typedialog/provisioning/platform/configs/orchestrator.solo.ncl | head -50\n\n# Export to TOML\nnickel export --format toml provisioning/.typedialog/provisioning/platform/configs/orchestrator.solo.ncl\n\n# Export to JSON\nnickel export --format json provisioning/.typedialog/provisioning/platform/configs/orchestrator.solo.ncl\n```\n\n## Configuration Merge Example\n\n```\n# Base\n{\n  server = {\n    host = "127.0.0.1",\n    port = 9090,\n    workers = 4,\n  },\n}\n\n# + Mode override\n& {\n  server.workers = 2,\n}\n\n# = Result\n{\n  server = {\n    host = "127.0.0.1",\n    port = 9090,\n    workers = 2,  # OVERRIDDEN\n  },\n}\n```\n\nNickel's `&` operator is a **shallow merge** - only top-level fields are replaced, deeper nesting is preserved.\n\n## Generated Config Structure\n\nAll generated configs follow this structure:\n\n```\n# Service config\n{\n  {service} = {\n    # Workspace\n    workspace = { ... },\n\n    # Server\n    server = { ... },\n\n    # Storage/Database\n    [storage | database] = { ... },\n\n    # Service-specific\n    [queue | rbac | capabilities] = { ... },\n\n    # Optional\n    [monitoring | security | compliance] = { ... },\n  },\n}\n```\n\n---\n\n**Version**: 1.0.0\n**Last Updated**: 2025-01-05
