docs: added context and documentation files for helping LLM understanding Cycle ORM architecture

context.yaml

@@ -0,0 +1,84 @@
+# Cycle ORM Context Configuration
+# Main configuration file with project overview and references to detailed component documentation
+
+# Cycle ORM is a powerful PHP Object-Relational Mapping (ORM) library that provides a comprehensive
+# solution for database interactions with a focus on performance, flexibility, and developer experience.
+
+import:
+  - path: context/core-architecture.yaml
+    description: Core interfaces and architectural contracts that define the ORM foundation
+  - path: context/entity-management.yaml
+    description: Entity lifecycle management, heap system, and ORM facade
+  - path: context/mapping-system.yaml
+    description: Data mapping, typecasting, proxy generation, and entity hydration
+  - path: context/relation-system.yaml
+    description: Complete relationship system including all relation types and references
+  - path: context/query-system.yaml
+    description: Query building, data loading strategies, and repository pattern
+  - path: context/transaction-system.yaml
+    description: Transaction management, command pattern, and Unit of Work implementation
+  - path: context/collections-and-factory.yaml
+    description: Collection management and dependency injection container system
+  - path: context/schema-and-config.yaml
+    description: Schema definitions, configuration management, and supporting utilities
+  - path: context/traits-and-utilities.yaml
+    description: Shared traits and utility components used across the ORM system
+
+documents:
+  - description: Cycle ORM project overview with complete architecture summary
+    outputPath: project/overview.md
+    sources:
+      - type: text
+        content: |
+          # Cycle ORM - Project Overview
+
+          Cycle ORM is a powerful PHP Object-Relational Mapping (ORM) library that provides a comprehensive solution for database interactions with a focus on performance, flexibility, and developer experience.
+
+          ## Key Features
+          - **Entity Management**: Complete entity lifecycle management with heap-based tracking
+          - **Flexible Relations**: Support for all relationship types including polymorphic relations
+          - **Query Builder**: Powerful and flexible query building capabilities
+          - **Transaction Management**: Robust transaction handling with Unit of Work pattern
+          - **Collection Support**: Multiple collection implementations (Doctrine, Laravel, etc.)
+          - **Lazy Loading**: Efficient lazy loading with proxy objects
+          - **Schema Management**: Comprehensive schema definition and management
+
+          ## Architecture Principles
+          - **Interface-Driven Design**: Heavy use of interfaces for flexibility and testability
+          - **Dependency Injection**: Built-in factory and DI container system
+          - **Command Pattern**: Database operations handled through command objects
+          - **Repository Pattern**: Clean data access layer abstraction
+          - **Heap Pattern**: Efficient entity tracking and identity management
+
+          ## Component Documentation
+
+          This project is organized into several functional components, each documented separately:
+
+          - **Core Architecture**: Fundamental interfaces and contracts ([core-architecture.md](core-architecture.md))
+          - **Entity Management**: ORM facade and entity lifecycle ([entity-management.md](entity-management.md))
+          - **Data Mapping**: Mappers, typecasting, and hydration ([mapping-system.md](mapping-system.md))
+          - **Relations**: All relationship types and references ([relation-system.md](relation-system.md))
+          - **Query System**: Query building and data loading ([query-system.md](query-system.md))
+          - **Transactions**: Command pattern and persistence ([transaction-system.md](transaction-system.md))
+          - **Collections**: Collection management and DI ([collections-and-factory.md](collections-and-factory.md))
+          - **Schema**: Configuration and metadata ([schema-and-config.md](schema-and-config.md))
+          - **Utilities**: Shared traits and helpers ([traits-and-utilities.md](traits-and-utilities.md))
+
+      - type: tree
+        description: Complete project structure with component descriptions
+        sourcePaths: src
+        maxDepth: 3
+        includeFiles: true
+        showSize: true
+        dirContext:
+          src/Collection: "Collection management and factory implementations"
+          src/Command: "Command pattern for database operations"
+          src/Exception: "Exception hierarchy for error handling"
+          src/Heap: "Entity tracking and identity management"
+          src/Mapper: "Data mapping and entity hydration"
+          src/Parser: "Data parsing and typecasting"
+          src/Relation: "Entity relationship implementations"
+          src/Reference: "Lazy loading and reference management"
+          src/Select: "Query building and data loading"
+          src/Service: "Service layer implementations"
+          src/Transaction: "Transaction management and Unit of Work"

