371 lines
10 KiB
YAML
371 lines
10 KiB
YAML
# 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
|