Oxicloud/REPO-DOCUMENTATION.md

# OxiCloud Code Documentation

This document provides a detailed description of each file in the OxiCloud codebase, organized by architectural layers according to the clean hexagonal architecture pattern.

## Domain Layer

The domain layer forms the core of the application, containing business entities and repository interfaces.

### Entities

**File Entity (`src/domain/entities/file.rs`)**
- Core domain entity representing files in the system
- Implements an immutable design pattern for file operations
- Provides validation, creation, and manipulation methods for files
- Maintains both physical storage information and logical metadata
- Includes error handling via `FileError` for validation failures

**Folder Entity (`src/domain/entities/folder.rs`)**
- Represents folders/directories in the domain model
- Supports hierarchical structure with parent-child relationships
- Provides validation, creation, and update operations
- Implements immutable pattern with methods returning new instances
- Handles path resolution for proper folder hierarchy

**User Entity (`src/domain/entities/user.rs`)**
- Manages user accounts and authentication
- Provides secure password handling with Argon2 hashing
- Supports roles (Admin, User) with appropriate permissions
- Tracks storage usage and quotas
- Includes account management functions (activation, deactivation, login tracking)

**Share Entity (`src/domain/entities/share.rs`)**
- Implements file and folder sharing functionality
- Supports various permission levels (read, write, reshare)
- Provides password protection for shared resources
- Handles expiration dates for temporary sharing
- Tracks access statistics for shared resources

**Calendar Entity (`src/domain/entities/calendar.rs`)**
- Supports calendar functionality for CalDAV integration
- Manages calendar properties like name, color, and description
- Provides ownership and access control
- Supports custom properties for extended CalDAV compatibility
- Handles validation of calendar data

**Calendar Event Entity (`src/domain/entities/calendar_event.rs`)**
- Represents calendar events with properties like title, description, location
- Handles date/time management with recurrence rules
- Supports reminders and notifications
- Provides validation for event data
- Implements custom properties for CalDAV compatibility

**Trashed Item Entity (`src/domain/entities/trashed_item.rs`)**
- Manages files and folders in the trash
- Tracks original locations for restoration
- Implements automatic cleanup based on retention policies
- Provides restoration and permanent deletion functionality

### Repositories (Interfaces)

**File Repository (`src/domain/repositories/file_repository.rs`)**
- Defines the contract for file storage operations
- Abstracts storage implementation details from the domain
- Supports file creation, retrieval, updating, and deletion
- Provides methods for content streaming and file movement
- Includes trash functionality for file lifecycle management

**Folder Repository (`src/domain/repositories/folder_repository.rs`)**
- Defines the interface for folder manipulation
- Abstracts storage implementation details for directories
- Handles folder creation, listing, and hierarchy management
- Supports moving folders and retrieving path information
- Includes trash operations for folders

**User Repository (`src/domain/repositories/user_repository.rs`)**
- Defines the interface for user data persistence
- Supports user creation, retrieval, and management
- Provides authentication and session management
- Handles user preferences and settings storage
- Manages user quotas and storage usage tracking

**Share Repository (`src/domain/repositories/share_repository.rs`)**
- Defines the interface for share record management
- Handles creation and validation of share records
- Tracks permissions and expiration settings
- Provides access verification for shared resources
- Manages share revocation and updates

**Trash Repository (`src/domain/repositories/trash_repository.rs`)**
- Defines the interface for trash operations
- Manages soft deletion and restoration of resources
- Handles retention policies and automatic cleanup
- Provides listing of trashed items with metadata
- Supports permanent deletion operations

### Domain Services

**Auth Service (`src/domain/services/auth_service.rs`)**
- Provides domain-level authentication logic
- Implements password validation and hashing
- Defines authentication policies and rules
- Manages token generation and validation
- Handles security-related domain operations

**I18n Service (`src/domain/services/i18n_service.rs`)**
- Defines domain-level internationalization interface
- Provides translation lookup capabilities
- Manages localization strategies
- Supports multiple languages and fallbacks
- Handles format localization for dates, numbers, etc.

