bunsane 0.1.4 → 0.2.0

package/.claude/settings.local.json

@@ -0,0 +1,47 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bun test:*)",
+      "mcp__serena__check_onboarding_performed",
+      "mcp__serena__activate_project",
+      "mcp__serena__onboarding",
+      "mcp__serena__list_dir",
+      "mcp__serena__find_file",
+      "mcp__serena__get_symbols_overview",
+      "mcp__serena__find_symbol",
+      "mcp__serena__think_about_collected_information",
+      "mcp__serena__write_memory",
+      "mcp__serena__list_memories",
+      "Bash(grep:*)",
+      "mcp__serena__initial_instructions",
+      "mcp__serena__read_memory",
+      "mcp__serena__search_for_pattern",
+      "mcp__serena__think_about_whether_you_are_done",
+      "mcp__serena__replace_symbol_body",
+      "Bash(find:*)",
+      "mcp__serena__get_current_config",
+      "mcp__serena__think_about_task_adherence",
+      "Bash(bun run tsc:*)",
+      "mcp__serena__insert_after_symbol",
+      "Bash(npx tsc:*)",
+      "Bash(STRESS_RECORD_COUNT=10000 bun test:*)",
+      "Bash(STRESS_RECORD_COUNT=1000 bun test:*)",
+      "mcp__serena__find_referencing_symbols",
+      "Bash(bun tsc:*)",
+      "mcp__serena__edit_memory",
+      "Bash(bunx tsc:*)",
+      "Bash(wc:*)",
+      "Bash(bun run:*)",
+      "Bash(BUN_CONFIG_FILE=/dev/null bun test:*)",
+      "Bash(echo:*)",
+      "WebSearch",
+      "Bash(bun:*)",
+      "Bash(tsc:*)",
+      "Bash(SKIP_TEST_DB_SETUP=true bun test:*)"
+    ]
+  },
+  "statusLine": {
+    "type": "command",
+    "command": "input=$(cat); model=$(echo \"$input\" | jq -r '.model.display_name'); used=$(echo \"$input\" | jq -r '.context_window.used_percentage // empty'); remaining=$(echo \"$input\" | jq -r '.context_window.remaining_percentage // empty'); if [ -n \"$remaining\" ]; then printf \"%s | Context: %.1f%% used, %.1f%% remaining\" \"$model\" \"$used\" \"$remaining\"; else echo \"$model\"; fi"
+  }
+}

package/.claude/skills/update-memory.md

@@ -0,0 +1,74 @@
+---
+name: update-memory
+description: Updating project memories with new information
+disable-model-invocation: false
+allowed-tools: Read, Grep
+---
+
+# Update Memory Skill
+
+This skill helps you update Serena project memories with new or changed information.
+
+## When to Use
+
+Use `/update-memory` when you need to:
+- Record architectural decisions or patterns discovered during work
+- Update project conventions based on new practices
+- Document important findings from code exploration
+- Add new information to existing memory files
+- Create new memory files for undocumented aspects
+
+## Instructions
+
+1. **List existing memories** first to see what's available:
+   - Use `mcp__serena__list_memories` to see all memory files
+
+2. **Read the relevant memory** (if updating existing):
+   - Use `mcp__serena__read_memory` with the memory file name
+   - Understand the current content and structure
+
+3. **Determine the action**:
+   - **Update existing**: Use `mcp__serena__edit_memory` for targeted changes
+   - **Create new**: Use `mcp__serena__write_memory` for new topics
+   - **Delete obsolete**: Use `mcp__serena__delete_memory` (only if user confirms)
+
+4. **For updates**, use `edit_memory` with:
+   - `mode: "literal"` for exact string replacement
+   - `mode: "regex"` for pattern-based changes
+   - Keep the existing format and style
+
+5. **For new memories**, use descriptive kebab-case names:
+   - `project_overview` - General project info
+   - `architecture` - System architecture
+   - `code_style_and_conventions` - Coding standards
+   - `{feature}-implementation` - Feature-specific docs
+
+## Memory Naming Conventions
+
+| Pattern | Purpose |
+|---------|---------|
+| `project_overview` | High-level project description |
+| `architecture` | Directory structure, core concepts |
+| `code_style_and_conventions` | Formatting, naming, patterns |
+| `{topic}-decisions` | Architectural decisions on topic |
+| `{feature}-implementation` | How a feature works |
+| `suggested_commands` | Useful commands for the project |
+| `task_completion_checklist` | Steps to verify work is complete |
+
+## Example Usage
+
+```
+User: /update-memory Add that we use Bun for testing
+Assistant: [Lists memories, reads code_style_and_conventions, updates with new testing info]
+
+User: /update-memory Create a memory about the caching system
+Assistant: [Creates new memory file: caching-system.md with relevant information]
+```
+
+## Important Notes
+
+- Always read existing content before editing to preserve context
+- Use markdown format for memory content
+- Keep memories focused and organized
+- Ask for confirmation before deleting memories
+- After updating, summarize what was changed

