From 838ae6e0d45e0a62d7d73cad23f3f5d261806509 Mon Sep 17 00:00:00 2001 From: Dionisio Pozo <58851263+DioCrafts@users.noreply.github.com> Date: Mon, 24 Mar 2025 12:52:54 +0100 Subject: [PATCH] Update README.md --- README.md | 148 +++++++++++++----------------------------------------- 1 file changed, 36 insertions(+), 112 deletions(-) diff --git a/README.md b/README.md index 147ad34e..c67f68f3 100644 --- a/README.md +++ b/README.md @@ -4,125 +4,52 @@ OxiCloud

-## The high-performance, Rust-powered file storage solution +## A lightweight, Rust-powered alternative to NextCloud -OxiCloud is a NextCloud-like file storage system built with Rust, designed from the ground up with **performance**, **security**, and **scalability** as its core principles. Perfect for self-hosting your own cloud storage or deploying in enterprise environments. - -## ✨ Key Features - -- πŸ”₯ **Blazing Fast Performance**: Built with Rust and optimized for speed -- πŸ“ **Advanced File Management**: Intuitive folder structure with powerful batch operations -- πŸ”„ **Concurrent Processing**: Parallel file operations for large files and batch processing -- πŸ” **Smart Caching**: Multi-layered caching system for metadata and file access -- 🌐 **Internationalization**: Full i18n support (currently English and Spanish) -- πŸ“± **Responsive Design**: Works seamlessly on desktop and mobile devices -- πŸ”Œ **Extensible Architecture**: Clean, layered design following domain-driven principles - -## πŸš€ Performance Optimizations - -OxiCloud incorporates multiple advanced performance optimizations: - -### Concurrency and Parallelism -- **Parallel File Processing**: Automatically splits large files into chunks for parallel processing -- **Asynchronous I/O**: Built on Tokio for non-blocking operations -- **Worker Pools**: Smart thread management for optimal resource utilization -- **Timeout Management**: Strategic timeouts to prevent resource exhaustion - -### Intelligent Caching -- **File Metadata Cache**: Drastically reduces filesystem calls -- **Smart Cache Invalidation**: Selectively invalidates cache entries -- **Preloading**: Strategic preloading for frequently accessed directories -- **TTL-Based Cache**: Time-based expiration for optimal memory usage - -### I/O Optimization -- **Buffer Pooling**: Reuses memory buffers to reduce allocation pressure -- **Adaptive Streaming**: Adjusts chunk sizes based on file size -- **Size-Based Processing**: Different strategies for small, medium, and large files -- **Non-Blocking Filesystem Operations**: Prevents I/O bottlenecks - -### Batch Processing -- **ID Mapping Optimizer**: Groups mapping operations to reduce overhead -- **Operation Batching**: Processes multiple file operations concurrently -- **Debounced Saving**: Groups write operations for optimal I/O -- **Parallel Directory Scanning**: Efficient directory traversal - -## 🧠 Advanced Technical Features - -### Clean Architecture Implementation -- **Hexagonal/Ports and Adapters Pattern**: Clear separation between domain, application, and infrastructure -- **Dependency Inversion**: Domain business rules are independent of external frameworks -- **Explicit Dependency Injection**: Manual, type-safe DI without heavy frameworks - -### Advanced Error Handling -- **Domain-Specific Error Types**: Granular error classification with context -- **Error Propagation Chain**: Preserves context through abstraction layers -- **Custom Error Context**: Enriches errors with additional information -- **Source Tracking**: Errors maintain their original source for debugging - -### Robust Repository Pattern -- **Persistence Abstraction**: Domain layer completely isolated from storage details -- **Repository Interfaces**: Defined in domain layer and implemented in infrastructure -- **Storage Mediator Pattern**: Coordinates interactions between repositories -- **ID Mapping Service**: Decouples domain identifiers from filesystem paths - -### Transaction Management -- **Atomic Operations**: Entity-level transaction support -- **Pending Changes System**: Batches persistence operations for efficiency -- **Rollback Capabilities**: Reverts state on failed operations -- **Optimistic Concurrency**: Protects against concurrent modifications - -### Advanced File System Handling -- **Parallel Processing for Large Files**: Chunked operations for efficient I/O -- **Specialized Strategies**: Different handlers for various file sizes -- **Timeout-Protected Operations**: Prevents hanging on problematic files -- **Background Processing**: Heavy operations offloaded to background tasks - -### Memory Efficiency -- **Buffer Pool Manager**: Reuses allocated memory to reduce fragmentation -- **Streaming I/O**: Processing large files without loading entirely into memory -- **Resource-Aware Processing**: Adapts resource usage based on file size -- **Lazy Loading**: Loads data only when needed - -### Defensive Programming -- **Extensive Input Validation**: Domain entities enforce business rules -- **Immutable Data Structures**: Prevents unexpected state mutations -- **Fail-Fast Operations**: Early validation to prevent cascading failures -- **Extensive Logging**: Structured logs with contextual information - -### Service Layer Optimizations -- **Application Services**: Orchestrate use cases with domain entities -- **Transaction Coordination**: Ensures data consistency across operations -- **Domain Service Specialization**: Services focused on specific domain concerns -- **Cross-Cutting Concerns**: Separated into dedicated middleware components - -## πŸ“Έ Screenshots +I built OxiCloud because I wanted a simpler, faster file storage solution than existing options. After struggling with NextCloud's performance on my home server, I decided to create something that prioritizes speed and simplicity while still being robust enough for daily use. ![OxiCloud Dashboard](doc/images/Captura%20de%20pantalla%202025-03-23%20230739.png) -*OxiCloud main interface showing file and folder management* +*OxiCloud's straightforward interface for file and folder management* + +## ✨ What makes OxiCloud different? + +- **Lightweight**: Minimal resource requirements compared to PHP-based alternatives +- **Responsive UI**: Clean, fast interface that works well on both desktop and mobile +- **Rust Performance**: Built with Rust for memory safety and speed +- **Simple Setup**: Get running with minimal configuration +- **Multilingual**: Full support for English and Spanish interfaces ## πŸ› οΈ Getting Started ### Prerequisites - Rust 1.70+ and Cargo +- PostgreSQL 13+ database +- 512MB RAM minimum (1GB+ recommended) ### Installation ```bash # Clone the repository -git clone https://github.com/yourusername/oxicloud.git +git clone https://github.com/DioCrafts/oxicloud.git cd oxicloud +# Configure your database (create .env file with your PostgreSQL connection) +echo "DATABASE_URL=postgres://username:password@localhost/oxicloud" > .env + # Build the project cargo build --release +# Run database migrations +cargo run --bin migrate + # Run the server cargo run --release ``` The server will be available at `http://localhost:8085` -## 🧩 Project Structure +## 🧩 Technical Implementation OxiCloud follows Clean Architecture principles with clear separation of concerns: @@ -131,6 +58,8 @@ OxiCloud follows Clean Architecture principles with clear separation of concerns - **Infrastructure Layer**: External systems and implementations - **Interfaces Layer**: API and web controllers +The architecture makes it easy to extend functionality or swap components without affecting the core system. + ## 🚧 Development ```bash @@ -153,36 +82,31 @@ RUST_LOG=debug cargo run # Run with detailed logging ## πŸ—ΊοΈ Roadmap -OxiCloud is under active development. Upcoming features include: +I'm actively working on improving OxiCloud with features that I need personally: -- User authentication and multi-user support -- File sharing and collaboration features -- WebDAV support and sync clients -- File versioning -- Encryption -- Mobile applications +- User authentication and multi-user support (in progress) +- File sharing with simple links +- WebDAV support for desktop integration +- Basic file versioning +- Simple mobile-friendly web interface enhancements +- Trash bin functionality (in progress) -See [TODO-LIST.md](TODO-LIST.md) for a detailed roadmap. +See [TODO-LIST.md](TODO-LIST.md) for my current development priorities. ## 🀝 Contributing -Contributions are welcome! Whether it's bug reports, feature suggestions, or code contributions, please feel free to reach out. +Contributions are welcome! The project is still in early stages, so there's lots of room for improvement: 1. Fork the repository -2. Create your feature branch (`git checkout -b feature/amazing-feature`) -3. Commit your changes (`git commit -m 'Add some amazing feature'`) -4. Push to the branch (`git push origin feature/amazing-feature`) +2. Create your feature branch (`git checkout -b feature/something-useful`) +3. Commit your changes (`git commit -m 'Add something useful'`) +4. Push to the branch (`git push origin feature/something-useful`) 5. Open a Pull Request ## πŸ“œ License OxiCloud is available under the MIT License. See the LICENSE file for more information. -## πŸ™ Acknowledgements - -- The Rust community for the amazing ecosystem -- All contributors who have helped shape this project - --- -Designed with ❀️ by OxiCloud Team \ No newline at end of file +Built by a developer who just wanted better file storage. Feedback and contributions welcome!