**Path Service (`src/domain/services/path_service.rs`)**
- Manages domain-level path abstractions
- Provides path validation and normalization
- Handles path traversal and resolution
- Implements path security measures
- Supports different path formats and conventions

## Application Layer

The application layer orchestrates use cases by coordinating domain objects and providing services to the interfaces layer.

### Services

**File Service (`src/application/services/file_service.rs`)**
- Implements file-related use cases
- Coordinates between repositories for file operations
- Provides file upload, download, and listing functionality
- Handles error translation between layers
- Contains business logic for file operations

**Folder Service (`src/application/services/folder_service.rs`)**
- Implements folder management use cases
- Manages folder creation, listing, and hierarchy
- Coordinates between repositories for folder operations
- Maintains folder structure integrity
- Handles error translation for folder operations

**Auth Application Service (`src/application/services/auth_application_service.rs`)**
- Manages user authentication flows
- Implements login, logout, and session management
- Handles token generation and validation
- Coordinates with user repository for verification
- Manages password reset and account recovery

**File Management Service (`src/application/services/file_management_service.rs`)**
- Provides higher-level file operations
- Manages file uploads, versions, and metadata
- Handles file operations across repositories
- Coordinates transactional file operations
- Provides advanced file searching and filtering

**File Retrieval Service (`src/application/services/file_retrieval_service.rs`)**
- Specialized service for file content retrieval
- Optimizes file reading operations
- Provides streaming and download functionality
- Implements read-specific error handling
- Supports different retrieval patterns (whole file, ranges)

**File Upload Service (`src/application/services/file_upload_service.rs`)**
- Specialized service for handling file uploads
- Manages chunked and multipart uploads
- Provides validation during upload
- Handles large file uploads efficiently
- Supports upload resumption and integrity verification

**Search Service (`src/application/services/search_service.rs`)**
- Implements file and folder search functionality
- Provides text-based content searching
- Handles metadata-based filtering
- Supports sorting and pagination of results
- Optimizes search operations for performance

**Share Service (`src/application/services/share_service.rs`)**
- Implements file and folder sharing functionality
- Creates and manages share links
- Handles permission checking for shared resources
- Manages password protection for shares
- Processes access requests for shared content

**Trash Service (`src/application/services/trash_service.rs`)**
- Implements trash can functionality
- Manages moving items to trash and restoration
- Handles automatic cleanup of expired trash
- Coordinates with repositories for trash operations
- Maintains metadata for trashed items

**Recent Service (`src/application/services/recent_service.rs`)**
- Tracks recently accessed files
- Manages user-specific recent file lists
- Handles expiration of old entries
- Provides sorting and filtering of recent files
- Coordinates with file repository for metadata

**Favorites Service (`src/application/services/favorites_service.rs`)**
- Manages user favorite files and folders
- Provides adding and removing favorites
- Handles listing and sorting of favorites
- Coordinates with repositories for data consistency
- Maintains user-specific favorite lists

**I18n Application Service (`src/application/services/i18n_application_service.rs`)**
- Handles internationalization and localization
- Provides translation lookups for UI components
- Manages locale detection and setting
- Coordinates with i18n domain service
- Supports dynamic language switching

**Storage Mediator (`src/application/services/storage_mediator.rs`)**
- Coordinates between different storage repositories
- Manages transaction coordination
- Handles path resolution between storage layers
- Provides unified view of storage subsystems
- Optimizes operations across storage types

**Batch Operations (`src/application/services/batch_operations.rs`)**
- Implements batch processing for file operations
- Handles atomic multi-file operations
- Provides transaction support for batch operations
- Manages failure handling and partial success
- Optimizes performance for bulk operations

### Ports

**Inbound Ports (`src/application/ports/inbound.rs`)**
- Defines interfaces for external systems to use
- Contains use case interfaces for application services
- Specifies contracts for UI and API interactions
- Provides clear boundaries for application functionality
- Forms the primary API for interfaces layer