package/.prettierrc

@@ -0,0 +1,4 @@
+{
+  "tabWidth": 4,
+  "useTabs": false
+}

package/.serena/memories/architectural-decision-no-dependency-injection.md

@@ -0,0 +1,76 @@
+# Architectural Decision: No Dependency Injection (For Now)
+
+**Date:** 2026-01-21  
+**Status:** Decided  
+**Context:** Framework v0.1.5 (experimental)
+
+## Decision
+
+BunSane will NOT implement a formal Dependency Injection (DI) container at this stage.
+
+## Current Approach
+
+The framework uses:
+- **Singleton patterns** for shared services (`CacheManager.getInstance()`, `EntityManager.instance`, `ComponentRegistry`)
+- **Global exports** for database (`import db from "database"`) and logger
+- **ApplicationLifecycle phases** for managing initialization order
+- **Metadata-driven decorators** for component/service registration
+
+## Rationale
+
+### Why DI Was Considered
+- Testing pain points: type-unsafe hacks like `(EntityManager as any).dbReady = true`
+- Hard to mock/swap implementations in tests
+- Singletons share global state between tests
+
+### Why DI Was Rejected (For Now)
+
+1. **Framework is experimental (v0.1.5)** - Too early for such fundamental architectural changes
+
+2. **Added complexity outweighs benefits** - DI adds another abstraction layer to an already complex ECS + GraphQL framework
+
+3. **Current approach works** - ApplicationLifecycle phases already manage dependency initialization order effectively
+
+4. **Users don't need to swap implementations** - Extensions happen via Components, Services, and Plugins, none of which benefit significantly from DI
+
+5. **Testing pain can be solved simpler** - Lightweight patterns like `reset()` methods or optional instance injection suffice
+
+6. **Bun ecosystem norms** - DI isn't a common pattern in modern Bun/TypeScript frameworks
+
+7. **Runtime overhead** - Relevant concern for a performance-focused framework
+
+## Alternative: Lightweight Testability Pattern
+
+Instead of full DI, use optional instance injection for testability:
+
+```typescript
+class CacheManager {
+    private static _instance: CacheManager | null = null;
+    
+    static getInstance(): CacheManager {
+        return this._instance ??= new CacheManager();
+    }
+    
+    // For testing only
+    static setInstance(instance: CacheManager | null): void {
+        this._instance = instance;
+    }
+}
+```
+
+## When to Revisit
+
+Consider DI if/when:
+- Framework reaches v1.0 with stable APIs
+- Users request ability to swap implementations
+- Codebase grows significantly larger (200+ files)
+- Multiple database/cache backends become first-class options
+
+## Related Files
+
+- `core/cache/CacheManager.ts` - Singleton cache manager
+- `core/EntityManager.ts` - Singleton entity manager
+- `core/components/ComponentRegistry.ts` - Singleton component registry
+- `service/ServiceRegistry.ts` - Singleton service registry
+- `core/ApplicationLifecycle.ts` - Lifecycle phase management
+- `database/index.ts` - Global database export

package/.serena/memories/architecture.md

