Daniel Harvey
132 lines
5.7 KiB
Markdown
132 lines
5.7 KiB
Markdown
# FileDatabase C# Port
|
|
|
|
This is a C# port of the TypeScript file database system, maintaining architectural integrity while leveraging C# language features.
|
|
|
|
## Architecture Overview
|
|
|
|
The C# port preserves the original three-layer architecture:
|
|
|
|
### 1. **FileDatabase** (Main Orchestrator)
|
|
- **Location**: `Services/FileDatabase.cs`
|
|
- **Purpose**: Root-level manager coordinating multiple media vaults
|
|
- **Key Features**:
|
|
- Manages collection of `MediaVault` instances using `StructuralMap<string, MediaVault>`
|
|
- Provides async factory method `FromAsync()` for initialization
|
|
- Handles vault creation, resource loading, and resource registration
|
|
|
|
### 2. **MediaVault System** (Storage Containers)
|
|
- **Location**: `Services/MediaVault.cs`
|
|
- **Components**:
|
|
- `MediaVault` (Abstract base class)
|
|
- `ImageVault` (Concrete implementation for images)
|
|
- `AudioVault` (Concrete implementation for audio)
|
|
- **Key Features**:
|
|
- File path normalization and media key generation
|
|
- Generic type-safe operations using `MediaVaultType` enum
|
|
- Metadata association with stored files
|
|
- Async factory pattern for initialization
|
|
|
|
### 3. **Index Management** (Metadata & Organization)
|
|
- **Location**: `Services/IndexSystem.cs`
|
|
- **Two-tier indexing**:
|
|
- `DirectoryIndex`: Manages vault entries (what vaults exist)
|
|
- `VaultIndex`: Manages media entries within vaults (what files exist + metadata)
|
|
- **Features**:
|
|
- `IndexFactory` handles index creation/loading
|
|
- Automatic JSON serialization to filesystem
|
|
- Strong typing with generic constraints
|
|
|
|
## Key Components
|
|
|
|
### Models (`Models/` directory)
|
|
- **String-based keys**: Simple string identifiers for vault and entry management
|
|
- **`MetaData` hierarchy**: Base metadata → `ImageMetaData` with aspect ratio
|
|
- **Media Types**: `FileBinary` → `MediaBinary` → `ImageBinary`
|
|
- **Factory Classes**: Type-safe creation of media objects and metadata
|
|
|
|
### Utilities (`Utils/` directory)
|
|
- **`StructuralMap<TKey, TValue>`**: JSON-based structural equality for complex keys
|
|
- **`StructuralSet<T>`**: Set with structural equality semantics
|
|
- **`FileUtils`**: Async file I/O operations with chunked reading/writing
|
|
|
|
## C# Design Improvements
|
|
|
|
### SOLID Principles Applied
|
|
1. **Single Responsibility**: Each class handles one concern
|
|
2. **Open/Closed**: Extensible media types via generic constraints
|
|
3. **Liskov Substitution**: Proper inheritance hierarchies
|
|
4. **Interface Segregation**: Focused interfaces (`IIndex`)
|
|
5. **Dependency Inversion**: Abstract base classes and interfaces
|
|
|
|
### C# Language Features
|
|
- **Records**: Immutable data structures for `MetaData` hierarchy
|
|
- **Pattern Matching**: Switch expressions for type-safe factory methods
|
|
- **Nullable Reference Types**: Explicit nullability handling
|
|
- **Async/Await**: Full async support with `Task<T>` and `ValueTask<T>`
|
|
- **Generic Constraints**: Strong typing with `where` clauses
|
|
|
|
### DRY Implementation
|
|
- **Factory Pattern**: Centralized object creation logic
|
|
- **Generic Type Maps**: Reusable type mappings for different media types
|
|
- **Template Method Pattern**: Common functionality in base classes
|
|
|
|
## Usage Example
|
|
|
|
```csharp
|
|
// Initialize the database
|
|
var database = await FileDatabase.FromAsync("/path/to/database");
|
|
|
|
// Create a vault
|
|
var vaultId = "images";
|
|
await database.CreateVaultAsync(vaultId, MediaVaultType.Image);
|
|
|
|
// Store an image (MediaVaultType inferred from ImageBinary)
|
|
var imageData = new ImageBinary(new ImageBinaryParams(buffer, size, ".jpg", 1.5));
|
|
await database.RegisterResourceAsync("gallery", "photo1", imageData);
|
|
|
|
// Load an image (MediaVaultType inferred from ImageBinary generic type)
|
|
var loadedImage = await database.LoadResourceAsync<ImageBinary>("gallery", "photo1");
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
FileDatabase/
|
|
├── Models/
|
|
│ ├── [EntryKey removed] # Now using simple string keys
|
|
│ ├── MetaData.cs # Metadata hierarchy
|
|
│ ├── MediaModels.cs # Binary data classes
|
|
│ ├── MediaFactories.cs # Factory pattern implementations
|
|
│ ├── MediaVaultType.cs # Enum for vault types
|
|
│ ├── IIndex.cs # Index interface
|
|
│ └── IndexData.cs # Index implementations
|
|
├── Services/
|
|
│ ├── FileDatabase.cs # Main orchestrator
|
|
│ ├── MediaVault.cs # Vault system
|
|
│ └── IndexSystem.cs # Index management
|
|
├── Utils/
|
|
│ ├── StructuralMap.cs # Structural equality map
|
|
│ ├── StructuralSet.cs # Structural equality set
|
|
│ └── FileUtils.cs # File I/O utilities
|
|
└── [FileDatabase is now part of DeepDrftContent.Services.csproj]
|
|
```
|
|
|
|
## Key Architectural Decisions
|
|
|
|
1. **Async-First Design**: All I/O operations are asynchronous
|
|
2. **Strong Type Safety**: Extensive use of generics and constraints
|
|
3. **Structural Equality**: JSON-based equality for composite keys
|
|
4. **Separation of Concerns**: Clear boundaries between indexing, storage, and media handling
|
|
5. **Factory-Based Initialization**: Handles complex async setup patterns
|
|
6. **Metadata-Driven**: Rich metadata system supporting extensible media types
|
|
|
|
## Differences from TypeScript Version
|
|
|
|
1. **Explicit Type Safety**: C# compiler enforces type constraints at compile time
|
|
2. **Memory Management**: Automatic garbage collection vs manual buffer management
|
|
3. **Serialization**: System.Text.Json instead of V8 serialization
|
|
4. **Error Handling**: Exceptions vs try/catch patterns (maintained original behavior)
|
|
5. **Nullability**: Explicit nullable reference types for better null safety
|
|
|
|
This port maintains the architectural integrity of the original TypeScript design while leveraging C#'s type system and language features for improved maintainability and performance.
|