Skip to content

Commit a54c749

Browse files
lobanovkirilllobanovkirill
committed
docs: added context and documentation files for helping LLM understanding Cycle ORM architecture
1 parent 78009d9 commit a54c749

10 files changed

Lines changed: 500 additions & 0 deletions

‎context.yaml‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Cycle ORM Context Configuration
2+
# Main configuration file with project overview and references to detailed component documentation
3+
4+
# Cycle ORM is a powerful PHP Object-Relational Mapping (ORM) library that provides a comprehensive
5+
# solution for database interactions with a focus on performance, flexibility, and developer experience.
6+
7+
import:
8+
- path: context/core-architecture.yaml
9+
description: Core interfaces and architectural contracts that define the ORM foundation
10+
- path: context/entity-management.yaml
11+
description: Entity lifecycle management, heap system, and ORM facade
12+
- path: context/mapping-system.yaml
13+
description: Data mapping, typecasting, proxy generation, and entity hydration
14+
- path: context/relation-system.yaml
15+
description: Complete relationship system including all relation types and references
16+
- path: context/query-system.yaml
17+
description: Query building, data loading strategies, and repository pattern
18+
- path: context/transaction-system.yaml
19+
description: Transaction management, command pattern, and Unit of Work implementation
20+
- path: context/collections-and-factory.yaml
21+
description: Collection management and dependency injection container system
22+
- path: context/schema-and-config.yaml
23+
description: Schema definitions, configuration management, and supporting utilities
24+
- path: context/traits-and-utilities.yaml
25+
description: Shared traits and utility components used across the ORM system
26+
27+
documents:
28+
- description: Cycle ORM project overview with complete architecture summary
29+
outputPath: project/overview.md
30+
sources:
31+
- type: text
32+
content: |
33+
# Cycle ORM - Project Overview
34+
35+
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.
36+
37+
## Key Features
38+
- **Entity Management**: Complete entity lifecycle management with heap-based tracking
39+
- **Flexible Relations**: Support for all relationship types including polymorphic relations
40+
- **Query Builder**: Powerful and flexible query building capabilities
41+
- **Transaction Management**: Robust transaction handling with Unit of Work pattern
42+
- **Collection Support**: Multiple collection implementations (Doctrine, Laravel, etc.)
43+
- **Lazy Loading**: Efficient lazy loading with proxy objects
44+
- **Schema Management**: Comprehensive schema definition and management
45+
46+
## Architecture Principles
47+
- **Interface-Driven Design**: Heavy use of interfaces for flexibility and testability
48+
- **Dependency Injection**: Built-in factory and DI container system
49+
- **Command Pattern**: Database operations handled through command objects
50+
- **Repository Pattern**: Clean data access layer abstraction
51+
- **Heap Pattern**: Efficient entity tracking and identity management
52+
53+
## Component Documentation
54+
55+
This project is organized into several functional components, each documented separately:
56+
57+
- **Core Architecture**: Fundamental interfaces and contracts ([core-architecture.md](core-architecture.md))
58+
- **Entity Management**: ORM facade and entity lifecycle ([entity-management.md](entity-management.md))
59+
- **Data Mapping**: Mappers, typecasting, and hydration ([mapping-system.md](mapping-system.md))
60+
- **Relations**: All relationship types and references ([relation-system.md](relation-system.md))
61+
- **Query System**: Query building and data loading ([query-system.md](query-system.md))
62+
- **Transactions**: Command pattern and persistence ([transaction-system.md](transaction-system.md))
63+
- **Collections**: Collection management and DI ([collections-and-factory.md](collections-and-factory.md))
64+
- **Schema**: Configuration and metadata ([schema-and-config.md](schema-and-config.md))
65+
- **Utilities**: Shared traits and helpers ([traits-and-utilities.md](traits-and-utilities.md))
66+
67+
- type: tree
68+
description: Complete project structure with component descriptions
69+
sourcePaths: src
70+
maxDepth: 3
71+
includeFiles: true
72+
showSize: true
73+
dirContext:
74+
src/Collection: "Collection management and factory implementations"
75+
src/Command: "Command pattern for database operations"
76+
src/Exception: "Exception hierarchy for error handling"
77+
src/Heap: "Entity tracking and identity management"
78+
src/Mapper: "Data mapping and entity hydration"
79+
src/Parser: "Data parsing and typecasting"
80+
src/Relation: "Entity relationship implementations"
81+
src/Reference: "Lazy loading and reference management"
82+
src/Select: "Query building and data loading"
83+
src/Service: "Service layer implementations"
84+
src/Transaction: "Transaction management and Unit of Work"