context/collections-and-factory.yaml

@@ -0,0 +1,35 @@
+# Collections and Factory System - Collection Management and DI Container
+# This covers collection factories, pivoted collections, and the main factory/DI system
+
+documents:
+  - description: Collection management and factory system for dependency injection and object creation
+    outputPath: project/collections-and-factory.md
+    sources:
+      - type: text
+        content: |
+          # Collections and Factory System
+
+          This document covers the collection management system and factory/DI container in Cycle ORM, including various collection implementations, pivoted collections for many-to-many relationships, and the main factory system for object creation and dependency injection.
+
+      - type: file
+        description: Main factory and DI container
+        sourcePaths: src
+        filePattern: "Factory.php"
+
+      - type: file
+        description: Collection factory implementations
+        sourcePaths: src/Collection
+        filePattern: "*.php"
+        notPath:
+          - src/Collection/Pivoted/
+
+      - type: file
+        description: Pivoted collection system for many-to-many relationships
+        sourcePaths: src/Collection/Pivoted
+        filePattern: "*.php"
+
+      - type: tree
+        description: Collections and factory structure
+        sourcePaths: src/Collection
+        maxDepth: 2
+        includeFiles: true

context/core-architecture.yaml

@@ -0,0 +1,46 @@
+# Core Architecture - Interfaces and Contracts
+# This document covers the fundamental interfaces and contracts that define the ORM architecture
+
+documents:
+  - description: Core ORM interfaces and base contracts that define the architecture
+    outputPath: project/core-architecture.md
+    sources:
+      - type: text
+        content: |
+          # Cycle ORM - Core Architecture
+
+          This document provides an overview of the core interfaces and architectural contracts that define how Cycle ORM operates. These interfaces establish the foundation for all ORM functionality including entity management, data mapping, querying, and transactions.
+
+      - type: file
+        description: Core interfaces and base classes
+        sourcePaths: src
+        filePattern:
+          - "*Interface.php"
+        path:
+          - src/*Interface.php
+          - src/*/
+        notPath:
+          - src/Exception/
+          - src/Parser/Traits/
+          - src/Command/Traits/
+          - src/Heap/Traits/
+          - src/Mapper/Traits/
+          - src/Relation/Traits/
+          - src/Select/Traits/
+
+      - type: file
+        description: Abstract base classes that implement core patterns
+        sourcePaths: src
+        filePattern: "Abstract*.php"
+        path:
+          - src/Parser/Abstract*.php
+          - src/Relation/Abstract*.php
+          - src/Select/Abstract*.php
+
+      - type: tree
+        description: Core architecture overview
+        sourcePaths: src
+        filePattern: "*Interface.php"
+        maxDepth: 2
+        includeFiles: true
+        showSize: false

context/entity-management.yaml

@@ -0,0 +1,41 @@
+# Entity Management - ORM Core, Heap, and Entity Factory
+# This covers entity lifecycle management, heap (entity map), and the main ORM facade
+
+documents:
+  - description: Entity management core - ORM facade, heap, and entity lifecycle
+    outputPath: project/entity-management.md
+    sources:
+      - type: text
+        content: |
+          # Entity Management System
+
+          This document covers the core entity management system in Cycle ORM, including the main ORM facade, heap (entity map) for tracking loaded entities, and the complete entity lifecycle from creation to persistence.
+
+      - type: file
+        description: Main ORM class and entity manager
+        sourcePaths: src
+        filePattern:
+          - "ORM.php"
+          - "EntityManager.php"
+
+      - type: file
+        description: Heap system for entity tracking and caching
+        sourcePaths: src/Heap
+        filePattern: "*.php"
+        notPath:
+          - src/Heap/Traits/
+
+      - type: file
+        description: Entity factory and service implementations
+        sourcePaths: src/Service
+        filePattern: "*.php"
+        path:
+          - src/Service/Implementation/
+
+      - type: tree
+        description: Entity management structure
+        sourcePaths:
+          - src/Heap
+          - src/Service
+        maxDepth: 2
+        includeFiles: true

context/mapping-system.yaml