**Outbound Ports (`src/application/ports/outbound.rs`)**
- Defines interfaces used by application services
- Specifies contracts that infrastructure must implement
- Allows swapping infrastructure implementations
- Maintains dependency inversion principle
- Protects application layer from external dependencies

**Auth Ports (`src/application/ports/auth_ports.rs`)**
- Defines interfaces for authentication operations
- Specifies contracts for login, validation, and sessions
- Handles token generation and verification
- Provides user identity management
- Supports different authentication methods

**Storage Ports (`src/application/ports/storage_ports.rs`)**
- Defines interfaces for storage operations
- Specifies contracts for accessing persistent storage
- Handles file system and database interactions
- Provides transaction support for storage operations
- Supports different storage backends

**File Ports (`src/application/ports/file_ports.rs`)**
- Defines interfaces for file operations
- Contains file upload and retrieval use cases
- Specifies contracts for file management
- Handles file-specific error conditions
- Supports various file operation patterns

**Favorites Ports (`src/application/ports/favorites_ports.rs`)**
- Defines interfaces for favorites functionality
- Specifies contracts for favorite management
- Handles favorite-specific operations
- Provides user-specific favorite management
- Supports different favorite organization structures

**Recent Ports (`src/application/ports/recent_ports.rs`)**
- Defines interfaces for recent files functionality
- Specifies contracts for recent file tracking
- Handles history and access patterns
- Provides user-specific recent file handling
- Supports different recency algorithms

**Share Ports (`src/application/ports/share_ports.rs`)**
- Defines interfaces for sharing functionality
- Specifies contracts for share creation and access
- Handles permission verification for shares
- Provides link generation and management
- Supports different sharing models

**Trash Ports (`src/application/ports/trash_ports.rs`)**
- Defines interfaces for trash functionality
- Specifies contracts for trash operations
- Handles trash-specific workflows
- Provides retention and cleanup interfaces
- Supports different trash implementation strategies

### DTOs

**File DTO (`src/application/dtos/file_dto.rs`)**
- Data transfer object for file entities
- Provides serialization and API representation
- Translates between domain model and external interfaces
- Includes conversions to/from domain entities
- Contains file metadata for API responses

**Folder DTO (`src/application/dtos/folder_dto.rs`)**
- Data transfer object for folder entities
- Provides folder data for API responses
- Handles serialization and API representation
- Includes conversions to/from domain entities
- Contains folder structure information

**User DTO (`src/application/dtos/user_dto.rs`)**
- Data transfer object for user information
- Provides user data for API responses
- Handles serialization with sensitive data protection
- Includes conversions to/from domain entities
- Contains user profile information

**Share DTO (`src/application/dtos/share_dto.rs`)**
- Data transfer object for share information
- Provides share data for API responses
- Handles serialization of sharing details
- Includes conversions to/from domain entities
- Contains share link and permission data

**Trash DTO (`src/application/dtos/trash_dto.rs`)**
- Data transfer object for trashed items
- Provides trash information for API responses
- Handles serialization of trash metadata
- Includes conversions to/from domain entities
- Contains restoration information

**Pagination DTO (`src/application/dtos/pagination.rs`)**
- Handles pagination for list responses
- Provides page size and number information
- Supports offset and cursor-based pagination
- Includes metadata for total items and pages
- Facilitates consistent pagination across APIs

**Favorites DTO (`src/application/dtos/favorites_dto.rs`)**
- Data transfer object for favorites
- Provides favorites data for API responses
- Handles serialization of favorite items
- Includes conversions to/from domain entities
- Contains favorite metadata and organization

**Recent DTO (`src/application/dtos/recent_dto.rs`)**
- Data transfer object for recent files
- Provides recent items data for API responses
- Handles serialization of access history
- Includes conversions to/from domain entities
- Contains timing and access metadata

**Search DTO (`src/application/dtos/search_dto.rs`)**
- Data transfer object for search results
- Provides search data for API responses
- Handles serialization of search results
- Includes query and result metadata
- Contains relevance and ranking information

**I18n DTO (`src/application/dtos/i18n_dto.rs`)**
- Data transfer object for internationalization
- Provides language and translation data
- Handles serialization of language resources
- Includes locale and preference information
- Contains translation bundle structures

