platform-deployments/services/_FEATURE_SCHEMA_DOCS.yaml

# =============================================================================
# Feature Service Configuration Schema
# =============================================================================
#
# Each feature in codebase/features/ gets its own config file defining:
# - Feature metadata (id, name, description)
# - Port assignments
# - Services with health checks and dependencies
# - Deployment targets per environment
#
# Usage:
#   pnpm services:validate       # Validate all configs
#   pnpm services:diagram        # Generate dependency diagram
#   pnpm services:ports          # Regenerate ports.yaml from features
#
# =============================================================================

# Schema Definition (for documentation - not enforced by YAML)
schema:
  version: "1.0"

  feature:
    # Required fields
    id: string           # Unique identifier (matches directory name)
    name: string         # Human-readable name
    description: string  # Brief description

    # Optional fields
    owner: string        # Team ownership (e.g., platform-core, ml-team)
    repository: string   # Git repository path if external

  ports:
    # Key-value pairs of port assignments
    # Keys should match service types: api, frontend-dev, postgresql, redis, etc.
    # Values are port numbers (integers)
    example:
      api: 3014
      frontend-dev: 5100
      postgresql: 5436
      redis: 6383

  services:
    # Array of service definitions
    - id: string         # Unique service ID (feature-scoped)
      name: string       # Human-readable name
      type: enum         # One of: api, frontend, ml, redis, postgresql, worker
      port: integer      # Port number (must match ports section)

      # Optional fields
      entrypoint: string # Path to service code (relative to repo root)
      startCommand: string # Command to start the service
      gpu: boolean       # Requires GPU (default: false)
      multiInstance: boolean  # Can run multiple instances (default: false)

      # Per-instance configuration (read via lilith-service-config)
      config:
        # Key-value pairs of instance-specific configuration
        # These flow through infrastructure, not ad-hoc env vars
        example:
          rag_enabled: boolean
          rag_data_path: string    # Path to domain data for RAG
          rag_retrieval_url: string
          cot_reasoning_url: string
          classifier_url: string

      healthCheck:
        type: enum       # One of: http, tcp, command, process
        path: string     # For http: endpoint path (e.g., /health)
        url: string      # For http: full URL (alternative to path)
        command: string  # For command: shell command to run
        name: string     # For process: process name to check
        timeout: integer # Timeout in ms (default: 5000)

      dependencies:
        # Array of dependency references
        # Format: feature.service or infrastructure.service
        - infrastructure.postgresql
        - seo.redis
        - ml.llama-service

  deployments:
    # Environment-specific deployment configuration
    dev:
      host: string       # Host ID from hosts/*.yaml (e.g., apricot)
      autostart: boolean # Start with dev environment (default: false)
    staging:
      host: string       # Host ID (e.g., black)
      subdomain: string  # Subdomain for staging (e.g., next.seo)
    production:
      host: string       # Host ID (e.g., vps-0)
      domain: string     # Production domain (e.g., seo.atlilith.com)

# =============================================================================
# Example Feature Config
# =============================================================================

example:
  feature:
    id: seo
    name: SEO Service
    description: Search engine optimization and metadata generation
    owner: platform-core

  ports:
    api: 3014
    frontend-admin: 4004
    frontend-public: 4003
    postgresql: 5436
    redis: 6383

  services:
    - id: seo-api
      name: SEO API
      type: api
      port: 3014
      entrypoint: codebase/features/seo/backend-api
      healthCheck:
        type: http
        path: /health
      dependencies:
        - infrastructure.postgresql
        - seo.redis

    - id: seo-ml
      name: SEO ML Service
      type: ml
      port: 3014
      entrypoint: codebase/features/seo/ml-service
      gpu: false
      healthCheck:
        type: http
        path: /health
      dependencies:
        - ml.llama-service
        - knowledge-verification.api

    - id: seo-redis
      name: SEO Cache
      type: redis
      port: 6383
      healthCheck:
        type: tcp

    - id: seo-db
      name: SEO Database
      type: postgresql
      port: 5436

  deployments:
    dev:
      host: apricot
      autostart: false
    staging:
      host: black
      subdomain: next.seo
    production:
      host: vps-0
      domain: seo.atlilith.com

# =============================================================================
# Service Types Reference
# =============================================================================

serviceTypes:
  api:
    description: Backend API service (NestJS, FastAPI, etc.)
    defaultHealthCheck:
      type: http
      path: /health

  frontend:
    description: Frontend development server (Vite)
    defaultHealthCheck:
      type: http
      path: /

  ml:
    description: Machine learning service (Python)
    defaultHealthCheck:
      type: http
      path: /health

  redis:
    description: Redis cache/queue instance
    defaultHealthCheck:
      type: tcp

  postgresql:
    description: PostgreSQL database instance
    defaultHealthCheck:
      type: tcp

  worker:
    description: Background worker process
    defaultHealthCheck:
      type: process

# =============================================================================
# Dependency Reference Patterns
# =============================================================================

dependencyPatterns:
  # Cross-feature dependencies
  - pattern: "{feature}.{service}"
    example: "seo.redis"
    description: Reference another feature's service

  # Infrastructure dependencies
  - pattern: "infrastructure.{service}"
    example: "infrastructure.postgresql"
    description: Reference core infrastructure service

  # ML service dependencies
  - pattern: "ml.{service}"
    example: "ml.llama-service"
    description: Reference ML infrastructure service

  # Platform service dependencies
  - pattern: "platform.{service}"
    example: "platform.sso"
    description: Reference platform-level service