@@ -0,0 +1,154 @@
+# Project Architecture
+
+## Directory Structure
+
+```
+bunsane/
+├── core/                    # Core framework
+│   ├── App.ts              # Main application entry point
+│   ├── Entity.ts           # Entity class (base data unit)
+│   ├── EntityManager.ts    # Entity lifecycle management
+│   ├── ArcheType.ts        # Entity templates with component definitions
+│   ├── BatchLoader.ts      # DataLoader for batching DB queries
+│   ├── Config.ts           # Configuration management
+│   ├── Logger.ts           # Pino logging setup
+│   ├── ErrorHandler.ts     # Error handling utilities
+│   ├── RequestContext.ts   # Request-scoped context
+│   ├── ApplicationLifecycle.ts  # App state management
+│   ├── cache/              # Caching system
+│   │   ├── CacheManager.ts     # Main cache orchestration
+│   │   ├── CacheProvider.ts    # Standard interface (all providers implement this)
+│   │   ├── MemoryCache.ts      # In-memory cache provider
+│   │   ├── RedisCache.ts       # Redis cache provider
+│   │   ├── MultiLevelCache.ts  # L1/L2 cache strategy (wrapper)
+│   │   ├── CacheAnalytics.ts   # Analytics wrapper provider
+│   │   ├── TTLStrategy.ts      # Adaptive TTL wrapper provider
+│   │   └── ...
+│   ├── components/         # Component system
+│   │   ├── BaseComponent.ts    # Base class for components
+│   │   ├── ComponentRegistry.ts # Component registration
+│   │   ├── Decorators.ts       # @Component, @CompData decorators
+│   │   └── ...
+│   ├── decorators/         # Additional decorators
+│   ├── events/             # Event system
+│   └── metadata/           # Metadata utilities
+├── database/               # Database layer
+│   ├── index.ts            # PostgreSQL connection (postgres.js)
+│   ├── DatabaseHelper.ts   # DB setup and migrations
+│   ├── PreparedStatementCache.ts  # Query caching
+│   └── IndexingStrategy.ts # Index management
+├── query/                  # Query builder
+│   ├── Query.ts            # Main query class
+│   ├── FilterBuilder.ts    # Filter construction
+│   ├── QueryDAG.ts         # Query execution graph
+│   └── ...
+├── gql/                    # GraphQL generation
+│   ├── Generator.ts        # Schema generation
+│   ├── builders/           # Type/resolver builders
+│   ├── decorators/         # GQL decorators
+│   ├── strategies/         # Type generation strategies
+│   └── visitors/           # Schema visitors
+├── service/                # Service layer
+│   ├── Service.ts          # Base service class
+│   └── ServiceRegistry.ts  # Service registration
+├── plugins/                # Plugin system
+├── scheduler/              # Task scheduling
+├── storage/                # File storage
+├── upload/                 # File upload handling
+├── rest/                   # REST endpoint support
+├── swagger/                # OpenAPI documentation
+├── studio/                 # BunSane Studio (web UI)
+├── test/                   # Tests
+│   ├── setup.ts            # Test environment setup
+│   ├── integration/        # Integration tests
+│   └── gql/                # GraphQL tests
+├── types/                  # Type definitions
+└── utils/                  # Utility functions
+```
+
+## Core Concepts Flow
+
+1. **App** initializes the application, sets up GraphQL Yoga server
+2. **Components** are registered via `@Component` decorator
+3. **Entities** are created and manipulated, storing component data
+4. **ArcheTypes** define entity templates for type-safe component access
+5. **Query** builder retrieves entities with filters and component population
+6. **Services** define business logic and auto-generate GraphQL resolvers
+7. **CacheManager** handles caching at entity/component/query levels
+
+## Cache System Architecture
+
+All cache providers implement the standardized `CacheProvider` interface:
+
+```typescript
+interface CacheProvider {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    delete(key: string | string[]): Promise<void>;  // Supports single or multiple
+    clear(): Promise<void>;
+    getMany<T>(keys: string[]): Promise<(T | null)[]>;  // Returns ordered array
+    setMany<T>(entries: Array<{key, value, ttl?}>): Promise<void>;  // Per-entry TTL
+    deleteMany(keys: string[]): Promise<void>;
+    invalidatePattern(pattern: string): Promise<void>;
+    ping(): Promise<boolean>;  // Health check
+    getStats(): Promise<CacheStats>;  // Metrics
+}
+```
+
+**Cache Providers**:
+- **MemoryCache**: In-memory LRU cache (base implementation)
+- **RedisCache**: Redis-backed cache (base implementation)
+- **MultiLevelCacheProvider**: L1 (memory) + L2 (Redis) wrapper
+- **AnalyticsCacheProvider**: Metrics and latency tracking wrapper
+- **AdaptiveTTLProvider**: Dynamic TTL adjustment wrapper
+
+**Key Design Decisions** (as of 2026-01-24):
+- Batch operations use arrays instead of Maps for ordering and flexibility
+- `delete()` accepts both single string and string array for convenience
+- `ping()` replaces `healthCheck()` for conventional naming
+- All wrappers maintain full interface compliance
+
+## Import Resolution (as of 2026-02-05)
+
+All internal imports use **relative paths** (`./`, `../`). Bare imports like `from "core/Logger"` that rely on `baseUrl` are NOT allowed because they break TypeScript type checking for consumers who install bunsane as a dependency (their tsconfig does not have baseUrl pointing to bunsane root).
+
+## Data Model
+
+- **Entity**: UUID-identified record in `entities` table
+- **Component**: JSONB data in `components` table, linked to entity
+- Components are identified by `entity_id` + `component_type`
+- Supports indexing specific component fields for queries
+
+## CORS System (as of 2026-02-04)
+
+The App class (`core/App.ts`) provides comprehensive CORS support with proper spec compliance.
+
+**CorsConfig Type**:
+```typescript
+type CorsConfig = {
+    origin?: string | string[] | ((origin: string) => boolean);
+    credentials?: boolean;
+    allowedHeaders?: string[];
+    exposedHeaders?: string[];  // For Access-Control-Expose-Headers
+    methods?: string[];
+    maxAge?: number;  // Preflight cache duration in seconds
+};
+```
+
+**Key Features**:
+- **Origin Validation**: Validates request Origin header against configured origins
+- **Array Origins**: Returns the matching origin (not comma-joined) per spec
+- **Function Origins**: Supports `(origin: string) => boolean` for dynamic validation
+- **Credentials + Wildcard**: When credentials=true with origin="*", reflects actual origin instead of wildcard
+- **Vary Header**: Always includes `Vary: Origin` for proper caching
+- **All Endpoints**: CORS headers applied to all response paths (health, docs, openapi, studio, errors)
+
+**Usage**:
+```typescript
+app.setCors({
+    origin: ["http://localhost:3000", "https://myapp.com"],
+    credentials: true,
+    maxAge: 86400,
+    exposedHeaders: ["X-Custom-Header"]
+});
+```

