spacedrive/docs/README.md

Spacedrive Core v2 Documentation

A unified, simplified architecture for cross-platform file management.

Overview

Core v2 is a complete rewrite of Spacedrive's core system, designed to address the architectural issues identified in the original codebase. It implements a clean, event-driven architecture with unified file management and a dramatically simplified job system.

Key Improvements

✅ Unified File System

• Single API for all file operations (no more dual indexed/ephemeral systems)
• Consistent behavior across all file management scenarios
• Bridge operations between different storage modes

✅ Event-Driven Architecture

• Replaced query invalidation with proper event bus
• Type-safe events for state changes
• Decoupled frontend/backend communication

✅ Modern Database Layer

• SeaORM instead of abandoned prisma-client-rust
• Optimized storage with 70%+ space savings for large file collections
• Proper migrations and database versioning

✅ Simplified Job System

• 50 lines vs 500+ lines to create new jobs
• Automatic serialization with MessagePack
• Type-safe progress reporting
• Database persistence with resume capabilities

✅ Clean Domain Models

• Entry-centric design where every file/folder has metadata by default
• Optional content identity for deduplication
• Unified device management (no more Node/Device/Instance confusion)

What's Complete

• Core initialization and lifecycle
• Library management (create, open, close, discovery)
• Device management with persistent identity
• Domain models (Entry, Location, Device, UserMetadata, ContentIdentity)
• Database layer with SeaORM and migrations
• Job system infrastructure with example jobs
• Event bus for decoupled communication
• File operations foundation (copy jobs)
• Indexing operations foundation
• Comprehensive tests and working examples

Architecture Documents

• Architecture Overview - High-level system design
• Domain Models - Core business entities and their relationships
• Job System - Background task processing and job management
• Database - Data persistence and storage optimization
• Examples - Working code examples and usage patterns

Quick Start

use sd_core::Core;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize core
    let core = Core::new().await?;

    // Create a library
    let library = core.libraries
        .create_library("My Library", None)
        .await?;

    println!("Library created: {}", library.name().await);
    println!("Path: {}", library.path().display());

    // Core automatically handles cleanup on drop
    Ok(())
}

Running Examples

# Library management demo
cargo run --example library_demo

# Job system demo
cargo run --example job_demo

# File type system demo
cargo run --example file_type_demo

Running Tests

# Run all tests
cargo test

# Run specific test modules
cargo test library_test
cargo test job_system_test
cargo test indexer_job_test

Project Status

Core v2 provides a solid foundation for Spacedrive's file management capabilities. The architecture is designed to be:

• Simple - Fewer abstractions, clearer responsibilities
• Maintainable - Modern Rust patterns, comprehensive tests
• Extensible - Event-driven design, pluggable job system
• Performant - Optimized database schema, efficient operations

Next Steps

1. API Layer - GraphQL/REST API implementation
2. Advanced Search - Full-text search with SQLite FTS5
3. Sync System - Cloud/P2P synchronization using third-party solutions
4. Media Processing - Thumbnail generation and metadata extraction
5. File Watching - Real-time filesystem monitoring

Contributing

See the examples for detailed usage patterns and the architecture docs for implementation guidance.