# Relations Schema
# Defines the structure of the entity relationship graph
# Generated by build_relations.py, validated by validate_relations.py

version: "1.0"
description: |
  Entity relationship graph that tracks dependencies between database models,
  API endpoints, components, and pages. Used for:
  - Impact analysis (what breaks if X changes)
  - Type alignment validation (DB → API → Component → Page)
  - Dependency chain visualization
  - Change detection

# ============================================================================
# ROOT STRUCTURE
# ============================================================================
relations:
  type: object
  required: true
  fields:
    version:
      type: string
      required: true
      description: Schema version

    generated_at:
      type: datetime
      required: true
      description: When this relations file was generated

    source:
      type: string
      required: true
      description: Source file path (design document or 'code_analysis')

# ============================================================================
# ENTITIES
# ============================================================================
entities:
  type: object
  required: true
  description: Entities organized by type
  fields:
    database:
      type: array
      items:
        $ref: '#/entity_schema'
      description: Database models (Layer 1)

    api:
      type: array
      items:
        $ref: '#/entity_schema'
      description: API endpoints (Layer 2)

    component:
      type: array
      items:
        $ref: '#/entity_schema'
      description: UI components (Layer 3)

    page:
      type: array
      items:
        $ref: '#/entity_schema'
      description: Pages/routes (Layer 4)

# ============================================================================
# ENTITY SCHEMA
# ============================================================================
entity_schema:
  type: object
  fields:
    id:
      type: string
      required: true
      description: Unique entity identifier (e.g., model_user, api_get_users)

    type:
      type: enum
      values: [database, api, component, page]
      required: true
      description: Entity type

    name:
      type: string
      required: true
      description: Human-readable name

    file_path:
      type: string
      description: Path to implementation file

    layer:
      type: integer
      enum: [1, 2, 3, 4]
      description: |
        Architectural layer:
        1 = Database (no dependencies)
        2 = API (depends on database)
        3 = Component (depends on API/components)
        4 = Page (depends on API/components)

    depends_on:
      type: array
      items: string
      description: Entity IDs this entity depends on

    used_by:
      type: array
      items: string
      description: Entity IDs that depend on this entity

    status:
      type: enum
      values: [pending, approved, implemented, verified]
      description: Implementation status

# ============================================================================
# RELATIONS
# ============================================================================
relations_array:
  type: array
  description: All relationships between entities
  items:
    type: object
    fields:
      source:
        type: string
        required: true
        description: Source entity ID (the dependent)

      target:
        type: string
        required: true
        description: Target entity ID (the dependency)

      type:
        type: enum
        values:
          - queries     # API → Database
          - calls       # Component/Page → API, API → API
          - imports     # Component → Component
          - renders     # Page → Component
          - references  # Database → Database (foreign key)
        required: true
        description: Relationship type

# ============================================================================
# DEPENDENCY CHAINS
# ============================================================================
dependency_chains:
  type: object
  description: |
    Full dependency chains for each entity.
    Key = entity_id, Value = list of all transitive dependencies
  additionalProperties:
    type: array
    items: string

# ============================================================================
# IMPACT CHAINS
# ============================================================================
impact_chains:
  type: object
  description: |
    Impact chains showing what depends on each entity.
    Key = entity_id, Value = list of all entities that would be affected by changes
  additionalProperties:
    type: array
    items: string

# ============================================================================
# TYPE MAPPINGS
# ============================================================================
type_mappings:
  type: object
  description: |
    Field/property types for each entity.
    Used for type alignment validation between layers.
  additionalProperties:
    type: object
    additionalProperties:
      type: string
  example:
    model_user:
      id: uuid
      email: string
      name: string
    api_get_user:
      id: string
      email: string
      name: string
    component_user_card:
      user: User
      showActions: boolean

# ============================================================================
# ISSUES
# ============================================================================
issues:
  type: object
  description: Issues detected during relation building
  fields:
    circular_dependencies:
      type: array
      items:
        type: array
        items: string
      description: List of circular dependency cycles

# ============================================================================
# STATISTICS
# ============================================================================
statistics:
  type: object
  fields:
    total_entities:
      type: integer
      description: Total number of entities

    total_relations:
      type: integer
      description: Total number of relationships

    by_type:
      type: object
      fields:
        database: integer
        api: integer
        component: integer
        page: integer

    by_layer:
      type: object
      fields:
        1_database: integer
        2_api: integer
        3_component: integer
        4_page: integer

# ============================================================================
# VALIDATION RULES
# ============================================================================
validation_rules:
  reference_integrity:
    - "All depends_on references must exist in entities or external_dependencies"
    - "All used_by references must exist in entities"

  layer_constraints:
    - "Layer 1 (database) can only reference other Layer 1 entities"
    - "Layer 2 (api) can only depend on Layer 1 or Layer 2"
    - "Layer 3 (component) can only depend on Layer 2 or Layer 3"
    - "Layer 4 (page) can depend on Layer 2, 3, or 4"

  type_alignment:
    - "API response fields should have compatible types with database fields"
    - "Component props should have compatible types with API response fields"
    - "Page data should match component prop requirements"

  circular_detection:
    - "No circular dependencies allowed within same layer"
    - "Cross-layer circular dependencies indicate architecture issues"

# ============================================================================
# TYPE COMPATIBILITY MATRIX
# ============================================================================
type_compatibility:
  description: |
    Types are considered compatible if they belong to the same compatibility group.
    This allows for reasonable type coercion between layers.

  compatibility_groups:
    identifiers: [uuid, string, id]
    text: [string, text]
    numbers: [integer, int, number, float, decimal]
    booleans: [boolean, bool]
    timestamps: [datetime, date, string, Date]
    structured: [object, json, any, Record, JSON]
    collections: [array, Array, list]

# ============================================================================
# EXAMPLE OUTPUT
# ============================================================================
example:
  version: "1.0"
  generated_at: "2025-01-16T10:30:00Z"
  source: ".workflow/versions/v001/design/design_document.yml"

  entities:
    database:
      - id: model_user
        type: database
        name: User
        file_path: prisma/schema.prisma
        layer: 1
        depends_on: []
        used_by: [api_get_users, api_create_user]
        status: implemented

    api:
      - id: api_get_users
        type: api
        name: Get Users
        file_path: app/api/users/route.ts
        layer: 2
        depends_on: [model_user]
        used_by: [page_users, component_user_list]
        status: implemented

    component:
      - id: component_user_card
        type: component
        name: UserCard
        file_path: app/components/UserCard.tsx
        layer: 3
        depends_on: []
        used_by: [component_user_list, page_user_detail]
        status: implemented

    page:
      - id: page_users
        type: page
        name: Users Page
        file_path: app/users/page.tsx
        layer: 4
        depends_on: [api_get_users, component_user_list]
        used_by: []
        status: implemented

  relations:
    - source: api_get_users
      target: model_user
      type: queries

    - source: page_users
      target: api_get_users
      type: calls

    - source: page_users
      target: component_user_list
      type: renders

  dependency_chains:
    page_users: [api_get_users, model_user, component_user_list, component_user_card]

  impact_chains:
    model_user: [api_get_users, api_create_user, page_users, component_user_list]

  type_mappings:
    model_user:
      id: uuid
      email: string
      name: string
    api_get_users:
      users: Array<User>
    component_user_card:
      user: User

  issues:
    circular_dependencies: []

  statistics:
    total_entities: 4
    total_relations: 3
    by_type:
      database: 1
      api: 1
      component: 1
      page: 1