package/.serena/memories/cache-interface-refactoring-2026-01-24.md

@@ -0,0 +1,165 @@
+# Cache Interface Refactoring - January 24, 2026
+
+## Status: COMPLETED
+**Completion Date**: 2026-01-24
+**Outcome**: Successfully standardized CacheProvider interface implementation across all cache-related files
+
+## Summary
+Fixed TypeScript compilation errors caused by mismatches between the `CacheProvider` interface and its implementations. The interface was correct, but several wrapper classes and test files had outdated method signatures.
+
+## Impact
+- **Errors Reduced**: From 100+ TypeScript errors to 69
+- **Cache Errors**: Fully resolved (0 remaining)
+- **Remaining Errors**: Unrelated to cache (SchedulerManager, GraphQL builders, test access to private members)
+
+## Files Modified
+
+### Core Cache Files (3 files)
+
+#### 1. `core/cache/CacheAnalytics.ts`
+**Class**: `AnalyticsCacheProvider`
+
+Changes:
+- Changed import to type-only import: `import type { CacheProvider } from './CacheProvider'`
+- Made `recordLatency` method public
+- Fixed method signatures:
+  - `delete(key: string | string[]): Promise<void>` (was single key only)
+  - `getMany<T>(keys: string[]): Promise<(T | null)[]>` (was returning Map)
+  - `setMany<T>(entries: Array<{key, value, ttl?}>): Promise<void>` (was using Map)
+  - `deleteMany(keys: string[]): Promise<void>` (added proper typing)
+  - `ping(): Promise<boolean>` (replaced `healthCheck()`)
+  - `getStats(): Promise<CacheStats>` (was async but not typed correctly)
+- Removed `has()` method (not in interface)
+
+#### 2. `core/cache/MultiLevelCache.ts`
+**Class**: `MultiLevelCacheProvider`
+
+Changes:
+- Fixed import path and made type-only
+- Applied same method signature fixes as CacheAnalytics
+- Added proper type guards for array access in `delete()` method
+- Ensured L1/L2 cache coordination respects new interface
+
+#### 3. `core/cache/TTLStrategy.ts`
+**Class**: `AdaptiveTTLProvider`
+
+Changes:
+- Applied same method signature fixes as above
+- Ensured TTL adaptation logic works with updated interface
+
+### Config Files (1 file)
+
+#### 4. `config/cache.config.ts`
+
+Changes:
+- Added `'multilevel'` to provider type union
+- Added `query` property with structure:
+  ```typescript
+  query: {
+    enabled: boolean;
+    ttl: number;
+    maxSize: number;
+  }
+  ```
+
+### Test Files (7 files)
+
+#### 5. `tests/unit/cache/MemoryCache.test.ts`
+- Added explicit type parameters to `cache.get<T>()` calls
+- Ensures type safety in test assertions
+
+#### 6. `tests/unit/cache/RedisCache.test.ts`
+- Added explicit type parameters to `cache.get<T>()` calls
+
+#### 7-11. Test Configuration Files
+Added `maxSize` to query config objects in:
+- `tests/integration/cache/CacheInvalidation.test.ts`
+- `tests/setup.ts`
+- `tests/stress/cursor-perf-test.ts`
+- `tests/unit/cache/CacheManager.test.ts`
+- `tests/utils/test-context.ts`
+
+## Key Interface Contract
+
+```typescript
+interface CacheProvider {
+    // Single operations
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    delete(key: string | string[]): Promise<void>;
+    clear(): Promise<void>;
+    
+    // Batch operations
+    getMany<T>(keys: string[]): Promise<(T | null)[]>;
+    setMany<T>(entries: Array<{key: string, value: T, ttl?: number}>): Promise<void>;
+    deleteMany(keys: string[]): Promise<void>;
+    
+    // Pattern operations
+    invalidatePattern(pattern: string): Promise<void>;
+    
+    // Health and metrics
+    ping(): Promise<boolean>;
+    getStats(): Promise<CacheStats>;
+}
+```
+
+## Critical Design Decisions
+
+### 1. Array Return for getMany
+**Decision**: `getMany` returns `Promise<(T | null)[]>` instead of `Map<string, T | null>`
+**Rationale**: 
+- Maintains order of requested keys
+- Simpler type handling
+- Better performance for indexed access
+
+### 2. Entry Array for setMany
+**Decision**: `setMany` takes `Array<{key, value, ttl?}>` instead of `Map`
+**Rationale**:
+- Supports per-entry TTL configuration
+- More flexible than Map-based approach
+- Aligns with common cache API patterns
+
+### 3. Flexible Delete
+**Decision**: `delete(key: string | string[])` accepts both single and multiple keys
+**Rationale**:
+- Reduces API surface area (no need for separate deleteOne/deleteMany)
+- Convenience for common use cases
+- Backward compatible with single-key usage
+
+### 4. Ping Instead of HealthCheck
+**Decision**: Renamed `healthCheck()` to `ping()`
+**Rationale**:
+- Shorter, more conventional name
+- Matches Redis and memcached naming
+- Clearer intent (simple connectivity check)
+
+## Verification
+
+### TypeScript Compilation
+- All cache-related files now compile without errors
+- Type safety enforced across all implementations
+- No type assertions or `any` types introduced
+
+### Interface Compliance
+All three wrapper implementations now fully comply:
+- AnalyticsCacheProvider (wraps any provider with metrics)
+- MultiLevelCacheProvider (L1/L2 cache coordination)
+- AdaptiveTTLProvider (dynamic TTL adjustment)
+
+## Follow-Up Items
+
+None for cache. Remaining TypeScript errors are in:
+1. **SchedulerManager**: Unrelated to cache
+2. **GraphQL builders**: Schema generation issues
+3. **Test files**: Access to private members (test-specific issues)
+
+## Lessons Learned
+
+1. **Interface-First Design**: Having a well-defined interface is only half the battle; keeping implementations in sync is critical
+2. **Type-Only Imports**: Using `import type` helps clarify when you're only referencing types vs. runtime values
+3. **Batch Operations**: The switch from Map to Array for batch ops required careful consideration of ordering and flexibility
+4. **Test Coverage**: Tests that use explicit type parameters catch more type mismatches earlier
+
+## Related Memories
+- See `architecture` for overall cache system design
+- See `code_style_and_conventions` for TypeScript patterns used