### Adapters

**WebDAV Adapter (`src/application/adapters/webdav_adapter.rs`)**
- Adapts between OxiCloud domain models and WebDAV protocol
- Handles XML parsing and generation for WebDAV operations
- Implements property handling for WebDAV (PROPFIND, PROPPATCH)
- Provides WebDAV-specific error handling
- Translates between file operations and WebDAV methods

### Transactions

**Storage Transaction (`src/application/transactions/storage_transaction.rs`)**
- Manages transactional operations for storage
- Implements transaction boundaries and commits
- Provides rollback capabilities on failure
- Ensures consistency across multiple operations
- Handles transaction isolation levels

## Infrastructure Layer

This layer provides concrete implementations of repository interfaces and technical services.

### Repositories (Implementations)

**File FS Repository (`src/infrastructure/repositories/file_fs_repository.rs`)**
- Implements FileRepository interface for filesystem storage
- Manages physical file operations on disk
- Handles file content reading and writing
- Implements optimized large file handling
- Provides metadata caching for performance

**File FS Read Repository (`src/infrastructure/repositories/file_fs_read_repository.rs`)**
- Specialized repository for read-only file operations
- Optimized for high-performance file retrieval
- Implements caching for frequently accessed files
- Supports streaming of large files
- Handles content type detection and verification

**File FS Write Repository (`src/infrastructure/repositories/file_fs_write_repository.rs`)**
- Specialized repository for file write operations
- Handles atomic file writes with transaction support
- Implements optimized large file writes
- Manages file locking for concurrent writes
- Provides integrity verification for written files

**File FS Repository Trash (`src/infrastructure/repositories/file_fs_repository_trash.rs`)**
- Extends file repository with trash functionality
- Implements soft delete operations for files
- Manages restoration from trash
- Handles automatic cleanup of expired trash
- Maintains metadata for trashed files

**Folder FS Repository (`src/infrastructure/repositories/folder_fs_repository.rs`)**
- Implements FolderRepository interface for filesystem
- Creates and manages directory structures
- Handles folder listing and hierarchy traversal
- Implements folder permissions and ownership
- Provides optimization for deep folder structures

**Folder FS Repository Trash (`src/infrastructure/repositories/folder_fs_repository_trash.rs`)**
- Extends folder repository with trash functionality
- Implements soft delete for directories
- Handles recursive trash operations for folders
- Manages restoration of folder hierarchies
- Maintains metadata for trashed folders

**Share FS Repository (`src/infrastructure/repositories/share_fs_repository.rs`)**
- Implements ShareRepository for filesystem-based sharing
- Manages share records and permissions
- Handles link generation and validation
- Provides access control for shared resources
- Supports share expiration and revocation

**Trash FS Repository (`src/infrastructure/repositories/trash_fs_repository.rs`)**
- Implements TrashRepository for filesystem
- Manages trash directory structure
- Handles metadata for trashed items
- Implements cleanup policies for expired trash
- Supports permanent deletion operations

**Session PG Repository (`src/infrastructure/repositories/pg/session_pg_repository.rs`)**
- Implements session storage using PostgreSQL
- Manages user sessions and authentication state
- Handles session creation, validation, and expiration
- Provides secure token management
- Supports multiple concurrent sessions

**User PG Repository (`src/infrastructure/repositories/pg/user_pg_repository.rs`)**
- Implements UserRepository with PostgreSQL
- Stores user accounts and profile information
- Handles user queries and updates
- Manages user roles and permissions
- Supports user search and filtering

**File Metadata Manager (`src/infrastructure/repositories/file_metadata_manager.rs`)**
- Manages file metadata independently of content
- Handles extended attributes for files
- Provides caching for frequently accessed metadata
- Optimizes metadata operations
- Supports custom metadata fields

**File Path Resolver (`src/infrastructure/repositories/file_path_resolver.rs`)**
- Resolves logical paths to physical storage locations
- Handles path normalization and validation
- Provides path translation between different systems
- Supports virtual paths and redirections
- Optimizes path resolution for nested structures

