From 9877ddf5ecc534e2cc6d693c0d3d2f00bc82263c Mon Sep 17 00:00:00 2001 From: anonpenguin Date: Sun, 6 Jul 2025 06:56:39 +0300 Subject: [PATCH] docs: Add development guidelines, project overview, and technical reference documentation --- .claude/development-guidelines.md | 391 +++++++++++++++++++ .claude/project-overview.md | 249 ++++++++++++ .claude/technical-reference.md | 607 ++++++++++++++++++++++++++++++ 3 files changed, 1247 insertions(+) create mode 100644 .claude/development-guidelines.md create mode 100644 .claude/project-overview.md create mode 100644 .claude/technical-reference.md diff --git a/.claude/development-guidelines.md b/.claude/development-guidelines.md new file mode 100644 index 0000000..3c21512 --- /dev/null +++ b/.claude/development-guidelines.md @@ -0,0 +1,391 @@ +# DebrosFramework Development Guidelines + +## Code Style and Standards + +### TypeScript Configuration +- **Strict Mode**: Always use strict TypeScript configuration +- **Decorators**: Enable `experimentalDecorators` and `emitDecoratorMetadata` +- **Target**: ES2020 for modern JavaScript features +- **Module System**: ES modules with CommonJS interop + +### Code Formatting +- **Prettier**: Use Prettier for consistent code formatting +- **ESLint**: Follow ESLint rules for code quality +- **Indentation**: 2 spaces for all files +- **Line Length**: Max 120 characters per line +- **Semicolons**: Always use semicolons +- **Quotes**: Single quotes for strings, double quotes for JSX + +### Naming Conventions +- **Classes**: PascalCase (e.g., `UserModel`, `QueryBuilder`) +- **Functions/Methods**: camelCase (e.g., `createUser`, `findById`) +- **Variables**: camelCase (e.g., `userId`, `queryResult`) +- **Constants**: UPPER_SNAKE_CASE (e.g., `DEFAULT_CACHE_SIZE`) +- **Files**: PascalCase for classes, camelCase for utilities +- **Interfaces**: PascalCase with descriptive names (e.g., `ModelConfig`) + +## Framework Architecture Patterns + +### Model System +```typescript +// Always extend BaseModel for data models +@Model({ + scope: 'user' | 'global', + type: 'docstore', + sharding: { strategy: 'hash', count: 4, key: 'fieldName' } +}) +export class ModelName extends BaseModel { + @Field({ type: 'string', required: true }) + propertyName: string; + + @BelongsTo(() => RelatedModel, 'foreignKey') + relation: RelatedModel; +} +``` + +### Query Patterns +```typescript +// Use chainable query builder pattern +const results = await Model.query() + .where('field', 'operator', value) + .with(['relationship1', 'relationship2']) + .orderBy('field', 'direction') + .limit(count) + .find(); + +// Prefer specific methods over generic ones +const user = await User.findById(id); // Good +const user = await User.query().where('id', id).findOne(); // Less preferred +``` + +### Error Handling +```typescript +// Always use try-catch for async operations +try { + const result = await someAsyncOperation(); + return result; +} catch (error) { + console.error('Operation failed:', error); + throw new DebrosFrameworkError('Descriptive error message', { originalError: error }); +} + +// Validate inputs early +if (!userId || typeof userId !== 'string') { + throw new ValidationError('User ID must be a non-empty string'); +} +``` + +### Service Layer Pattern +```typescript +// Encapsulate business logic in service classes +export class UserService { + async createUser(userData: CreateUserData): Promise { + // Validation + await this.validateUserData(userData); + + // Business logic + const user = await User.create(userData); + + // Post-processing + await this.sendWelcomeEmail(user); + + return user; + } + + private async validateUserData(data: CreateUserData): Promise { + // Validation logic + } +} +``` + +## Testing Standards + +### Unit Tests +- **Jest**: Use Jest for all unit testing +- **Mocking**: Mock external dependencies (OrbitDB, IPFS) +- **Coverage**: Aim for >90% code coverage +- **Structure**: One test file per source file +- **Naming**: `*.test.ts` for test files + +```typescript +describe('ModelName', () => { + let model: ModelName; + + beforeEach(() => { + model = new ModelName(); + }); + + describe('methodName', () => { + it('should handle normal case', async () => { + // Arrange + const input = 'test value'; + + // Act + const result = await model.methodName(input); + + // Assert + expect(result).toBeDefined(); + expect(result.property).toBe('expected value'); + }); + + it('should throw error for invalid input', async () => { + // Arrange & Act & Assert + await expect(model.methodName(null)).rejects.toThrow('Expected error message'); + }); + }); +}); +``` + +### Integration Tests +- **Docker**: Use Docker for real integration tests +- **Scenarios**: Test complete user workflows +- **Data**: Use realistic test data +- **Cleanup**: Always clean up test data + +## Performance Guidelines + +### Query Optimization +```typescript +// Use selective field loading when possible +const users = await User.query().select(['id', 'username']).find(); + +// Prefer eager loading for predictable relationships +const posts = await Post.query().with(['author', 'comments']).find(); + +// Use caching for expensive queries +const popularPosts = await Post.query() + .where('likeCount', '>', 100) + .cache(300) // Cache for 5 minutes + .find(); +``` + +### Memory Management +- **Lazy Loading**: Use lazy loading for large datasets +- **Pagination**: Always use pagination for large result sets +- **Cache Limits**: Set appropriate cache size limits +- **Cleanup**: Clean up resources in finally blocks + +### Database Design +- **Sharding**: Design effective sharding strategies +- **Indexing**: Use indexes for frequently queried fields +- **Relationships**: Avoid deep relationship chains +- **Data Types**: Use appropriate data types for storage efficiency + +## Security Considerations + +### Input Validation +```typescript +// Always validate and sanitize inputs +@Field({ + type: 'string', + required: true, + validate: (value: string) => value.length >= 3 && value.length <= 50, + transform: (value: string) => value.trim().toLowerCase() +}) +username: string; +``` + +### Access Control +- **User Scoping**: Use user-scoped models for private data +- **Validation**: Validate user permissions before operations +- **Sanitization**: Sanitize all user inputs +- **Encryption**: Use encryption for sensitive data + +### Error Messages +- **Security**: Don't expose internal system details in error messages +- **Logging**: Log security-relevant events +- **Validation**: Provide clear validation error messages + +## Documentation Standards + +### Code Documentation +```typescript +/** + * Creates a new user with the provided data. + * + * @param userData - The user data to create + * @param options - Additional creation options + * @returns Promise resolving to the created user + * @throws ValidationError if user data is invalid + * @throws DuplicateError if username or email already exists + * + * @example + * ```typescript + * const user = await userService.createUser({ + * username: 'alice', + * email: 'alice@example.com' + * }); + * ``` + */ +async createUser(userData: CreateUserData, options?: CreateOptions): Promise { + // Implementation +} +``` + +### README Updates +- Keep README.md up to date with latest features +- Include practical examples +- Document breaking changes +- Provide migration guides + +### API Documentation +- Document all public APIs +- Include parameter types and return types +- Provide usage examples +- Document error conditions + +## Common Patterns and Anti-Patterns + +### ✅ Good Patterns + +#### Model Definition +```typescript +@Model({ + scope: 'user', + type: 'docstore', + sharding: { strategy: 'hash', count: 4, key: 'userId' } +}) +export class Post extends BaseModel { + @Field({ type: 'string', required: true, maxLength: 200 }) + title: string; + + @Field({ type: 'string', required: true }) + content: string; + + @BeforeCreate() + setDefaults() { + this.createdAt = Date.now(); + this.updatedAt = Date.now(); + } +} +``` + +#### Service Methods +```typescript +async createPost(authorId: string, postData: CreatePostData): Promise { + // Validate input + if (!authorId) throw new ValidationError('Author ID is required'); + + // Check permissions + const author = await User.findById(authorId); + if (!author) throw new NotFoundError('Author not found'); + + // Create post + const post = await Post.create({ + ...postData, + authorId, + }); + + // Post-processing + await this.notifyFollowers(author, post); + + return post; +} +``` + +### ❌ Anti-Patterns + +#### Avoid Direct Database Access +```typescript +// Bad: Direct database manipulation +const db = await orbitdb.open('posts'); +await db.put('key', data); + +// Good: Use model methods +const post = await Post.create(data); +``` + +#### Avoid Synchronous Operations +```typescript +// Bad: Synchronous file operations +const data = fs.readFileSync('file.json'); + +// Good: Async operations +const data = await fs.promises.readFile('file.json'); +``` + +#### Avoid Deep Relationship Chains +```typescript +// Bad: Deep relationship loading +const posts = await Post.query() + .with(['author.profile.settings.preferences']) + .find(); + +// Good: Load only what you need +const posts = await Post.query() + .with(['author']) + .find(); +``` + +## Migration Guidelines + +### Schema Changes +```typescript +// Create migration for schema changes +const migration = createMigration('add_user_avatar', '1.1.0') + .addField('User', 'avatarUrl', { + type: 'string', + required: false + }) + .transformData('User', (user) => ({ + ...user, + avatarUrl: user.avatarUrl || null + })) + .build(); +``` + +### Backwards Compatibility +- Always maintain backwards compatibility in minor versions +- Deprecate features before removing them +- Provide migration paths for breaking changes +- Document all changes in CHANGELOG.md + +## Deployment Considerations + +### Environment Configuration +- Use environment variables for configuration +- Provide default configurations for development +- Validate configuration on startup +- Document required environment variables + +### Production Readiness +- Enable production optimizations +- Configure appropriate cache sizes +- Set up monitoring and logging +- Implement health checks + +### Performance Monitoring +- Monitor query performance +- Track cache hit rates +- Monitor memory usage +- Set up alerts for errors + +## Contributing Guidelines + +### Pull Request Process +1. Fork the repository +2. Create feature branch from main +3. Implement changes with tests +4. Update documentation +5. Submit pull request with description + +### Code Review Checklist +- [ ] Code follows style guidelines +- [ ] Tests are included and passing +- [ ] Documentation is updated +- [ ] No breaking changes (or properly documented) +- [ ] Performance implications considered +- [ ] Security implications reviewed + +### Commit Message Format +``` +type(scope): description + +body (optional) + +footer (optional) +``` + +Types: feat, fix, docs, style, refactor, test, chore + +These guidelines ensure consistent, maintainable, and high-quality code throughout the DebrosFramework project. diff --git a/.claude/project-overview.md b/.claude/project-overview.md new file mode 100644 index 0000000..b6fb281 --- /dev/null +++ b/.claude/project-overview.md @@ -0,0 +1,249 @@ +# DebrosFramework Project Overview + +## Project Identity +**DebrosFramework** is a powerful Node.js framework that provides an ORM-like abstraction over OrbitDB and IPFS, making it easy to build scalable decentralized applications. + +- **Package Name**: `@debros/network` +- **Version**: 0.5.1-beta (Active Development) +- **License**: GNU GPL v3.0 +- **Language**: TypeScript +- **Framework Type**: Decentralized Application Framework + +## What This Project Does + +DebrosFramework simplifies the development of decentralized applications by providing: + +### Core Capabilities +- **Model-based Abstraction**: Define data models using decorators and TypeScript classes +- **Automatic Database Management**: Handle user-scoped and global databases automatically +- **Smart Sharding**: Distribute data across multiple databases for scalability +- **Advanced Query System**: Rich query capabilities with relationship loading and caching +- **Automatic Features**: Built-in pinning strategies and PubSub event publishing +- **Migration System**: Schema evolution and data transformation capabilities +- **Type Safety**: Full TypeScript support with strong typing throughout + +### Key Features +1. **🏗️ Model-Driven Development**: Familiar decorator patterns for data models +2. **🔍 Powerful Query System**: Complex queries with relationship loading +3. **🚀 Automatic Scaling**: Handle millions of users with automatic sharding +4. **🔄 Schema Evolution**: Safe data structure migrations +5. **🔗 Rich Relationships**: Complex relationships between models +6. **⚡ Performance Features**: Query caching, eager loading, optimized pagination +7. **🎯 Model Hooks**: Lifecycle hooks for business logic + +## Architecture Overview + +The framework is built around several core components: + +1. **Models & Decorators**: Define data structure and behavior +2. **Database Manager**: Handles database creation and management +3. **Shard Manager**: Distributes data across multiple databases +4. **Query System**: Processes queries with optimization and caching +5. **Relationship Manager**: Handles complex relationships between models +6. **Migration System**: Manages schema evolution over time +7. **Automatic Features**: Pinning, PubSub, and performance optimization + +## Technology Stack + +### Core Dependencies +- **OrbitDB**: Distributed peer-to-peer database on IPFS +- **IPFS/Helia**: Distributed file system for data storage +- **libp2p**: Peer-to-peer networking stack +- **TypeScript**: Strong typing and modern JavaScript features + +### Key Libraries +- `@orbitdb/core`: Core OrbitDB functionality +- `@helia/unixfs`: IPFS file system operations +- `@libp2p/*`: Various libp2p modules for networking +- `winston`: Logging +- `node-cache`: In-memory caching +- `express`: HTTP server for integration tests + +## Project Structure + +``` +src/framework/ +├── core/ # Core framework components +│ ├── ConfigManager.ts +│ ├── DatabaseManager.ts +│ └── ModelRegistry.ts +├── models/ # Model system and decorators +│ ├── BaseModel.ts +│ └── decorators/ +├── query/ # Query builder and execution +│ ├── QueryBuilder.ts +│ ├── QueryExecutor.ts +│ ├── QueryOptimizer.ts +│ └── QueryCache.ts +├── relationships/ # Relationship management +│ ├── RelationshipManager.ts +│ ├── LazyLoader.ts +│ └── RelationshipCache.ts +├── sharding/ # Data sharding logic +│ └── ShardManager.ts +├── migrations/ # Schema migration system +│ ├── MigrationManager.ts +│ └── MigrationBuilder.ts +├── pinning/ # Automatic pinning features +│ └── PinningManager.ts +├── pubsub/ # Event publishing system +│ └── PubSubManager.ts +├── services/ # External service integrations +│ ├── OrbitDBService.ts +│ ├── IPFSService.ts +│ └── RealOrbitDBService.ts +└── types/ # TypeScript type definitions + ├── framework.ts + ├── models.ts + └── queries.ts +``` + +## Development Status + +**Current State**: Beta (v0.5.1-beta) - Active Development + +### What's Stable +- ✅ Core model system with decorators +- ✅ Basic CRUD operations +- ✅ Query builder and execution +- ✅ Relationship management +- ✅ Database management and sharding +- ✅ Migration system foundation + +### What's In Development +- 🚧 Advanced query optimization +- 🚧 Performance optimization features +- 🚧 Production-ready configurations +- 🚧 Extended relationship types +- 🚧 Enhanced error handling + +### Testing +- **Unit Tests**: Comprehensive test suite using Jest +- **Integration Tests**: Docker-based real-world scenarios +- **Blog Scenario**: Complete blogging platform test case + +## Key Concepts + +### Model Scoping +- **Global Models**: Shared across all users (e.g., User profiles) +- **User Models**: Each user has their own database instance (e.g., Posts, Comments) + +### Sharding Strategies +- **Hash Sharding**: Distribute data based on key hashing +- **Range Sharding**: Distribute data based on value ranges +- **User Sharding**: Dedicated shards per user or user group + +### Query System +- **Chainable API**: Fluent interface for building queries +- **Type Safety**: Full TypeScript support with auto-completion +- **Relationship Loading**: Eager and lazy loading strategies +- **Caching**: Intelligent query result caching + +### Relationships +- **BelongsTo**: Many-to-one relationships +- **HasMany**: One-to-many relationships +- **HasOne**: One-to-one relationships +- **ManyToMany**: Many-to-many relationships (with through tables) + +## Common Use Cases + +### 1. Social Platforms +- User profiles and authentication +- Posts, comments, and reactions +- Friend networks and messaging +- Activity feeds and notifications + +### 2. Content Management +- Blogs and publishing platforms +- Document management systems +- Media galleries and collections +- Version control for content + +### 3. Collaborative Applications +- Real-time document editing +- Project management tools +- Team collaboration platforms +- Knowledge bases and wikis + +### 4. Marketplace Applications +- Product catalogs and inventory +- User reviews and ratings +- Order management systems +- Payment and transaction records + +## Development Workflow + +### Prerequisites +- Node.js 18.0 or higher +- TypeScript knowledge +- Basic understanding of IPFS and OrbitDB concepts +- Docker (for integration tests) + +### Build Process +```bash +npm run build # Compile TypeScript +npm run dev # Development with watch mode +npm run lint # ESLint code checking +npm run format # Prettier code formatting +``` + +### Testing +```bash +npm run test:unit # Fast unit tests with mocks +npm run test:real # Full integration tests with Docker +npm run test:blog-integration # Blog scenario integration tests +``` + +### Key Development Principles +1. **Type Safety First**: Everything is strongly typed +2. **Decorator-Based**: Use decorators for configuration +3. **Async/Await**: All operations are promise-based +4. **Error Handling**: Comprehensive error management +5. **Performance**: Built-in optimization and caching +6. **Scalability**: Designed for distributed systems + +## API Patterns + +### Model Definition +```typescript +@Model({ + scope: 'user', + type: 'docstore', + sharding: { strategy: 'hash', count: 4, key: 'userId' } +}) +class Post extends BaseModel { + @Field({ type: 'string', required: true }) + title: string; + + @BelongsTo(() => User, 'userId') + user: User; +} +``` + +### Query Operations +```typescript +const posts = await Post.query() + .where('isPublished', true) + .where('createdAt', '>', Date.now() - 7 * 24 * 60 * 60 * 1000) + .with(['user', 'comments']) + .orderBy('likeCount', 'desc') + .limit(20) + .find(); +``` + +### Lifecycle Hooks +```typescript +class User extends BaseModel { + @BeforeCreate() + setupNewUser() { + this.registeredAt = Date.now(); + } + + @AfterCreate() + async sendWelcomeEmail() { + // Business logic after creation + } +} +``` + +This framework makes building decentralized applications feel like traditional web development while providing the benefits of distributed, peer-to-peer systems. diff --git a/.claude/technical-reference.md b/.claude/technical-reference.md new file mode 100644 index 0000000..2d4f84e --- /dev/null +++ b/.claude/technical-reference.md @@ -0,0 +1,607 @@ +# DebrosFramework Technical Reference + +## Core Architecture Components + +### DebrosFramework Main Class +**Location**: `src/framework/DebrosFramework.ts` + +The main framework class that orchestrates all components: + +```typescript +export class DebrosFramework { + // Core services + private orbitDBService: FrameworkOrbitDBService; + private ipfsService: FrameworkIPFSService; + + // Framework components + private databaseManager: DatabaseManager; + private shardManager: ShardManager; + private queryCache: QueryCache; + private relationshipManager: RelationshipManager; + private pinningManager: PinningManager; + private pubsubManager: PubSubManager; + private migrationManager: MigrationManager; + + // Lifecycle methods + async initialize(orbitDBService?, ipfsService?, config?): Promise + async start(): Promise + async stop(): Promise + getStatus(): FrameworkStatus + getMetrics(): FrameworkMetrics +} +``` + +### BaseModel Class +**Location**: `src/framework/models/BaseModel.ts` + +Abstract base class for all data models: + +```typescript +export abstract class BaseModel { + // Instance properties + public id: string; + public _loadedRelations: Map; + protected _isDirty: boolean; + protected _isNew: boolean; + + // Static configuration + static modelName: string; + static storeType: StoreType; + static scope: 'user' | 'global'; + static sharding?: ShardingConfig; + static fields: Map; + static relationships: Map; + + // CRUD operations + async save(): Promise + static async create(data: any): Promise + static async findById(id: string): Promise + static query(): QueryBuilder + async delete(): Promise + + // Lifecycle hooks + async beforeCreate(): Promise + async afterCreate(): Promise + async beforeUpdate(): Promise + async afterUpdate(): Promise + async beforeDelete(): Promise + async afterDelete(): Promise +} +``` + +## Decorator System + +### @Model Decorator +**Location**: `src/framework/models/decorators/Model.ts` + +Configures model behavior and database storage: + +```typescript +interface ModelConfig { + scope: 'user' | 'global'; // Database scope + type: StoreType; // OrbitDB store type + sharding?: ShardingConfig; // Data distribution strategy + pinning?: PinningConfig; // Automatic pinning configuration + pubsub?: PubSubConfig; // Event publishing configuration + validation?: ValidationConfig; // Model-level validation +} + +@Model({ + scope: 'user', + type: 'docstore', + sharding: { strategy: 'hash', count: 4, key: 'userId' } +}) +``` + +### @Field Decorator +**Location**: `src/framework/models/decorators/Field.ts` + +Defines field properties and validation: + +```typescript +interface FieldConfig { + type: FieldType; // Data type + required?: boolean; // Required field + unique?: boolean; // Unique constraint + default?: any | (() => any); // Default value + validate?: (value: any) => boolean; // Custom validation + transform?: (value: any) => any; // Data transformation + serialize?: boolean; // Include in serialization + index?: boolean; // Create index for field + virtual?: boolean; // Virtual field (not stored) +} + +@Field({ + type: 'string', + required: true, + unique: true, + validate: (value: string) => value.length >= 3, + transform: (value: string) => value.trim().toLowerCase() +}) +``` + +### Relationship Decorators +**Location**: `src/framework/models/decorators/relationships.ts` + +```typescript +// Many-to-one relationship +@BelongsTo(() => User, 'userId') +author: User; + +// One-to-many relationship +@HasMany(() => Post, 'authorId') +posts: Post[]; + +// One-to-one relationship +@HasOne(() => Profile, 'userId') +profile: Profile; + +// Many-to-many relationship +@ManyToMany(() => Tag, 'post_tags', 'tag_id', 'post_id') +tags: Tag[]; +``` + +### Lifecycle Hook Decorators +**Location**: `src/framework/models/decorators/hooks.ts` + +```typescript +@BeforeCreate() +setupDefaults() { + this.createdAt = Date.now(); +} + +@AfterCreate() +async sendNotification() { + await this.notifyUsers(); +} + +@BeforeUpdate() +updateTimestamp() { + this.updatedAt = Date.now(); +} + +@AfterUpdate() +async invalidateCache() { + await this.clearRelatedCache(); +} + +@BeforeDelete() +async checkPermissions() { + if (!this.canDelete()) { + throw new Error('Cannot delete this record'); + } +} + +@AfterDelete() +async cleanupRelations() { + await this.removeRelatedData(); +} +``` + +## Query System + +### QueryBuilder Class +**Location**: `src/framework/query/QueryBuilder.ts` + +Fluent interface for building queries: + +```typescript +export class QueryBuilder { + // Filter methods + where(field: string, value: any): QueryBuilder + where(field: string, operator: string, value: any): QueryBuilder + where(callback: (query: QueryBuilder) => void): QueryBuilder + orWhere(field: string, value: any): QueryBuilder + whereIn(field: string, values: any[]): QueryBuilder + whereNotIn(field: string, values: any[]): QueryBuilder + whereNull(field: string): QueryBuilder + whereNotNull(field: string): QueryBuilder + whereLike(field: string, pattern: string): QueryBuilder + + // Relationship methods + with(relations: string[]): QueryBuilder + withCount(relations: string[]): QueryBuilder + + // Ordering and limiting + orderBy(field: string, direction?: 'asc' | 'desc'): QueryBuilder + limit(count: number): QueryBuilder + offset(count: number): QueryBuilder + + // Field selection + select(fields: string[]): QueryBuilder + distinct(field?: string): QueryBuilder + + // Caching + cache(ttl?: number): QueryBuilder + + // Execution methods + find(): Promise + findOne(): Promise + first(): Promise + count(): Promise + exists(): Promise + paginate(page: number, perPage: number): Promise> + + // Aggregation + sum(field: string): Promise + avg(field: string): Promise + min(field: string): Promise + max(field: string): Promise +} +``` + +### Query Operators +```typescript +type QueryOperator = + | 'eq' // Equal to + | 'ne' // Not equal to + | 'gt' // Greater than + | 'gte' // Greater than or equal + | 'lt' // Less than + | 'lte' // Less than or equal + | 'in' // In array + | 'not in' // Not in array + | 'like' // Pattern matching + | 'regex' // Regular expression + | 'is null' // Is null + | 'is not null' // Is not null + | 'includes' // Array includes value + | 'includes any'// Array includes any of values + | 'includes all'// Array includes all values +``` + +## Database Management + +### DatabaseManager Class +**Location**: `src/framework/core/DatabaseManager.ts` + +Handles database creation and lifecycle: + +```typescript +export class DatabaseManager { + // Database operations + async getGlobalDatabase(modelName: string): Promise + async getUserDatabase(userId: string, modelName: string): Promise + async createDatabase(name: string, type: StoreType, options?: any): Promise + async closeDatabase(name: string): Promise + + // Document operations + async getDocument(database: Database, storeType: StoreType, id: string): Promise + async putDocument(database: Database, storeType: StoreType, id: string, data: any): Promise + async deleteDocument(database: Database, storeType: StoreType, id: string): Promise + async queryDocuments(database: Database, storeType: StoreType, query: any): Promise + + // Lifecycle + async initialize(orbitDBService: FrameworkOrbitDBService): Promise + async stop(): Promise +} +``` + +### ShardManager Class +**Location**: `src/framework/sharding/ShardManager.ts` + +Handles data distribution across shards: + +```typescript +export class ShardManager { + // Shard operations + getShardForKey(modelName: string, key: string): Shard + getShardForRange(modelName: string, value: any): Shard + getAllShards(modelName: string): Shard[] + + // Shard management + async createShards(modelName: string, config: ShardingConfig): Promise + async redistributeData(modelName: string, newShardCount: number): Promise + + // Configuration + setShardingConfig(modelName: string, config: ShardingConfig): void + getShardingConfig(modelName: string): ShardingConfig | undefined +} + +interface ShardingConfig { + strategy: 'hash' | 'range' | 'user'; + count: number; + key: string; + ranges?: ShardRange[]; +} + +interface Shard { + id: string; + database: Database; + range?: { min: any; max: any }; +} +``` + +## Relationship Management + +### RelationshipManager Class +**Location**: `src/framework/relationships/RelationshipManager.ts` + +Handles loading and caching of model relationships: + +```typescript +export class RelationshipManager { + // Relationship loading + async loadRelationship(model: BaseModel, relationshipName: string): Promise + async loadRelationships(model: BaseModel, relationshipNames: string[]): Promise + async eagerLoadRelationships(models: BaseModel[], relationshipNames: string[]): Promise + + // Relationship operations + async attachRelationship(model: BaseModel, relationshipName: string, relatedModel: BaseModel): Promise + async detachRelationship(model: BaseModel, relationshipName: string, relatedModel: BaseModel): Promise + async syncRelationship(model: BaseModel, relationshipName: string, relatedModels: BaseModel[]): Promise + + // Caching + getCachedRelationship(model: BaseModel, relationshipName: string): any + setCachedRelationship(model: BaseModel, relationshipName: string, data: any): void + clearRelationshipCache(model: BaseModel, relationshipName?: string): void +} +``` + +## Migration System + +### MigrationManager Class +**Location**: `src/framework/migrations/MigrationManager.ts` + +Handles schema evolution and data transformation: + +```typescript +export class MigrationManager { + // Migration operations + async runMigration(migrationId: string): Promise + async rollbackMigration(migrationId: string): Promise + async runPendingMigrations(): Promise + + // Migration management + registerMigration(migration: Migration): void + getPendingMigrations(): Migration[] + getAppliedMigrations(): Promise + + // Status + getMigrationStatus(): Promise +} + +interface Migration { + id: string; + version: string; + name: string; + description: string; + targetModels: string[]; + up: MigrationOperation[]; + down: MigrationOperation[]; + dependencies?: string[]; + validators?: MigrationValidator[]; +} +``` + +### MigrationBuilder Class +**Location**: `src/framework/migrations/MigrationBuilder.ts` + +Fluent interface for creating migrations: + +```typescript +export function createMigration(name: string, version: string): MigrationBuilder { + return new MigrationBuilder(name, version); +} + +export class MigrationBuilder { + // Field operations + addField(modelName: string, fieldName: string, config: FieldConfig): MigrationBuilder + removeField(modelName: string, fieldName: string): MigrationBuilder + modifyField(modelName: string, fieldName: string, config: FieldConfig): MigrationBuilder + renameField(modelName: string, oldName: string, newName: string): MigrationBuilder + + // Index operations + addIndex(modelName: string, fields: string[], options?: IndexOptions): MigrationBuilder + removeIndex(modelName: string, indexName: string): MigrationBuilder + + // Data transformation + transformData(modelName: string, transformer: (data: any) => any): MigrationBuilder + + // Validation + addValidator(name: string, validator: MigrationValidator): MigrationBuilder + + // Build migration + build(): Migration +} +``` + +## Caching System + +### QueryCache Class +**Location**: `src/framework/query/QueryCache.ts` + +Intelligent caching of query results: + +```typescript +export class QueryCache { + // Cache operations + get(key: string): Promise + set(key: string, value: any, ttl?: number): Promise + delete(key: string): Promise + clear(): Promise + + // Cache management + invalidateModelCache(modelName: string): Promise + invalidateUserCache(userId: string): Promise + + // Statistics + getStats(): CacheStats + getHitRate(): number +} +``` + +### RelationshipCache Class +**Location**: `src/framework/relationships/RelationshipCache.ts` + +Specialized caching for relationship data: + +```typescript +export class RelationshipCache { + // Relationship caching + getCachedRelationship(modelId: string, relationshipName: string): any + setCachedRelationship(modelId: string, relationshipName: string, data: any, ttl?: number): void + invalidateRelationship(modelId: string, relationshipName: string): void + + // Batch operations + preloadRelationships(modelIds: string[], relationshipNames: string[]): Promise + warmCache(modelName: string, relationshipName: string): Promise +} +``` + +## Type Definitions + +### Framework Types +**Location**: `src/framework/types/framework.ts` + +```typescript +export interface FrameworkConfig { + cache?: CacheConfig; + queryOptimization?: QueryOptimizationConfig; + automaticPinning?: PinningConfig; + pubsub?: PubSubConfig; + development?: DevelopmentConfig; +} + +export interface CacheConfig { + enabled?: boolean; + maxSize?: number; + ttl?: number; +} + +export type StoreType = 'docstore' | 'eventlog' | 'keyvalue' | 'counter' | 'feed'; +``` + +### Model Types +**Location**: `src/framework/types/models.ts` + +```typescript +export interface FieldConfig { + type: FieldType; + required?: boolean; + unique?: boolean; + default?: any | (() => any); + validate?: (value: any) => boolean; + transform?: (value: any) => any; + serialize?: boolean; + index?: boolean; + virtual?: boolean; +} + +export type FieldType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'date'; + +export interface RelationshipConfig { + type: 'belongsTo' | 'hasMany' | 'hasOne' | 'manyToMany'; + target: () => typeof BaseModel; + foreignKey: string; + localKey?: string; + through?: string; + throughForeignKey?: string; + throughLocalKey?: string; +} +``` + +### Query Types +**Location**: `src/framework/types/queries.ts` + +```typescript +export interface QueryOptions { + where?: WhereClause[]; + orderBy?: OrderByClause[]; + limit?: number; + offset?: number; + with?: string[]; + cache?: boolean | number; +} + +export interface WhereClause { + field: string; + operator: QueryOperator; + value: any; + boolean: 'and' | 'or'; +} + +export interface OrderByClause { + field: string; + direction: 'asc' | 'desc'; +} + +export interface PaginationResult { + data: T[]; + total: number; + page: number; + perPage: number; + totalPages: number; + hasNext: boolean; + hasPrev: boolean; +} +``` + +## Error Handling + +### Framework Errors +```typescript +export class DebrosFrameworkError extends Error { + code: string; + details?: any; + + constructor(message: string, code?: string, details?: any) { + super(message); + this.name = 'DebrosFrameworkError'; + this.code = code || 'UNKNOWN_ERROR'; + this.details = details; + } +} + +export class ValidationError extends DebrosFrameworkError { + field: string; + value: any; + constraint: string; +} + +export class QueryError extends DebrosFrameworkError { + query: string; + parameters?: any[]; +} + +export class RelationshipError extends DebrosFrameworkError { + modelName: string; + relationshipName: string; + relatedModel: string; +} +``` + +## Performance Optimization + +### Query Optimization +**Location**: `src/framework/query/QueryOptimizer.ts` + +```typescript +export class QueryOptimizer { + // Query optimization + optimizeQuery(query: QueryBuilder): QueryBuilder + analyzeQueryPerformance(query: QueryBuilder): Promise + suggestIndexes(modelName: string): Promise + + // Statistics + getSlowQueries(): Promise + getQueryStats(): Promise +} +``` + +### LazyLoader Class +**Location**: `src/framework/relationships/LazyLoader.ts` + +```typescript +export class LazyLoader { + // Lazy loading + async loadOnDemand(model: BaseModel, relationshipName: string): Promise + async batchLoad(models: BaseModel[], relationshipName: string): Promise + + // Configuration + setBatchSize(size: number): void + setLoadingStrategy(strategy: 'immediate' | 'batched' | 'deferred'): void +} +``` + +This technical reference provides the implementation details needed to work effectively with the DebrosFramework codebase.