package/.serena/memories/code_style_and_conventions.md

@@ -0,0 +1,76 @@
+# Code Style and Conventions
+
+## Formatting
+- **Indentation**: 4 spaces (configured in `.prettierrc`)
+- **No tabs**: Spaces only
+- **Prettier**: Used for formatting
+
+## TypeScript Configuration
+- **Strict mode**: Enabled
+- **Experimental decorators**: Enabled
+- **Emit decorator metadata**: Enabled
+- **Module**: ESNext/Preserve
+- **Path alias**: `@/*` maps to `./*`
+
+## Naming Conventions
+- **Classes**: PascalCase (e.g., `Entity`, `BaseComponent`, `CacheManager`)
+- **Methods/Functions**: camelCase (e.g., `createEntity`, `getEntityWithID`)
+- **Variables**: camelCase
+- **Constants**: camelCase or UPPER_SNAKE_CASE for environment-like values
+- **Private properties**: Prefix with underscore (e.g., `_dirty`, `_persisted`)
+- **Interfaces**: PascalCase, often prefixed with `I` (e.g., `IEntity`)
+- **Types**: PascalCase
+
+## Decorators Usage
+The framework heavily uses TypeScript decorators:
+
+```typescript
+// Component definition
+@Component
+class MyComponent extends BaseComponent {
+    @CompData()
+    myField!: string;
+}
+
+// ArcheType definition
+class MyArcheType extends BaseArcheType {
+    @ArcheTypeField(MyComponent)
+    myComponent!: MyComponent;
+}
+```
+
+## Import Style
+- **ALWAYS use relative imports** (`./`, `../`) for all internal modules
+- Do NOT use bare imports like `from "core/Logger"` - they rely on `baseUrl` and break consumer typechecking
+- The `@/` path alias is configured but not used in practice; prefer relative imports
+- Group imports: external packages first, then internal modules
+- **Type-only imports**: Use `import type` for interface/type imports when only used for type checking:
+  ```typescript
+  import type { CacheProvider } from './CacheProvider';
+  ```
+  Benefits: Clearer intent, reduced runtime dependencies, better tree-shaking
+
+## Testing Conventions
+- Test files: `*.test.ts`
+- Use Bun's built-in test runner (`bun:test`)
+- Structure: `describe` blocks for grouping, `test` for individual cases
+- Use `beforeAll`/`afterAll` for setup/cleanup
+- Integration tests should clean up created entities
+
+```typescript
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+
+describe('FeatureName', () => {
+    beforeAll(async () => { /* setup */ });
+    afterAll(async () => { /* cleanup */ });
+    
+    test('should do something', async () => {
+        expect(result).toBe(expected);
+    });
+});
+```
+
+## Documentation
+- Use JSDoc comments for public APIs
+- Block comments for file headers explaining purpose
+- Inline comments sparingly, only when logic is complex