**Parallel File Processor (`src/infrastructure/repositories/parallel_file_processor.rs`)**
- Implements parallel processing for large files
- Optimizes file operations with multi-threading
- Provides chunked reading and writing
- Handles load balancing for file operations
- Implements backpressure mechanisms

### Services

**ID Mapping Service (`src/infrastructure/services/id_mapping_service.rs`)**
- Manages mapping between UUIDs and filesystem paths
- Provides persistent ID generation and lookup
- Handles path changes while maintaining stable IDs
- Implements caching for frequently accessed mappings
- Ensures consistency between IDs and paths

**Buffer Pool (`src/infrastructure/services/buffer_pool.rs`)**
- Manages memory buffers for file operations
- Implements pooling for optimal memory usage
- Provides buffer recycling to reduce allocations
- Handles buffer sizing for different operations
- Implements thread-safe buffer management

**Cache Manager (`src/infrastructure/services/cache_manager.rs`)**
- Provides application-wide caching services
- Implements multiple cache levels (memory, disk)
- Handles cache invalidation and consistency
- Manages cache size limits and eviction
- Provides statistics for cache performance

**Compression Service (`src/infrastructure/services/compression_service.rs`)**
- Implements data compression for files and responses
- Supports multiple compression algorithms
- Provides on-the-fly compression for API responses
- Handles selective compression based on file types
- Optimizes compression levels for different content

**File System I18n Service (`src/infrastructure/services/file_system_i18n_service.rs`)**
- Implements I18n service using filesystem storage
- Loads translations from JSON files
- Handles language detection and fallbacks
- Provides translation lookups for UI components
- Supports dynamic language switching

**File Metadata Cache (`src/infrastructure/services/file_metadata_cache.rs`)**
- Provides caching for file metadata
- Optimizes repeated metadata access
- Implements cache invalidation strategies
- Handles concurrent access to metadata
- Supports different cache levels (memory, persistent)

**ID Mapping Optimizer (`src/infrastructure/services/id_mapping_optimizer.rs`)**
- Optimizes ID-to-path mapping operations
- Implements batch processing for mapping updates
- Provides preloading for frequently accessed mappings
- Handles compaction of mapping storage
- Optimizes lookup performance for large mappings

**Zip Service (`src/infrastructure/services/zip_service.rs`)**
- Provides ZIP archive creation and extraction
- Supports on-the-fly compression for downloads
- Handles large directory archiving
- Implements streaming ZIP generation
- Provides progress tracking for large operations

**Trash Cleanup Service (`src/infrastructure/services/trash_cleanup_service.rs`)**
- Manages automatic cleanup of expired trash items
- Implements retention policy enforcement
- Provides scheduled cleanup operations
- Handles graceful cleanup with resource limits
- Supports custom cleanup rules

## Interfaces Layer

This layer handles external communication, including API endpoints and web interfaces.

### API Handlers

**File Handler (`src/interfaces/api/handlers/file_handler.rs`)**
- Handles HTTP requests for file operations
- Processes file uploads with multipart support
- Provides file downloads with optional compression
- Implements CRUD operations for files
- Manages error responses and status codes

**Folder Handler (`src/interfaces/api/handlers/folder_handler.rs`)**
- Handles HTTP requests for folder operations
- Processes folder creation and listing
- Implements CRUD operations for directories
- Provides folder hierarchy navigation
- Manages error responses for folder operations

**Auth Handler (`src/interfaces/api/handlers/auth_handler.rs`)**
- Handles authentication-related API endpoints
- Processes login, logout, and registration
- Manages session tokens and refresh
- Implements password reset functionality
- Provides authentication status information

**Share Handler (`src/interfaces/api/handlers/share_handler.rs`)**
- Handles file and folder sharing endpoints
- Processes share creation and management
- Provides access to shared resources
- Handles permission verification
- Manages share links and passwords