@@ -0,0 +1,48 @@
+# Data Mapping System - Mappers, Typecasting, and Entity Hydration
+# This covers how entities are mapped to/from database records and data transformation
+
+documents:
+  - description: Data mapping system including mappers, typecasting, and entity hydration
+    outputPath: project/mapping-system.md
+    sources:
+      - type: text
+        content: |
+          # Data Mapping System
+
+          This document covers the data mapping layer of Cycle ORM, including how entities are converted to/from database records, typecasting mechanisms, proxy generation, and entity hydration strategies.
+
+      - type: file
+        description: Core mapper implementations
+        sourcePaths: src/Mapper
+        filePattern: "*.php"
+        notPath:
+          - src/Mapper/Proxy/
+          - src/Mapper/Traits/
+
+      - type: file
+        description: Proxy system for lazy loading and entity decoration
+        sourcePaths: src/Mapper/Proxy
+        filePattern: "*.php"
+        notPath:
+          - src/Mapper/Proxy/Hydrator/
+
+      - type: file
+        description: Hydration system for efficient entity creation
+        sourcePaths: src/Mapper/Proxy/Hydrator
+        filePattern: "*.php"
+
+      - type: file
+        description: Parser and typecasting system
+        sourcePaths: src/Parser
+        filePattern: "*.php"
+        notPath:
+          - src/Parser/Abstract*.php
+          - src/Parser/Traits/
+
+      - type: tree
+        description: Mapping system structure
+        sourcePaths:
+          - src/Mapper
+          - src/Parser
+        maxDepth: 3
+        includeFiles: true

context/query-system.yaml

@@ -0,0 +1,44 @@
+# Query and Selection System - Select, Loaders, and Repository Pattern
+# This covers querying, data loading strategies, and repository implementations
+
+documents:
+  - description: Query and selection system including Select queries, loaders, and repositories
+    outputPath: project/query-system.md
+    sources:
+      - type: text
+        content: |
+          # Query and Selection System
+
+          This document covers the query and data selection system in Cycle ORM, including the Select query builder, various data loaders for efficient loading strategies, repository pattern implementations, and query scoping mechanisms.
+
+      - type: file
+        description: Main Select query builder
+        sourcePaths: src
+        filePattern: "Select.php"
+
+      - type: file
+        description: Core selection infrastructure
+        sourcePaths: src/Select
+        filePattern: "*.php"
+        notPath:
+          - src/Select/Loader/
+          - src/Select/Traits/
+          - src/Select/Abstract*.php
+
+      - type: file
+        description: Data loader implementations for various relationship types
+        sourcePaths: src/Select/Loader
+        filePattern: "*.php"
+        notPath:
+          - src/Select/Loader/Morphed/
+
+      - type: file
+        description: Morphed relationship loaders
+        sourcePaths: src/Select/Loader/Morphed
+        filePattern: "*.php"
+
+      - type: tree
+        description: Query system structure
+        sourcePaths: src/Select
+        maxDepth: 3
+        includeFiles: true

context/relation-system.yaml

@@ -0,0 +1,46 @@
+# Relation System - Entity Relationships and References
+# This covers all types of entity relationships and reference handling
+
+documents:
+  - description: Complete relation system including all relationship types and reference management
+    outputPath: project/relation-system.md
+    sources:
+      - type: text
+        content: |
+          # Relation System
+
+          This document covers the comprehensive relationship system in Cycle ORM, including all relationship types (HasOne, HasMany, BelongsTo, ManyToMany, etc.), morphed relationships, embedded objects, and reference management.
+
+      - type: file
+        description: Core relation classes and relationship map
+        sourcePaths: src
+        filePattern:
+          - "Relation.php"
+          - "RelationMap.php"
+
+      - type: file
+        description: All relationship implementations
+        sourcePaths: src/Relation
+        filePattern: "*.php"
+        notPath:
+          - src/Relation/Abstract*.php
+          - src/Relation/Traits/
+          - src/Relation/Morphed/
+
+      - type: file
+        description: Morphed (polymorphic) relationships
+        sourcePaths: src/Relation/Morphed
+        filePattern: "*.php"
+
+      - type: file
+        description: Reference system for lazy loading
+        sourcePaths: src/Reference
+        filePattern: "*.php"
+
+      - type: tree
+        description: Relation system structure
+        sourcePaths:
+          - src/Relation
+          - src/Reference
+        maxDepth: 2
+        includeFiles: true