package/.serena/memories/project_overview.md

@@ -0,0 +1,43 @@
+# BunSane Project Overview
+
+## Purpose
+BunSane is a batteries-included TypeScript API framework for Bun with:
+- Entity–Component storage on PostgreSQL (auto-migrates base tables on first run)
+- Fluent, performant Query builder
+- Zero-boilerplate GraphQL with GraphQL Yoga
+- Declarative Components with decorators and indexed fields
+
+**Status**: EXPERIMENTAL - Not Production Ready
+
+## Tech Stack
+- **Runtime**: Bun
+- **Language**: TypeScript 5.9+ (strict mode, experimental decorators)
+- **Database**: PostgreSQL
+- **GraphQL**: GraphQL Yoga + GQLoom (@gqloom/core, @gqloom/zod)
+- **Validation**: Zod 4.x
+- **Logging**: Pino (with pino-pretty for development)
+- **Cache**: Memory and Redis support (ioredis)
+- **Data Loading**: dataloader for batching
+
+## Key Concepts
+1. **Entity**: Base unit of data storage, identified by UUID
+2. **Component**: Data attached to entities (decorators: @Component, @CompData)
+3. **ArcheType**: Defines a template of components an entity should have
+4. **Query**: Fluent query builder for retrieving entities with components
+5. **Service**: Business logic layer with auto-generated GraphQL schema
+
+## Environment Variables
+Database configuration via environment variables:
+- `POSTGRES_HOST`, `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`
+- `POSTGRES_MAX_CONNECTIONS`
+- `LOG_LEVEL`, `LOG_PRETTY`
+
+## Cache Configuration
+Cache system supports multiple providers (configured in `config/cache.config.ts`):
+- **Providers**: `memory`, `redis`, `multilevel`
+- **Query cache**: Can be enabled with configurable TTL and max size
+- All providers implement standardized `CacheProvider` interface
+- Wrapper providers available: Analytics, MultiLevel, AdaptiveTTL
+
+## Repository
+https://github.com/yaaruu/bunsane