**Trash Handler (`src/interfaces/api/handlers/trash_handler.rs`)**
- Handles trash-related API endpoints
- Processes moving items to trash
- Provides trash listing and filtering
- Handles restoration from trash
- Manages permanent deletion operations

**Search Handler (`src/interfaces/api/handlers/search_handler.rs`)**
- Handles search-related API endpoints
- Processes text search queries
- Provides filtering and sorting options
- Handles pagination for search results
- Manages relevance scoring for results

**Recent Handler (`src/interfaces/api/handlers/recent_handler.rs`)**
- Handles recently accessed files endpoints
- Provides listing and filtering of recent files
- Manages user-specific recent history
- Handles pagination for recent items
- Provides sorting options for recent files

**Favorites Handler (`src/interfaces/api/handlers/favorites_handler.rs`)**
- Handles user favorites endpoints
- Processes adding and removing favorites
- Provides listing and filtering of favorites
- Manages user-specific favorite collections
- Handles sorting and organization of favorites

**I18n Handler (`src/interfaces/api/handlers/i18n_handler.rs`)**
- Handles internationalization endpoints
- Provides language selection and detection
- Serves translation resources
- Manages locale settings
- Handles language preference persistence

**Batch Handler (`src/interfaces/api/handlers/batch_handler.rs`)**
- Handles batch operation endpoints
- Processes multiple operations in a single request
- Provides transaction support for batches
- Handles partial success scenarios
- Manages comprehensive error reporting

**WebDAV Handler (`src/interfaces/api/handlers/webdav_handler.rs`)**
- Implements WebDAV protocol (RFC 4918) endpoints
- Handles WebDAV methods (PROPFIND, PROPPATCH, etc.)
- Provides file system access via HTTP
- Manages WebDAV properties and locks
- Supports third-party WebDAV clients

### API Routes

**Routes (`src/interfaces/api/routes.rs`)**
- Defines API routes and URL structure
- Maps endpoints to appropriate handlers
- Configures middleware for routes
- Handles versioning for API endpoints
- Provides documentation integration

### Middleware

**Auth Middleware (`src/interfaces/middleware/auth.rs`)**
- Handles authentication for API requests
- Verifies tokens and sessions
- Provides user context for handlers
- Manages authentication errors
- Supports different authentication methods

**Cache Middleware (`src/interfaces/middleware/cache.rs`)**
- Implements response caching
- Handles cache headers and validation
- Provides conditional request processing
- Manages cache invalidation
- Optimizes for different content types

**Redirect Middleware (`src/interfaces/middleware/redirect.rs`)**
- Handles HTTP redirects
- Manages URL normalization
- Provides permanent and temporary redirects
- Handles protocol upgrades (HTTP to HTTPS)
- Supports path-based redirections

### Web Interface

**Web Module (`src/interfaces/web/mod.rs`)**
- Coordinates web interface components
- Manages static file serving
- Provides web application integration
- Handles web-specific middleware
- Supports single-page application routing

## Common Layer

This layer provides shared utilities and configurations used across the application.

**Config (`src/common/config.rs`)**
- Manages application configuration
- Loads settings from environment and files
- Provides typed configuration access
- Handles configuration validation
- Supports different environments (dev, prod)

**Errors (`src/common/errors.rs`)**
- Defines error types and handling
- Provides consistent error formatting
- Implements error context and wrapping
- Handles error translation between layers
- Supports error categorization and logging

**DI (`src/common/di.rs`)**
- Implements dependency injection
- Manages service lifecycles
- Provides application state container
- Handles service resolution and registration
- Supports scoped service instances

**DB (`src/common/db.rs`)**
- Manages database connections
- Provides connection pooling
- Handles database migrations
- Implements query helpers
- Supports transaction management

**Cache (`src/common/cache.rs`)**
- Provides generic caching facilities
- Implements different cache strategies
- Handles cache key generation
- Manages cache invalidation
- Supports distributed caching

**Auth Factory (`src/common/auth_factory.rs`)**
- Creates authentication components
- Configures auth providers based on settings
- Provides factory methods for auth services
- Handles auth strategy selection
- Supports multiple authentication methods