‎context/collections-and-factory.yaml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Collections and Factory System - Collection Management and DI Container
2+
# This covers collection factories, pivoted collections, and the main factory/DI system
3+
4+
documents:
5+
- description: Collection management and factory system for dependency injection and object creation
6+
outputPath: project/collections-and-factory.md
7+
sources:
8+
- type: text
9+
content: |
10+
# Collections and Factory System
11+
12+
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.
13+
14+
- type: file
15+
description: Main factory and DI container
16+
sourcePaths: src
17+
filePattern: "Factory.php"
18+
19+
- type: file
20+
description: Collection factory implementations
21+
sourcePaths: src/Collection
22+
filePattern: "*.php"
23+
notPath:
24+
- src/Collection/Pivoted/
25+
26+
- type: file
27+
description: Pivoted collection system for many-to-many relationships
28+
sourcePaths: src/Collection/Pivoted
29+
filePattern: "*.php"
30+
31+
- type: tree
32+
description: Collections and factory structure
33+
sourcePaths: src/Collection
34+
maxDepth: 2
35+
includeFiles: true

‎context/core-architecture.yaml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Core Architecture - Interfaces and Contracts
2+
# This document covers the fundamental interfaces and contracts that define the ORM architecture
3+
4+
documents:
5+
- description: Core ORM interfaces and base contracts that define the architecture
6+
outputPath: project/core-architecture.md
7+
sources:
8+
- type: text
9+
content: |
10+
# Cycle ORM - Core Architecture
11+
12+
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.
13+
14+
- type: file
15+
description: Core interfaces and base classes
16+
sourcePaths: src
17+
filePattern:
18+
- "*Interface.php"
19+
path:
20+
- src/*Interface.php
21+
- src/*/
22+
notPath:
23+
- src/Exception/
24+
- src/Parser/Traits/
25+
- src/Command/Traits/
26+
- src/Heap/Traits/
27+
- src/Mapper/Traits/
28+
- src/Relation/Traits/
29+
- src/Select/Traits/
30+
31+
- type: file
32+
description: Abstract base classes that implement core patterns
33+
sourcePaths: src
34+
filePattern: "Abstract*.php"
35+
path:
36+
- src/Parser/Abstract*.php
37+
- src/Relation/Abstract*.php
38+
- src/Select/Abstract*.php
39+
40+
- type: tree
41+
description: Core architecture overview
42+
sourcePaths: src
43+
filePattern: "*Interface.php"
44+
maxDepth: 2
45+
includeFiles: true
46+
showSize: false

‎context/entity-management.yaml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Entity Management - ORM Core, Heap, and Entity Factory
2+
# This covers entity lifecycle management, heap (entity map), and the main ORM facade
3+
4+
documents:
5+
- description: Entity management core - ORM facade, heap, and entity lifecycle
6+
outputPath: project/entity-management.md
7+
sources:
8+
- type: text
9+
content: |
10+
# Entity Management System
11+
12+
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.
13+
14+
- type: file
15+
description: Main ORM class and entity manager
16+
sourcePaths: src
17+
filePattern:
18+
- "ORM.php"
19+
- "EntityManager.php"
20+
21+
- type: file
22+
description: Heap system for entity tracking and caching
23+
sourcePaths: src/Heap
24+
filePattern: "*.php"
25+
notPath:
26+
- src/Heap/Traits/
27+
28+
- type: file
29+
description: Entity factory and service implementations
30+
sourcePaths: src/Service
31+
filePattern: "*.php"
32+
path:
33+
- src/Service/Implementation/
34+
35+
- type: tree
36+
description: Entity management structure
37+
sourcePaths:
38+
- src/Heap
39+
- src/Service
40+
maxDepth: 2
41+
includeFiles: true

