From a54c749d8edf101f652f347defad96ed23b93655 Mon Sep 17 00:00:00 2001 From: kirill lobanov Date: Sat, 5 Jul 2025 10:55:16 +0500 Subject: [PATCH] docs: added context and documentation files for helping LLM understanding Cycle ORM architecture --- context.yaml | 84 ++++++++++++++++++++++++++++ context/collections-and-factory.yaml | 35 ++++++++++++ context/core-architecture.yaml | 46 +++++++++++++++ context/entity-management.yaml | 41 ++++++++++++++ context/mapping-system.yaml | 48 ++++++++++++++++ context/query-system.yaml | 44 +++++++++++++++ context/relation-system.yaml | 46 +++++++++++++++ context/schema-and-config.yaml | 55 ++++++++++++++++++ context/traits-and-utilities.yaml | 51 +++++++++++++++++ context/transaction-system.yaml | 50 +++++++++++++++++ 10 files changed, 500 insertions(+) create mode 100644 context.yaml create mode 100644 context/collections-and-factory.yaml create mode 100644 context/core-architecture.yaml create mode 100644 context/entity-management.yaml create mode 100644 context/mapping-system.yaml create mode 100644 context/query-system.yaml create mode 100644 context/relation-system.yaml create mode 100644 context/schema-and-config.yaml create mode 100644 context/traits-and-utilities.yaml create mode 100644 context/transaction-system.yaml diff --git a/context.yaml b/context.yaml new file mode 100644 index 00000000..ccc238c5 --- /dev/null +++ b/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" diff --git a/context/collections-and-factory.yaml b/context/collections-and-factory.yaml new file mode 100644 index 00000000..b371e52f --- /dev/null +++ b/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 diff --git a/context/core-architecture.yaml b/context/core-architecture.yaml new file mode 100644 index 00000000..b28830d8 --- /dev/null +++ b/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 diff --git a/context/entity-management.yaml b/context/entity-management.yaml new file mode 100644 index 00000000..cc1c2f98 --- /dev/null +++ b/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 diff --git a/context/mapping-system.yaml b/context/mapping-system.yaml new file mode 100644 index 00000000..359f0e89 --- /dev/null +++ b/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 diff --git a/context/query-system.yaml b/context/query-system.yaml new file mode 100644 index 00000000..0c921ee7 --- /dev/null +++ b/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 diff --git a/context/relation-system.yaml b/context/relation-system.yaml new file mode 100644 index 00000000..359b2093 --- /dev/null +++ b/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 diff --git a/context/schema-and-config.yaml b/context/schema-and-config.yaml new file mode 100644 index 00000000..cbe9cfc2 --- /dev/null +++ b/context/schema-and-config.yaml @@ -0,0 +1,55 @@ +# Schema and Configuration System - Metadata and Configuration Management +# This covers schema definitions, configuration, and supporting utilities + +documents: + - description: Schema definition and configuration management system + outputPath: project/schema-and-config.md + sources: + - type: text + content: | + # Schema and Configuration System + + This document covers the schema definition and configuration system in Cycle ORM, including entity schema management, configuration classes, exception handling, and supporting utilities like iterators and options. + + - type: file + description: Core schema implementation + sourcePaths: src + filePattern: "Schema.php" + + - type: file + description: Schema-related classes and generated field definitions + sourcePaths: src/Schema + filePattern: "*.php" + + - type: file + description: Configuration management + sourcePaths: src/Config + filePattern: "*.php" + + - type: file + description: Exception hierarchy + sourcePaths: src/Exception + filePattern: "*.php" + notPath: + - src/Exception/Relation/ + + - type: file + description: Relation-specific exceptions + sourcePaths: src/Exception/Relation + filePattern: "*.php" + + - type: file + description: Supporting utilities + sourcePaths: src + filePattern: + - "Iterator.php" + - "Options.php" + + - type: tree + description: Schema and configuration structure + sourcePaths: + - src/Schema + - src/Config + - src/Exception + maxDepth: 2 + includeFiles: true diff --git a/context/traits-and-utilities.yaml b/context/traits-and-utilities.yaml new file mode 100644 index 00000000..43f94f0b --- /dev/null +++ b/context/traits-and-utilities.yaml @@ -0,0 +1,51 @@ +# Traits and Utility Components - Shared Functionality and Helpers +# This covers all trait implementations and shared utility components + +documents: + - description: Shared traits and utility components used across the ORM system + outputPath: project/traits-and-utilities.md + sources: + - type: text + content: | + # Traits and Utility Components + + This document covers all the shared traits and utility components used throughout Cycle ORM, including reusable functionality for parsing, commands, heap management, mapping, relations, and query building. + + - type: file + description: Parser-related traits + sourcePaths: src/Parser/Traits + filePattern: "*.php" + + - type: file + description: Command-related traits + sourcePaths: src/Command/Traits + filePattern: "*.php" + + - type: file + description: Heap management traits + sourcePaths: src/Heap/Traits + filePattern: "*.php" + + - type: file + description: Mapper-related traits + sourcePaths: src/Mapper/Traits + filePattern: "*.php" + + - type: file + description: Relation-related traits + sourcePaths: src/Relation/Traits + filePattern: "*.php" + + - type: file + description: Select and query-related traits + sourcePaths: src/Select/Traits + filePattern: "*.php" + + - type: tree + description: Traits structure across the system + sourcePaths: src + filePattern: "*.php" + path: + - src/*/Traits/ + maxDepth: 3 + includeFiles: true diff --git a/context/transaction-system.yaml b/context/transaction-system.yaml new file mode 100644 index 00000000..99c921be --- /dev/null +++ b/context/transaction-system.yaml @@ -0,0 +1,50 @@ +# Transaction and Command System - Persistence and Unit of Work +# This covers transaction management, command pattern, and persistence operations + +documents: + - description: Transaction and command system for managing persistence operations + outputPath: project/transaction-system.md + sources: + - type: text + content: | + # Transaction and Command System + + This document covers the transaction management and command system in Cycle ORM, including the Unit of Work pattern, command generation and execution, database commands, and transaction state management. + + - type: file + description: Transaction management and legacy interface + sourcePaths: src + filePattern: + - "Transaction.php" + + - type: file + description: Core transaction system components + sourcePaths: src/Transaction + filePattern: "*.php" + + - type: file + description: Command interfaces and base implementations + sourcePaths: src/Command + filePattern: "*.php" + notPath: + - src/Command/Database/ + - src/Command/Special/ + - src/Command/Traits/ + + - type: file + description: Database-specific command implementations + sourcePaths: src/Command/Database + filePattern: "*.php" + + - type: file + description: Special command types and wrappers + sourcePaths: src/Command/Special + filePattern: "*.php" + + - type: tree + description: Transaction system structure + sourcePaths: + - src/Transaction + - src/Command + maxDepth: 2 + includeFiles: true