Vapora/provisioning/schemas/platform/configs/README.md

# Platform Configs

Composed Nickel configurations ready for export.

## Configuration Files

Composed configurations for VAPORA with different deployment modes:

- `vapora-solo.ncl` - Solo mode (development)
- `vapora-multiuser.ncl` - Multiuser mode (team)
- `vapora-enterprise.ncl` - Enterprise mode (production)
- `main.ncl` - Entry point for exporting all configs

Each file combines:
1. **Schema** - Structure definition from `vapora/main.ncl`
2. **Common Defaults** - Base values for all modes
3. **Mode Defaults** - Mode-specific overrides (solo/multiuser/enterprise)
4. **User customizations** - Optional overrides (commented examples)

## Composition Pattern

```
VAPORA Schema (vapora/main.ncl)
    ↓
Platform Common Defaults (platform/defaults/common/)
    ↓
Mode-Specific Defaults (platform/defaults/deployment/{mode}.ncl)
    ↓
User Customizations (optional)
    ↓
Final Configuration
```

## Configuration Details

### Solo Mode (`vapora-solo.ncl`)

**Best for**: Local development, testing, PoCs

**Defaults**:
- Host: `127.0.0.1` (localhost only)
- Backend: 2 workers, file-based database
- Agents: 3 max instances, no NATS
- Router: Cost tracking disabled
- Security: JWT only (no TLS, no MFA)

**Customization examples**:
```nickel
# Enable debugging
monitoring.log_level = "debug",

# Change port
backend.port = 9001,

# Enable Ollama
llm_router.providers.ollama_enabled = true,
```

### Multiuser Mode (`vapora-multiuser.ncl`)

**Best for**: Team development, staging, internal deployments

**Defaults**:
- Host: `0.0.0.0` (network accessible)
- Backend: 4 workers, remote SurrealDB
- Agents: 10 max instances, NATS enabled
- Router: Cost tracking enabled (per-role budgets)
- Security: TLS + MFA + audit logging
- Knowledge graph: 30-day retention

**Customization examples**:
```nickel
# Set external domain
frontend.api_url = "https://api.vapora.internal:8001",

# Adjust team budgets
llm_router.budget_enforcement.role_limits = {
  architect_cents = 750000,    # $7500/month
  developer_cents = 500000,    # $5000/month
},

# Enable additional providers
providers.openai_enabled = true,
providers.gemini_enabled = true,
```

### Enterprise Mode (`vapora-enterprise.ncl`)

**Best for**: Production deployments, large organizations, HA

**Defaults**:
- Host: `0.0.0.0` (clustered)
- Backend: 8 workers, 2000 max connections
- Agents: 50 instances, NATS cluster
- Router: All providers enabled, cost optimization
- Database: SurrealDB cluster, 100 pool size
- Security: TLS enforced, MFA required, audit enabled
- Observability: Prometheus, OpenTelemetry, tracing
- Knowledge graph: 90-day retention
- Backup: Every 6 hours

**Customization examples**:
```nickel
# Set production domain
frontend.api_url = "https://api.vapora.production.com",

# All providers with custom Ollama endpoint
ollama_url = "http://ollama-cluster.production:11434",

# Aggressive cost control
llm_router.budget_enforcement.near_threshold_percent = 70,

# Extended learning window
agents.learning.recency_window_days = 30,
```

## Usage Patterns

### 1. Export Solo to JSON

```bash
nickel export schemas/platform/configs/vapora-solo.ncl > vapora-solo.json
```

### 2. Export Multiuser to JSON

```bash
nickel export schemas/platform/configs/vapora-multiuser.ncl > vapora-multiuser.json
```

### 3. Export Enterprise to JSON

```bash
nickel export schemas/platform/configs/vapora-enterprise.ncl > vapora-enterprise.json
```

### 4. Export with User Customizations

Create a custom config file that imports and customizes:

```nickel
# custom-vapora.ncl
let helpers = import "schemas/platform/common/helpers.ncl" in
let schema = import "schemas/vapora/main.ncl" in
let defaults = import "schemas/platform/defaults/deployment/multiuser.ncl" in

helpers.compose_config schema defaults {
  backend.port = 9001,
  llm_router.providers.ollama_enabled = true,
  monitoring.log_level = "debug",
}
```

Export:
```bash
nickel export custom-vapora.ncl > vapora-custom.json
```

### 5. Generate TOML from JSON

```bash
# Export to JSON, then convert via template
nickel export schemas/platform/configs/vapora-solo.ncl | \
  jinja2 schemas/platform/templates/configs/toml.j2 > vapora.toml
```

### 6. Generate Docker Compose

```bash
# Generate from multiuser config
nickel export schemas/platform/configs/vapora-multiuser.ncl | \
  jinja2 schemas/platform/templates/docker-compose/docker-compose.yaml.j2 > docker-compose.yml

# Deploy
docker compose up -d
```

### 7. Generate Kubernetes ConfigMap

```bash
# Generate from enterprise config
nickel export schemas/platform/configs/vapora-enterprise.ncl | \
  jinja2 schemas/platform/templates/kubernetes/configmap.yaml.j2 > configmap.yaml

# Deploy
kubectl apply -f configmap.yaml
```

## Exporting All Configurations

Use the main entry point to export all modes:

```bash
nickel export schemas/platform/configs/main.ncl > all-configs.json
```

This generates:
```json
{
  "solo": { ... },
  "multiuser": { ... },
  "enterprise": { ... }
}
```

## Composition Details

Each config uses the **helper functions** to compose:

```nickel
let helpers = import "../common/helpers.ncl" in

helpers.compose_config schema defaults_mode user_customizations
```

This merges in order:
1. `schema` - Defines structure and types
2. `defaults_mode` - Overrides with mode-specific values
3. User customizations - Final overrides

## References

- Parent: `../README.md`
- VAPORA schema: `../../vapora/README.md`
- Platform helpers: `../common/helpers.ncl`
- Platform defaults: `../defaults/README.md`
- Platform values: `../values/README.md`
- Templates: `../templates/README.md`
- Constraints: `../constraints/README.md`
- Validators: `../validators/README.md`