‎context/mapping-system.yaml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Data Mapping System - Mappers, Typecasting, and Entity Hydration
2+
# This covers how entities are mapped to/from database records and data transformation
3+
4+
documents:
5+
- description: Data mapping system including mappers, typecasting, and entity hydration
6+
outputPath: project/mapping-system.md
7+
sources:
8+
- type: text
9+
content: |
10+
# Data Mapping System
11+
12+
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.
13+
14+
- type: file
15+
description: Core mapper implementations
16+
sourcePaths: src/Mapper
17+
filePattern: "*.php"
18+
notPath:
19+
- src/Mapper/Proxy/
20+
- src/Mapper/Traits/
21+
22+
- type: file
23+
description: Proxy system for lazy loading and entity decoration
24+
sourcePaths: src/Mapper/Proxy
25+
filePattern: "*.php"
26+
notPath:
27+
- src/Mapper/Proxy/Hydrator/
28+
29+
- type: file
30+
description: Hydration system for efficient entity creation
31+
sourcePaths: src/Mapper/Proxy/Hydrator
32+
filePattern: "*.php"
33+
34+
- type: file
35+
description: Parser and typecasting system
36+
sourcePaths: src/Parser
37+
filePattern: "*.php"
38+
notPath:
39+
- src/Parser/Abstract*.php
40+
- src/Parser/Traits/
41+
42+
- type: tree
43+
description: Mapping system structure
44+
sourcePaths:
45+
- src/Mapper
46+
- src/Parser
47+
maxDepth: 3
48+
includeFiles: true

‎context/query-system.yaml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Query and Selection System - Select, Loaders, and Repository Pattern
2+
# This covers querying, data loading strategies, and repository implementations
3+
4+
documents:
5+
- description: Query and selection system including Select queries, loaders, and repositories
6+
outputPath: project/query-system.md
7+
sources:
8+
- type: text
9+
content: |
10+
# Query and Selection System
11+
12+
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.
13+
14+
- type: file
15+
description: Main Select query builder
16+
sourcePaths: src
17+
filePattern: "Select.php"
18+
19+
- type: file
20+
description: Core selection infrastructure
21+
sourcePaths: src/Select
22+
filePattern: "*.php"
23+
notPath:
24+
- src/Select/Loader/
25+
- src/Select/Traits/
26+
- src/Select/Abstract*.php
27+
28+
- type: file
29+
description: Data loader implementations for various relationship types
30+
sourcePaths: src/Select/Loader
31+
filePattern: "*.php"
32+
notPath:
33+
- src/Select/Loader/Morphed/
34+
35+
- type: file
36+
description: Morphed relationship loaders
37+
sourcePaths: src/Select/Loader/Morphed
38+
filePattern: "*.php"
39+
40+
- type: tree
41+
description: Query system structure
42+
sourcePaths: src/Select
43+
maxDepth: 3
44+
includeFiles: true

‎context/relation-system.yaml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Relation System - Entity Relationships and References
2+
# This covers all types of entity relationships and reference handling
3+
4+
documents:
5+
- description: Complete relation system including all relationship types and reference management
6+
outputPath: project/relation-system.md
7+
sources:
8+
- type: text
9+
content: |
10+
# Relation System
11+
12+
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.
13+
14+
- type: file
15+
description: Core relation classes and relationship map
16+
sourcePaths: src
17+
filePattern:
18+
- "Relation.php"
19+
- "RelationMap.php"
20+
21+
- type: file
22+
description: All relationship implementations
23+
sourcePaths: src/Relation
24+
filePattern: "*.php"
25+
notPath:
26+
- src/Relation/Abstract*.php
27+
- src/Relation/Traits/
28+
- src/Relation/Morphed/
29+
30+
- type: file
31+
description: Morphed (polymorphic) relationships
32+
sourcePaths: src/Relation/Morphed
33+
filePattern: "*.php"
34+
35+
- type: file
36+
description: Reference system for lazy loading
37+
sourcePaths: src/Reference
38+
filePattern: "*.php"
39+
40+
- type: tree
41+
description: Relation system structure
42+
sourcePaths:
43+
- src/Relation
44+
- src/Reference
45+
maxDepth: 2
46+
includeFiles: true

0 commit comments

Comments
 (0)