gh-onezerocompany-claude-project-basics/skills/spec-author/templates/configuration-schema.md

# Configuration Schema: <!-- TODO: Feature Name -->

**Document ID:** `config-[project]-[feature-number]-[slug]`
**Created:** <!-- TODO: YYYY-MM-DD -->
**Status:** <!-- TODO: Draft | Active | Deprecated -->
**Owner:** <!-- TODO: Team/Individual -->

---

## Overview

### Purpose
<!-- TODO: Brief description of what this configuration controls -->

### Scope
<!-- TODO: Which components/services use this configuration -->

### Configuration Files
<!-- TODO: List configuration files and their locations, e.g.:
- **Primary:** `config/[environment].yml`
- **Overrides:** `config/local.yml` (git-ignored)
- **Secrets:** Environment variables or vault
-->

### Precedence Order
<!-- TODO: How configuration sources are merged, highest priority first, e.g.:
1. Environment variables
2. Local overrides (`config/local.yml`)
3. Environment-specific (`config/production.yml`, `config/development.yml`)
4. Base defaults (`config/default.yml`)
-->

---

## Configuration Structure

### File Organization
<!-- TODO: Document configuration file structure using YAML or JSON format example -->

---

## Common Settings

### Server Configuration
<!-- TODO: Document server configuration settings with examples, e.g.:
```yaml
server:
  host: localhost
  port: 3000
  timeout: 30000  # milliseconds
```

**Key Settings:**
- `host`: Server bind address
- `port`: Server port number
-->

### Database Configuration
<!-- TODO: Document database configuration settings with examples, e.g.:
```yaml
database:
  adapter: postgresql
  host: localhost
  port: 5432
  name: app_development
  username: dbuser
  password: ${DB_PASSWORD}  # Use env var
```

**Key Settings:**
- `adapter`: Database type
- `pool.max`: Maximum database connections
-->

### Cache Configuration
<!-- TODO: OPTIONAL - Remove if not applicable. Document cache configuration:
```yaml
cache:
  adapter: redis
  host: localhost
  port: 6379
  ttl: 3600  # seconds
```
-->

### Logging Configuration
<!-- TODO: Document logging configuration settings with examples, e.g.:
```yaml
logging:
  level: info  # debug, info, warn, error
  format: json  # json, text
  outputs:
    - type: console
    - type: file
      path: logs/app.log
```

**Key Settings:**
- `level`: Minimum log level to output
- `format`: Log output format
-->

### Security Configuration
<!-- TODO: Document security configuration settings with examples, e.g.:
```yaml
security:
  jwt:
    secret: ${JWT_SECRET}  # Use env var
    expiry: 3600  # seconds
  cors:
    enabled: true
    allowed_origins:
      - "http://localhost:3000"
```

**Key Settings:**
- Document important security settings
-->

---

## Required vs Optional

### Required Configuration
<!-- TODO: Document configuration that MUST be set for the application to start

**Environment Variables:**
```bash
# Required in all environments
DB_PASSWORD=<database-password>
JWT_SECRET=<jwt-signing-secret>
```

**Validation Rules:**
- List validation rules
-->

### Optional Configuration
<!-- TODO: Document configuration with sensible defaults

**Settings with Defaults:**
- `setting.name`: Defaults to value
-->

---

## Feature Flags

<!-- TODO: OPTIONAL - Remove if not applicable. Document feature flags:
```yaml
features:
  new_feature:
    enabled: false
    rollout_percentage: 0  # 0-100

  experimental_feature:
    enabled: false
    environments:
      - development
      - staging
```

**Feature Flag Guidelines:**
- Default to `false` for new features
- Use `rollout_percentage` for gradual rollout
-->

---

## Configuration Examples

### Development Environment
<!-- TODO: Document development environment configuration example:
```yaml
# config/development.yml
server:
  host: localhost
  port: 3000

database:
  adapter: postgresql
  host: localhost
  port: 5432
  name: app_development
```
-->

### Production Environment
<!-- TODO: Document production environment configuration example:
```yaml
# config/production.yml
server:
  host: 0.0.0.0
  port: 8080

database:
  adapter: postgresql
  host: db.production.internal
  port: 5432
  name: app_production
```
-->

---

## Configuration Validation

### Startup Validation
<!-- TODO: Document checks performed when application starts

**Validation Steps:**
1. Required environment variables are set
2. Configuration files are valid YAML/JSON
3. Database connection is successful
4. Port is available

**Failure Behavior:**
- Application fails to start if validation fails
- Error messages indicate which configuration is invalid
-->

### Runtime Validation
<!-- TODO: OPTIONAL - Remove if not applicable. Document checks performed during operation

**Health Checks:**
- Database connection pool health
- Cache connectivity

**Monitoring Alerts:**
- Connection pool exhaustion
- Cache miss rate exceeds threshold
-->

---

## Environment Variables Reference

<!-- TODO: Document all environment variables:
```bash
# Database
DB_PASSWORD=<required>

# Security
JWT_SECRET=<required-min-32-chars>
API_KEY=<optional>

# External Services
REDIS_URL=<optional-defaults-to-config>
```
-->

---

## Troubleshooting

### Common Issues

<!-- TODO: Document common configuration issues and solutions

**Application won't start:**
- Check required environment variables are set
- Verify database connection settings
- Ensure port is not already in use

**Performance issues:**
- Review database pool settings
- Check cache hit rate and TTL settings
- Verify logging level is not set to `debug` in production

**Configuration not taking effect:**
- Check configuration precedence order
- Verify environment variable names match exactly
- Restart application after config changes
-->