+
+ A fast self-hosted cloud for people who want files, calendars, contacts, and office editing without dragging a heavy stack behind them.
+
- [](https://opensource.org/licenses/MIT)
- [](https://github.com/diocrafts/OxiCloud/releases)
- [](https://github.com/diocrafts/OxiCloud/actions/workflows/ci.yml)
- [](https://www.rust-lang.org/)
- [](https://hub.docker.com/r/diocrafts/oxicloud)
- [](https://github.com/diocrafts/OxiCloud/stargazers)
- [](https://github.com/diocrafts/OxiCloud/issues)
- [](https://github.com/diocrafts/OxiCloud/commits/main)
+
+ Documentation
+ ·
+ Quick Start
+ ·
+ Star OxiCloud
+ ·
+ Request a Feature
+ ·
+ Supported Clients
+ ·
+ Project Status
+
-[**Documentation**](https://diocrafts.github.io/OxiCloud/)
+
+ 
+ 
+ 
+ 
+ 
+ 
+
+
+ If OxiCloud saves you setup time, RAM, or complexity, give it a star.
+ If something is missing, ask for a feature or request a docs improvement.
+
-NextCloud was too slow on my home server. So I built OxiCloud — a complete cloud platform written in Rust that runs on minimal hardware and stays out of your way.
+
-
+## Why People Try OxiCloud
-
+OxiCloud is aimed at self-hosters, home labs, and small teams who want the useful parts of a cloud suite without the operational drag of a traditional PHP stack.
+What pulls people in:
+- Standard protocols first: WebDAV, CalDAV, and CardDAV are built in
+- Useful product surface already there: files, previews, sharing, trash, search, favorites, and recent items
+- Modern auth and admin basics: OIDC/SSO, quotas, roles, and shared links
+- Better interoperability: native desktop and mobile clients work without custom sync tooling for basic access
+- Lower deployment friction: Docker Compose, environment-based configuration, Helm chart, and Nix module
-## OxiCloud vs NextCloud
-
-| Metric | OxiCloud | NextCloud |
-|--------|----------|-----------|
-| **Language** | Rust (compiled, zero-cost abstractions) | PHP (interpreted) |
-| **Docker image** | ~40 MB (Alpine, static binary) | ~1 GB+ (Apache + PHP + modules) |
-| **Idle RAM** | ~30–50 MB | ~250–512 MB |
-| **Cold start** | < 1 s | 5–15 s |
-| **CPU at idle** | ~0 % | 1–5 % (cron, background jobs) |
-| **Min. hardware** | 1 vCPU / 512 MB RAM | 2 vCPU / 2 GB RAM (recommended) |
-| **Concurrent uploads** | Parallel chunked (TUS-like), async I/O | Sequential PHP workers |
-| **File dedup** | SHA-256 content-addressable, ref-counting | None (each user = full copy) |
-| **DB connections** | Dual pool (user + maintenance) | Single pool, background jobs compete |
-| **LTO + PGO** | Fat LTO, codegen-units=1, opt-level=3 | N/A (interpreted) |
-| **Dependencies** | Single binary + PostgreSQL | PHP, Apache/Nginx, Redis, Cron, … |
-| **WebDAV** | Built-in (RFC 4918, PROPFIND streaming) | Built-in |
-| **CalDAV / CardDAV** | Built-in | Via apps |
-| **WOPI (Office editing)** | Built-in (Collabora / OnlyOffice) | Via apps |
-| **OIDC / SSO** | Built-in (Keycloak, Authentik, …) | Via apps |
-
-> **Note:** NextCloud is a mature, feature-rich ecosystem. OxiCloud targets users who prioritise raw performance, simplicity, and low resource usage over plugin breadth.
-
----
-
-## Features
-
-### Storage & Files
-- **Upload / download / organise** — drag-and-drop, multi-file, grid & list views
-- **Chunked uploads** — TUS-like protocol, parallel chunks, resumable, MD5 integrity
-- **File deduplication** — SHA-256 content-addressable blobs with automatic ref-counting
-- **Adaptive compression** — zstd / gzip selected per MIME type
-- **Trash bin** — soft-delete, restore, auto-purge by retention policy
-- **Favourites & recent files**
-- **Full-text search** — by name, type, date range, size, recursive subtree (ltree)
-- **MIME magic-byte detection** — `infer` crate, not just extension guessing
-- **Inline preview** — images, PDF, text, audio & video player modal
-- **Thumbnails & transcoding** — WebP / AVIF on-the-fly via `image` crate
-
-### Protocols
-- **WebDAV** — RFC 4918, streaming PROPFIND, locking, compatible with all major clients
-- **CalDAV** — calendar sync (Thunderbird, GNOME Calendar, iOS, DAVx⁵, …)
-- **CardDAV** — contacts sync with vCard support
-- **WOPI** — edit Office docs in Collabora Online or OnlyOffice
-- **REST API** — complete JSON API for all operations
-
-### Security & Auth
-- **JWT authentication** with refresh tokens
-- **Argon2id** password hashing
-- **OIDC / SSO** — Keycloak, Authentik, Authelia, Google, Azure AD…
-- **Role-based access** — admin / user, per-folder permissions
-- **Storage quotas** per user
-- **Shared links** with optional password protection
-
-### Infrastructure
-- **Single binary** — no runtime, no interpreter, no framework overhead
-- **~40 MB Docker image** (Alpine)
-- **Dual DB pool** — dedicated maintenance pool so background tasks never starve user queries
-- **LTO-optimised release** — fat LTO, 1 codegen-unit, `opt-level = 3`, stripped
-- **Write-behind caching** (moka) — sub-millisecond hot reads
-- **222+ automated tests** — `cargo test` on every push (CI)
-- **14 languages** — EN, ES, DE, FR, IT, PT, NL, ZH, JA, KO, AR, HI, FA, RU
-
----
-
-## Feature Status
-
-| Feature | Status | Notes |
-|---------|--------|-------|
-| **File storage & upload** | ✅ Working | Chunked uploads, deduplication, thumbnails |
-| **WebDAV** | ✅ Working | Fully compatible with major clients |
-| **CalDAV (Thunderbird, iOS)** | ✅ Working | Calendar sync functional |
-| **CardDAV (Thunderbird, iOS)** | ✅ Working | Contacts sync functional |
-| **DAVx⁵ (Android)** | ⚠️ Partial | File sync works; calendar/contacts in progress |
-| **WOPI / Office editing** | ✅ Working | Collabora/OnlyOffice integration |
-| **OIDC / SSO** | ✅ Working | Keycloak, Authentik, Google, Azure AD |
-| **Trash / recycle bin** | ✅ Working | Soft-delete with restore |
-| **Full-text search** | ✅ Working | Recursive subtree search |
-| **Shared links** | ✅ Working | Optional password protection |
-| **Music library & playlists** | ✅ Working | Streaming player, drag-and-drop reorder |
-| **Photo gallery** | ✅ Working | Day/month/year views, multi-select |
-| **Desktop sync client** | ❌ Planned | Not yet available |
-| **Android / iOS app** | ❌ Planned | Not yet available |
-| **End-to-end encryption** | ❌ Planned | Roadmap item |
-
-> **Note:** The DAVx⁵ Android app currently works for file sync via WebDAV, but calendar and contacts sync via CalDAV/CardDAV is still being refined. Use Thunderbird or iOS native clients for full CalDAV/CardDAV support.
-
----
+> OxiCloud is not trying to mirror the full plugin ecosystem of Nextcloud. It is designed for a smaller stack, fast startup, and standards-based interoperability.
## Quick Start
-### Docker (recommended)
+### Docker Compose
+
+Requires Docker and Docker Compose.
```bash
-git clone https://github.com/DioCrafts/oxicloud.git
-cd oxicloud
-
-# Copy and optionally edit environment
+git clone https://github.com/DioCrafts/OxiCloud.git
+cd OxiCloud
cp example.env .env
+# If users will access OxiCloud through a domain or reverse proxy,
+# set OXICLOUD_BASE_URL in .env before the first login.
docker compose up -d
```
-Open **http://localhost:8086**. That's it.
+Open `http://localhost:8086`.
-If you want to access the server remotely set the OXICLOUD_BASE_URL to your server's domain/port or the authentication will fail after setting up the admin user.
+### Run from source
-### From source
-
-Requires **Rust 1.93+** and **PostgreSQL 13+**.
+Requires Rust 1.93+ and PostgreSQL.
```bash
-git clone https://github.com/DioCrafts/oxicloud.git
-cd oxicloud
+git clone https://github.com/DioCrafts/OxiCloud.git
+cd OxiCloud
+cp example.env .env
-# Configure database
-echo "DATABASE_URL=postgres://user:pass@localhost/oxicloud" > .env
-
-# Build optimised binary
-cargo build --release
-
-# Start the server (migrations run automatically)
-cargo run --release
+# If PostgreSQL runs on your host instead of Docker, update both
+# OXICLOUD_DB_CONNECTION_STRING and DATABASE_URL to use localhost:5432.
+cargo run
```
----
+Deployment details: [deployment guide](docs/config/deployment.md) · [example.env](example.env)
-## Client Setup
+## What You Get
-OxiCloud speaks standard protocols — any WebDAV / CalDAV / CardDAV client works:
+| Area | Included |
+| --- | --- |
+| Files | Multi-file upload, folders, inline previews, thumbnails, chunked uploads, deduplication, trash |
+| Sync and clients | WebDAV, CalDAV, CardDAV, native OS clients, Thunderbird, DAVx5 |
+| Security | JWT auth, Argon2id, OIDC/SSO, shared links, quotas, admin/user roles |
+| Integrations | REST API and WOPI for Collabora or OnlyOffice |
+| Operations | Docker image, Docker Compose, env-driven config, PostgreSQL backend |
+| Project tooling | Architecture docs, Helm chart, Nix module, CI |
-| Client | Protocol | URL |
-|--------|----------|-----|
-| Windows Explorer | WebDAV | `http://host:8086/webdav/` |
-| macOS Finder | WebDAV | `http://host:8086/webdav/` |
-| Nautilus / Dolphin | WebDAV | `dav://host:8086/webdav/` |
-| Thunderbird (calendar) | CalDAV | `http://host:8086/caldav/` |
-| Thunderbird (contacts) | CardDAV | `http://host:8086/carddav/` |
-| DAVx⁵ (Android) | CalDAV + CardDAV | `http://host:8086/` |
-| GNOME Calendar | CalDAV | `http://host:8086/caldav/` |
-| GNOME Contacts | CardDAV | `http://host:8086/carddav/` |
-| Collabora / OnlyOffice | WOPI | See [WOPI docs](doc/wopi-integration.md) |
+## Supported Clients
-For detailed setup guides: [WebDAV](doc/webdav-integration-guide.md) · [CalDAV](doc/caldav-technical-spec.md) · [CardDAV](doc/carddav-technical-spec.md) · [OIDC/SSO](doc/oidc-integration.md)
+OxiCloud uses standard DAV protocols, so it works with native clients instead of requiring a custom sync stack for basic access.
----
+| Use case | URL |
+| --- | --- |
+| Files via WebDAV | `https://your-host/webdav/` |
+| Calendars via CalDAV | `https://your-host/caldav/` |
+| Contacts via CardDAV | `https://your-host/carddav/` |
-## Architecture
+Common clients that work well:
-Clean / Hexagonal architecture — each layer depends only on the one below:
+- macOS Finder
+- Windows Explorer
+- GNOME Files and KDE Dolphin
+- Thunderbird
+- Apple Calendar and Contacts
+- DAVx5 on Android
-```
-┌───────────────────────────────────────────────────────────────┐
-│ Interfaces │ REST API, WebDAV, CalDAV, CardDAV, WOPI │
-├───────────────────────────────────────────────────────────────┤
-│ Application │ Use cases, DTOs, port definitions │
-├───────────────────────────────────────────────────────────────┤
-│ Domain │ Entities, business rules, repository traits │
-├───────────────────────────────────────────────────────────────┤
-│ Infrastructure│ PostgreSQL, filesystem, caching, auth │
-└───────────────────────────────────────────────────────────────┘
-```
+Client setup guides: [DAV client setup](docs/guide/dav-client-setup.md) · [WebDAV guide](docs/guide/webdav.md) · [CalDAV & CardDAV guide](docs/guide/caldav-carddav.md)
-Swap the database, add a new protocol, or change auth — without touching business logic.
+## Project Status
-For a deep dive: [Internal Architecture](doc/internal-architecture.md) · [Caching](doc/caching-architecture.md) · [DB Transactions](doc/database-transactions.md)
+OxiCloud is actively developed and already covers the core self-hosted cloud workflow.
----
+| Capability | Status | Notes |
+| --- | --- | --- |
+| File storage and web UI | Ready | Uploads, previews, sharing, trash, and search |
+| WebDAV | Ready | Standard file access for desktop and mobile clients |
+| CalDAV and CardDAV | Ready | Working with Thunderbird, Apple clients, and others |
+| OIDC / SSO | Ready | Documentation and config examples included |
+| WOPI office editing | Ready | Works with Collabora or OnlyOffice |
+| DAVx5 Android support | Partial | File sync works well; calendar and contact behavior is still being refined |
+| Desktop sync client | Planned | Not yet available |
+| Mobile apps | Planned | Not yet available |
+| End-to-end encryption | Planned | Roadmap item |
-## Configuration
+Roadmap: [TODO-LIST.md](TODO-LIST.md)
-All config via environment variables (see [`example.env`](example.env)):
+## Help Shape OxiCloud
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `OXICLOUD_STORAGE_PATH` | `./storage` | Root directory for file storage |
-| `OXICLOUD_SERVER_PORT` | `8086` | HTTP listen port |
-| `OXICLOUD_DB_CONNECTION_STRING` | — | PostgreSQL connection string |
-| `OXICLOUD_JWT_SECRET` | random | Token signing key (set in production!) |
-| `OXICLOUD_OIDC_ENABLED` | `false` | Enable OpenID Connect SSO |
-| `OXICLOUD_WOPI_ENABLED` | `false` | Enable Collabora / OnlyOffice editing |
-| `OXICLOUD_ENABLE_AUTH` | `true` | Toggle authentication |
-| `OXICLOUD_ENABLE_TRASH` | `true` | Toggle trash / recycle bin |
+If you want OxiCloud to get better faster, use the repo like a product feedback loop, not just a code dump.
-Full reference: [`example.env`](example.env) · [Deployment guide](https://diocrafts.github.io/OxiCloud/config/deployment) · [OIDC setup](https://diocrafts.github.io/OxiCloud/config/oidc)
+- Give it a star if you want more people to discover the project: [Star OxiCloud](https://github.com/DioCrafts/OxiCloud/stargazers)
+- Propose missing functionality: [feature request](https://github.com/DioCrafts/OxiCloud/issues/new?template=feature_request.md)
+- Point out confusing onboarding or weak docs: [documentation request](https://github.com/DioCrafts/OxiCloud/issues/new?template=documentation_request.md)
+- Report breakage or regressions: [bug report](https://github.com/DioCrafts/OxiCloud/issues/new?template=bug_report.md)
+- Build it with us: [CONTRIBUTING.md](CONTRIBUTING.md)
----
+The best feature ideas usually come from real deployment pain. If you hit friction, open an issue and describe the workflow you want.
-## Development
+## Architecture and Deployment
-### Server side
+OxiCloud follows a clean, hexagonal architecture so protocol handlers, business logic, and infrastructure stay separated.
-```bash
-cargo build # Dev build
-cargo run # Run locally
-cargo test --workspace # 112 tests
-cargo clippy -- -D warnings # Lint (zero warnings policy)
-cargo fmt --all --check # Format check
-RUST_LOG=debug cargo run # Debug logging
-```
+- Backend: Rust + Axum
+- Database: PostgreSQL
+- Configuration: environment variables
+- Default deployment: Docker Compose
+- Additional packaging: [Helm chart](charts/oxicloud) and [Nix module](tools/nix/module.nix)
-### Client side
+Architecture docs: [internal architecture](docs/architecture/index.md) · [caching architecture](docs/architecture/caching.md) · [database transactions](docs/architecture/database-transactions.md) · [storage safety](docs/architecture/file-system-safety.md)
-Run server in dev profile:
+## Configuration and Integrations
-```bash
-PROFILE=dev cargo run
-```
+Start with [example.env](example.env). The most important settings are:
-CSS & JS linter is `biome` (can be installed via `cargo install biome-cli` or on MacOS: `brew install biome`)
+- `OXICLOUD_BASE_URL` for reverse proxies, domains, and external access
+- `OXICLOUD_DB_CONNECTION_STRING` for PostgreSQL
+- `OXICLOUD_OIDC_ENABLED` and related settings for SSO
+- `OXICLOUD_WOPI_ENABLED` and discovery URL for office editing
+- `MIMALLOC_PURGE_DELAY=0` for lower idle RSS in constrained environments
-### Project stats
-
-| Metric | Value |
-|--------|-------|
-| Rust source files | 170 |
-| Lines of code | ~50 000 |
-| Automated tests | 222+ |
-| Documentation pages | 35+ |
-
----
+Integration docs: [OIDC setup](docs/config/oidc.md) · [OIDC architecture](docs/config/oidc.md) · [OIDC config examples](docs/config/oidc-config-examples.md) · [WOPI integration](docs/config/wopi.md)
## Documentation
-📖 **Full documentation:** [**diocrafts.github.io/OxiCloud**](https://diocrafts.github.io/OxiCloud/)
+- Docs site: [diocrafts.github.io/OxiCloud](https://diocrafts.github.io/OxiCloud/)
+- Deployment: [docs/config/deployment.md](docs/config/deployment.md)
+- Batch operations: [docs/guide/batch-operations.md](docs/guide/batch-operations.md)
+- Search: [docs/guide/search.md](docs/guide/search.md)
+- Thumbnails and transcoding: [docs/guide/thumbnails-and-transcoding.md](docs/guide/thumbnails-and-transcoding.md)
+- Deduplication: [docs/guide/deduplication.md](docs/guide/deduplication.md)
-| Topic | Online | Source |
-|-------|--------|--------|
-| Quick Start | [Guide](https://diocrafts.github.io/OxiCloud/guide/installation) | [doc/deployment.md](doc/deployment.md) |
-| WebDAV | [Guide](https://diocrafts.github.io/OxiCloud/guide/webdav) | [doc/webdav-integration-guide.md](doc/webdav-integration-guide.md) |
-| CalDAV / CardDAV | [Guide](https://diocrafts.github.io/OxiCloud/guide/caldav-carddav) | [doc/caldav-technical-spec.md](doc/caldav-technical-spec.md) |
-| OIDC / SSO | [Guide](https://diocrafts.github.io/OxiCloud/config/oidc) | [doc/oidc-integration.md](doc/oidc-integration.md) |
-| WOPI (Office) | [Guide](https://diocrafts.github.io/OxiCloud/config/wopi) | [doc/wopi-integration.md](doc/wopi-integration.md) |
-| Architecture | [Guide](https://diocrafts.github.io/OxiCloud/architecture/) | [doc/internal-architecture.md](doc/internal-architecture.md) |
-| All env variables | [Reference](https://diocrafts.github.io/OxiCloud/config/env) | [`example.env`](example.env) |
+## Development
----
+```bash
+cargo fmt --all --check
+cargo clippy -- -D warnings
+cargo test --workspace
+```
-## Roadmap
-
-Check [TODO-LIST.md](TODO-LIST.md) for the full roadmap. Highlights:
-
-- [ ] File versioning & diff viewer
-- [ ] End-to-end encryption
-- [ ] Desktop sync client (Rust)
-- [ ] Android / iOS app
-- [ ] OCR & intelligent tagging
-- [ ] Automated workflows
-
----
+Contributor guide: [CONTRIBUTING.md](CONTRIBUTING.md)
## Contributing
-The project is actively developed. Contributions welcome!
+Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community expectations.
-Read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a PR. Follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+If you are not ready to code yet, starring the project and opening a precise feature request is still a meaningful contribution.
## License
-MIT — see [LICENSE](LICENSE).
-
----
-
-## Star History
-
-
-
----
-
-Questions? [Open an issue](https://github.com/DioCrafts/OxiCloud/issues). Want to help? PRs welcome.
+MIT. See [LICENSE](LICENSE).
diff --git a/doc/ADMIN-SETTINGS1.md b/doc/ADMIN-SETTINGS1.md
deleted file mode 100644
index 69a35387..00000000
--- a/doc/ADMIN-SETTINGS1.md
+++ /dev/null
@@ -1,162 +0,0 @@
-# OxiCloud — Admin Settings
-
-## Overview
-
-OxiCloud provides an admin panel API for managing server settings, OIDC configuration, user management, and dashboard statistics. All admin endpoints require a valid JWT token with `role = "admin"`.
-
-## Architecture
-
-| Layer | Component | File |
-|---|---|---|
-| Domain Port | `SettingsRepository` trait | `src/domain/repositories/settings_repository.rs` |
-| Application Service | `AdminSettingsService` | `src/application/services/admin_settings_service.rs` |
-| Application DTOs | Settings and user management DTOs | `src/application/dtos/settings_dto.rs` |
-| Infrastructure | `SettingsPgRepository` | `src/infrastructure/repositories/pg/settings_pg_repository.rs` |
-| Interfaces | `admin_handler` functions | `src/interfaces/api/handlers/admin_handler.rs` |
-
-## REST API
-
-All routes under `/api/admin`, require admin JWT.
-
-### Settings
-
-| Method | Path | Handler | Description |
-|---|---|---|---|
-| `GET` | `/api/admin/settings/oidc` | `get_oidc_settings` | Get current OIDC configuration |
-| `PUT` | `/api/admin/settings/oidc` | `save_oidc_settings` | Update OIDC configuration |
-| `POST` | `/api/admin/settings/oidc/test` | `test_oidc_connection` | Test OIDC provider connectivity |
-| `GET` | `/api/admin/settings/general` | `get_general_settings` | Get general server settings |
-
-### Dashboard
-
-| Method | Path | Handler | Description |
-|---|---|---|---|
-| `GET` | `/api/admin/dashboard` | `get_dashboard_stats` | Server dashboard statistics |
-
-### User Management
-
-| Method | Path | Handler | Description |
-|---|---|---|---|
-| `GET` | `/api/admin/users` | `list_users` | List all users (paginated) |
-| `GET` | `/api/admin/users/{id}` | `get_user` | Get user details |
-| `DELETE` | `/api/admin/users/{id}` | `delete_user` | Delete a user |
-| `PUT` | `/api/admin/users/{id}/role` | `update_user_role` | Change user role |
-| `PUT` | `/api/admin/users/{id}/active` | `update_user_active` | Activate/deactivate user |
-| `PUT` | `/api/admin/users/{id}/quota` | `update_user_quota` | Set storage quota |
-
-### Safety Guards
-
-- **Self-deletion blocked**: Admins cannot delete their own account
-- **Self-role-change blocked**: Admins cannot change their own role
-- **Self-deactivation blocked**: Admins cannot deactivate themselves
-
-## OIDC Settings Management
-
-### Get Settings Response
-
-```json
-{
- "enabled": true,
- "issuer_url": "https://keycloak.example.com/realms/main",
- "client_id": "oxicloud",
- "client_secret_set": true,
- "scopes": "openid profile email",
- "auto_provision": true,
- "admin_groups": "oxicloud-admins",
- "disable_password_login": false,
- "provider_name": "KeyCloak",
- "callback_url": "https://oxicloud.example.com/api/auth/oidc/callback",
- "env_overrides": ["issuer_url", "client_id"]
-}
-```
-
-The `env_overrides` field lists which settings are overridden by environment variables (env vars take priority over DB settings).
-
-### Save Settings Request
-
-```json
-{
- "enabled": true,
- "issuer_url": "https://keycloak.example.com/realms/main",
- "client_id": "oxicloud",
- "client_secret": "new-secret",
- "scopes": "openid profile email",
- "auto_provision": true,
- "admin_groups": "oxicloud-admins",
- "disable_password_login": false,
- "provider_name": "KeyCloak"
-}
-```
-
-After saving, the service hot-reloads OIDC via `auth_app_service.reload_oidc()` or `disable_oidc()`.
-
-### Test OIDC Connection
-
-```json
-// Request
-{ "issuer_url": "https://keycloak.example.com/realms/main" }
-
-// Response
-{
- "success": true,
- "message": "Successfully connected to OIDC provider",
- "issuer": "https://keycloak.example.com/realms/main",
- "authorization_endpoint": "https://keycloak.example.com/realms/main/protocol/openid-connect/auth",
- "token_endpoint": "https://keycloak.example.com/realms/main/protocol/openid-connect/token",
- "userinfo_endpoint": "https://keycloak.example.com/realms/main/protocol/openid-connect/userinfo",
- "provider_name_suggestion": "KeyCloak"
-}
-```
-
-## Dashboard Statistics
-
-```json
-{
- "server_version": "0.3.2",
- "auth_enabled": true,
- "oidc_configured": true,
- "quotas_enabled": false,
- "total_users": 42,
- "active_users": 38,
- "admin_users": 2,
- "total_quota_bytes": 107374182400,
- "total_used_bytes": 53687091200,
- "storage_usage_percent": 50.0,
- "users_over_80_percent": 5,
- "users_over_quota": 1
-}
-```
-
-## User Management DTOs
-
-```rust
-pub struct UpdateUserRoleDto { pub role: String } // "user" | "admin"
-pub struct UpdateUserActiveDto { pub active: bool }
-pub struct UpdateUserQuotaDto { pub quota_bytes: i64 }
-pub struct ListUsersQueryDto { pub limit: Option, pub offset: Option }
-```
-
-## Config Priority
-
-Settings are resolved with the following priority (highest first):
-
-1. **Environment variables** (`OXICLOUD_OIDC_*`)
-2. **Database settings** (`auth.admin_settings` table)
-3. **Defaults**
-
-## Database Schema
-
-```sql
-CREATE TABLE IF NOT EXISTS auth.admin_settings (
- key TEXT PRIMARY KEY,
- value TEXT NOT NULL,
- category TEXT NOT NULL,
- is_secret BOOLEAN DEFAULT FALSE,
- updated_by VARCHAR(36),
- updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
-);
-```
-
-## Frontend
-
-The admin panel is served from `static/admin.html`.
diff --git a/doc/admin-settings.md b/doc/admin-settings.md
deleted file mode 100644
index 8c8b7e9d..00000000
--- a/doc/admin-settings.md
+++ /dev/null
@@ -1,160 +0,0 @@
-# 17 - Admin Settings
-
-Admin panel API for managing server settings, OIDC configuration, user management, and dashboard stats. All endpoints under `/api/admin` require a valid JWT with `role = "admin"`.
-
-## Architecture
-
-| Layer | Component | File |
-|---|---|---|
-| Domain Port | `SettingsRepository` trait | `src/domain/repositories/settings_repository.rs` |
-| Application Service | `AdminSettingsService` | `src/application/services/admin_settings_service.rs` |
-| Application DTOs | Settings and user management DTOs | `src/application/dtos/settings_dto.rs` |
-| Infrastructure | `SettingsPgRepository` | `src/infrastructure/repositories/pg/settings_pg_repository.rs` |
-| Interfaces | `admin_handler` functions | `src/interfaces/api/handlers/admin_handler.rs` |
-
-## REST API
-
-All routes under `/api/admin`, require admin JWT.
-
-### Settings
-
-| Method | Path | Handler | Description |
-|---|---|---|---|
-| `GET` | `/api/admin/settings/oidc` | `get_oidc_settings` | Get current OIDC configuration |
-| `PUT` | `/api/admin/settings/oidc` | `save_oidc_settings` | Update OIDC configuration |
-| `POST` | `/api/admin/settings/oidc/test` | `test_oidc_connection` | Test OIDC provider connectivity |
-| `GET` | `/api/admin/settings/general` | `get_general_settings` | Get general server settings |
-
-### Dashboard
-
-| Method | Path | Handler | Description |
-|---|---|---|---|
-| `GET` | `/api/admin/dashboard` | `get_dashboard_stats` | Server dashboard statistics |
-
-### User Management
-
-| Method | Path | Handler | Description |
-|---|---|---|---|
-| `GET` | `/api/admin/users` | `list_users` | List all users (paginated) |
-| `GET` | `/api/admin/users/{id}` | `get_user` | Get user details |
-| `DELETE` | `/api/admin/users/{id}` | `delete_user` | Delete a user |
-| `PUT` | `/api/admin/users/{id}/role` | `update_user_role` | Change user role |
-| `PUT` | `/api/admin/users/{id}/active` | `update_user_active` | Activate/deactivate user |
-| `PUT` | `/api/admin/users/{id}/quota` | `update_user_quota` | Set storage quota |
-
-### Safety Guards
-
-- **Self-deletion blocked** -- admins cannot delete their own account
-- **Self-role-change blocked** -- admins cannot change their own role
-- **Self-deactivation blocked** -- admins cannot deactivate themselves
-
-## OIDC Settings Management
-
-### Get Settings Response
-
-```json
-{
- "enabled": true,
- "issuer_url": "https://keycloak.example.com/realms/main",
- "client_id": "oxicloud",
- "client_secret_set": true,
- "scopes": "openid profile email",
- "auto_provision": true,
- "admin_groups": "oxicloud-admins",
- "disable_password_login": false,
- "provider_name": "KeyCloak",
- "callback_url": "https://oxicloud.example.com/api/auth/oidc/callback",
- "env_overrides": ["issuer_url", "client_id"]
-}
-```
-
-The **env_overrides** field lists which settings are overridden by environment variables. Env vars always take priority over DB settings.
-
-### Save Settings Request
-
-```json
-{
- "enabled": true,
- "issuer_url": "https://keycloak.example.com/realms/main",
- "client_id": "oxicloud",
- "client_secret": "new-secret",
- "scopes": "openid profile email",
- "auto_provision": true,
- "admin_groups": "oxicloud-admins",
- "disable_password_login": false,
- "provider_name": "KeyCloak"
-}
-```
-
-After saving, the service hot-reloads OIDC via **auth_app_service.reload_oidc()** or **disable_oidc()**.
-
-### Test OIDC Connection
-
-```json
-// Request
-{ "issuer_url": "https://keycloak.example.com/realms/main" }
-
-// Response
-{
- "success": true,
- "message": "Successfully connected to OIDC provider",
- "issuer": "https://keycloak.example.com/realms/main",
- "authorization_endpoint": "https://keycloak.example.com/realms/main/protocol/openid-connect/auth",
- "token_endpoint": "https://keycloak.example.com/realms/main/protocol/openid-connect/token",
- "userinfo_endpoint": "https://keycloak.example.com/realms/main/protocol/openid-connect/userinfo",
- "provider_name_suggestion": "KeyCloak"
-}
-```
-
-## Dashboard Statistics
-
-```json
-{
- "server_version": "0.3.1",
- "auth_enabled": true,
- "oidc_configured": true,
- "quotas_enabled": false,
- "total_users": 42,
- "active_users": 38,
- "admin_users": 2,
- "total_quota_bytes": 107374182400,
- "total_used_bytes": 53687091200,
- "storage_usage_percent": 50.0,
- "users_over_80_percent": 5,
- "users_over_quota": 1
-}
-```
-
-## User Management DTOs
-
-```rust
-pub struct UpdateUserRoleDto { pub role: String } // "user" | "admin"
-pub struct UpdateUserActiveDto { pub active: bool }
-pub struct UpdateUserQuotaDto { pub quota_bytes: i64 }
-pub struct ListUsersQueryDto { pub limit: Option, pub offset: Option }
-```
-
-## Config Priority
-
-Settings resolve in this order (highest first):
-
-1. **Environment variables** (`OXICLOUD_OIDC_*`)
-2. **Database settings** (`auth.admin_settings` table)
-3. **Defaults**
-
-## Database Schema
-
-```sql
-CREATE TABLE IF NOT EXISTS auth.admin_settings (
- key TEXT PRIMARY KEY,
- value TEXT NOT NULL,
- category TEXT NOT NULL,
- is_secret BOOLEAN DEFAULT FALSE,
- updated_by VARCHAR(36),
- updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
-);
-```
-
-## Frontend
-
-The admin panel is served from `static/admin.html`.
diff --git a/doc/batch-operations.md b/doc/batch-operations.md
deleted file mode 100644
index c9df3e11..00000000
--- a/doc/batch-operations.md
+++ /dev/null
@@ -1,140 +0,0 @@
-# 09 - Batch Operations
-
-Batch endpoints let you perform bulk file and folder operations (move, copy, delete, get, create) in a single request. Operations run concurrently behind a configurable semaphore. Each response includes detailed per-item success/failure info.
-
-## Architecture
-
-| Layer | Component | File |
-|---|---|---|
-| Application Service | **BatchOperationService** | `src/application/services/batch_operations.rs` |
-| Interfaces | `batch_handler` functions | `src/interfaces/api/handlers/batch_handler.rs` |
-
-## REST API
-
-All routes live under `/api/batch` and require authentication.
-
-### File Operations
-
-| Method | Path | Handler | Description |
-|---|---|---|---|
-| `POST` | `/api/batch/files/move` | `move_files_batch` | Move files to target folder |
-| `POST` | `/api/batch/files/copy` | `copy_files_batch` | Copy files to target folder |
-| `POST` | `/api/batch/files/delete` | `delete_files_batch` | Delete multiple files |
-| `POST` | `/api/batch/files/get` | `get_files_batch` | Get metadata for multiple files |
-
-### Folder Operations
-
-| Method | Path | Handler | Description |
-|---|---|---|---|
-| `POST` | `/api/batch/folders/delete` | `delete_folders_batch` | Delete multiple folders |
-| `POST` | `/api/batch/folders/create` | `create_folders_batch` | Create multiple folders |
-| `POST` | `/api/batch/folders/get` | `get_folders_batch` | Get metadata for multiple folders |
-
-## Request DTOs
-
-### File Operations
-
-```json
-{
- "file_ids": ["id-1", "id-2", "id-3"],
- "target_folder_id": "folder-abc" // required for move/copy
-}
-```
-
-### Folder Delete
-
-```json
-{
- "folder_ids": ["folder-1", "folder-2"],
- "recursive": true,
- "target_folder_id": null
-}
-```
-
-### Folder Create
-
-```json
-{
- "folders": [
- { "name": "Documents", "parent_id": null },
- { "name": "Photos", "parent_id": "folder-abc" }
- ]
-}
-```
-
-## Response Format
-
-Every batch endpoint returns the same structure:
-
-```json
-{
- "successful": [ ... ],
- "failed": [
- { "id": "bad-id", "error": "File not found" }
- ],
- "stats": {
- "total": 5,
- "successful": 4,
- "failed": 1,
- "execution_time_ms": 245
- }
-}
-```
-
-### Status Codes
-
-| Code | Meaning |
-|---|---|
-| `200 OK` / `201 Created` | All operations succeeded |
-| `206 Partial Content` | Some succeeded, some failed |
-| `400 Bad Request` | All operations failed |
-
-## Concurrency
-
-Operations run concurrently via `tokio::sync::Semaphore`, capped by **max_concurrent_files** (default: 10).
-
-```rust
-pub struct BatchOperationService {
- file_retrieval: Arc,
- file_management: Arc,
- folder_service: Arc,
- config: AppConfig,
- semaphore: Arc,
-}
-```
-
-## Error Handling
-
-```rust
-pub enum BatchOperationError {
- Domain(DomainError), // individual operation error
- Cancelled(String), // operation was cancelled
- ConcurrencyLimit(String), // semaphore exhausted
- PartialFailure(String, usize, usize), // message, success_count, fail_count
- Internal(String),
-}
-```
-
-Individual failures do not abort the batch. They get collected in the `failed` array and the response returns `206 Partial Content`.
-
-## Example
-
-```bash
-# Move 3 files to a folder
-curl -X POST -H "Authorization: Bearer $TOKEN" \
- -H "Content-Type: application/json" \
- -d '{"file_ids":["id-1","id-2","id-3"],"target_folder_id":"folder-abc"}' \
- "https://oxicloud.example.com/api/batch/files/move"
-
-# Delete folders recursively
-curl -X POST -H "Authorization: Bearer $TOKEN" \
- -H "Content-Type: application/json" \
- -d '{"folder_ids":["old-1","old-2"],"recursive":true}' \
- "https://oxicloud.example.com/api/batch/folders/delete"
-
-# Create multiple folders
-curl -X POST -H "Authorization: Bearer $TOKEN" \
- -H "Content-Type: application/json" \
- -d '{"folders":[{"name":"Docs","parent_id":null},{"name":"Photos","parent_id":"root-id"}]}' \
- "https://oxicloud.example.com/api/batch/folders/create"
-```
diff --git a/doc/caching-architecture.md b/doc/caching-architecture.md
deleted file mode 100644
index ab1ecdd6..00000000
--- a/doc/caching-architecture.md
+++ /dev/null
@@ -1,274 +0,0 @@
-# 04 - Caching Architecture
-
-OxiCloud uses a multi-layer caching system spanning HTTP-level caching down to kernel-level memory mapping. Covers both uploads and downloads.
-
-## Cache Layers Summary
-
-```
-┌─────────────────────────────────────────────────────┐
-│ Layer 0: HTTP Cache Middleware (ETag + 304) │ All endpoints
-├─────────────────────────────────────────────────────┤
-│ Layer 1: File Content Cache (LRU, <10MB files) │ Downloads
-├─────────────────────────────────────────────────────┤
-│ Layer 2: MMAP (memmap2, 10-100MB blobs) │ Downloads
-├─────────────────────────────────────────────────────┤
-│ Layer 3: Streaming (FramedRead, ≥100MB blobs) │ Downloads
-├─────────────────────────────────────────────────────┤
-│ Layer 4: Buffer Pool (reusable I/O buffers) │ Compression
-└─────────────────────────────────────────────────────┘
-```
-
-> **Note:** File metadata (name, size, MIME type, folder) is served from PostgreSQL — no separate filesystem metadata cache is needed.
-
----
-
-## Layer 0: HTTP Cache Middleware
-
-**File**: `src/interfaces/middleware/cache.rs`
-
-Generic HTTP caching layer applied to API endpoints.
-
-| Parameter | Value |
-|---|---|
-| Max entries | 1,000 |
-| Default max-age | 60 seconds |
-| Eviction | LRU (oldest 10% when full) |
-| Cleanup | Background task every 5 minutes |
-
-Features:
-- ETag-based conditional requests (`If-None-Match` → `304 Not Modified`)
-- `Cache-Control` header injection
-- Implements Tower `Layer` + `Service` traits for Axum integration
-- Per-request key: method + URI
-
----
-
-## Layer 1: File Content Cache (Download Tier 1)
-
-**File**: `src/infrastructure/services/file_content_cache.rs`
-
-In-memory LRU cache for small files, served directly from RAM.
-
-| Parameter | Value |
-|---|---|
-| Max file size | 10 MB per file |
-| Max total cache size | 512 MB |
-| Max entries | 10,000 |
-| Structure | `lru::LruCache` |
-| Latency | ~0.1ms |
-
-**CacheEntry**: `{ data: Bytes, etag: String, content_type: String, size: usize }`
-
-Methods:
-- `should_cache(size)` — checks if file fits in cache
-- `get(file_id)` → `Option<(Bytes, String, String)>` — returns (data, etag, content_type)
-- `put(file_id, content, etag, content_type)` — inserts with LRU eviction
-- `invalidate(file_id)`, `clear()`
-- `stats()` → `CacheStats { current_size_bytes, max_size_bytes, hits, misses, hit_rate_percent }`
-
-Port: implements **ContentCachePort** trait.
-
----
-
-## Layer 2: MMAP (Download Tier 2)
-
-**File**: `src/infrastructure/repositories/pg/file_blob_read_repository.rs`
-
-Memory-mapped I/O for medium blobs using `memmap2`.
-
-| Parameter | Value |
-|---|---|
-| File range | 10 MB - 100 MB |
-| Implementation | `memmap2::Mmap` via `spawn_blocking` |
-| Latency | ~1-5ms |
-
-The blob file (`.blobs/{prefix}/{hash}.blob`) is memory-mapped and its contents copied to `Bytes`. Benefits from kernel page cache for frequently accessed blobs.
-
----
-
-## Layer 3: Streaming (Download Tier 3)
-
-**File**: `src/infrastructure/repositories/pg/file_blob_read_repository.rs`
-
-Chunked streaming for large blobs using tokio-util codecs.
-
-| Parameter | Value |
-|---|---|
-| File range | ≥100 MB |
-| Chunk size | 1 MB (configurable via **ResourceConfig.chunk_size_bytes**) |
-| Implementation | `FramedRead` + `BytesCodec` |
-| RAM usage | Near zero (one chunk at a time) |
-
----
-
-## Layer 4: Buffer Pool
-
-**File**: `src/infrastructure/services/buffer_pool.rs`
-
-Reusable byte buffer pool to reduce allocation pressure during compression operations.
-
-| Parameter | Value |
-|---|---|
-| Buffer size | 64 KB |
-| Max buffers | 100 |
-| Buffer TTL | 60 seconds |
-| Concurrency control | `tokio::sync::Semaphore` |
-
-Features:
-- `get_buffer()` — borrows a buffer (blocks if pool exhausted)
-- **BorrowedBuffer** auto-returns to pool on `Drop` via `tokio::spawn`
-- Expired buffers are cleaned periodically via `start_cleaner()`
-- Tracks stats: gets, hits, misses, returns, evictions, waits
-
----
-
-## Configuration
-
-All cache-related config in `src/common/config.rs`:
-
-```rust
-pub struct ResourceConfig {
- pub large_file_threshold_mb: u64, // 100 MB (mmap→streaming boundary)
- pub chunk_size_bytes: usize, // 1 MB (streaming chunk size)
- pub max_in_memory_file_size_mb: u64, // 50 MB
-}
-```
-
-## Download Flow
-
-```
-Request → ETag check (304?) → Range request (206?)
- → file size < 10MB? → Tier 1: LRU cache (RAM)
- → file size < 100MB? → Tier 2: MMAP (kernel page cache on blob file)
- → file size ≥ 100MB → Tier 3: Streaming (chunked from blob file)
-```
-
-In all tiers, metadata (file name, size, MIME type) comes from a PostgreSQL `SELECT` on `storage.files`. Content is read from the DedupService blob at `.blobs/{prefix}/{hash}.blob`.
-
----
-
-## Range Requests (HTTP 206 Partial Content)
-
-**Files**: `src/interfaces/api/handlers/file_handler.rs`, `src/infrastructure/repositories/pg/file_blob_read_repository.rs`
-
-**Crate**: `http-range-header = "0.4"` for parsing.
-
-### Request Processing Flow
-
-```
-Range header present?
- ├─ parse_range_header(range_str)
- │ ├─ Parse OK → ranges.validate(file_size)
- │ │ ├─ Valid → take first range → get_file_range_stream(start, end+1)
- │ │ │ ├─ Stream OK → 206 Partial Content
- │ │ │ └─ Stream Err → fall through to normal download (200)
- │ │ └─ Invalid → 416 Range Not Satisfiable
- │ └─ Parse Err → fall through to normal download (200)
- └─ No Range header → normal 3-tier download
-```
-
-### Response Headers (206)
-
-| Header | Value |
-|---|---|
-| `Content-Type` | File MIME type |
-| `Content-Range` | `bytes {start}-{end}/{total_size}` |
-| `Content-Length` | Range length (end - start + 1) |
-| `Accept-Ranges` | `bytes` |
-| `ETag` | `"{file_id}-{modified_at}"` |
-| `Cache-Control` | `private, max-age=3600, must-revalidate` |
-
-### 416 Range Not Satisfiable
-
-Returned when `ranges.validate(file_size)` fails:
-```
-HTTP/1.1 416 Range Not Satisfiable
-Content-Range: bytes */12345
-```
-
-### Blob File Seek Implementation
-
-`get_file_range_stream()` at the repository level:
-
-1. Resolves blob path from `blob_hash` via DedupService
-2. Opens the blob file with `TokioFile::open()`
-3. Seeks to `start` via `fh.seek(SeekFrom::Start(start))`
-4. Limits read to `range_length` via `fh.take(range_length)`
-5. Wraps in `FramedRead` + `BytesCodec`
-
-Adaptive chunk size:
-
-| Range size | Chunk size |
-|---|---|
-| ≤ 1 MB | 8 KB |
-| > 1 MB | 1 MB (from **ResourceConfig.chunk_size_bytes**) |
-
-### Tier Interaction
-
-Range requests **bypass all download tiers** (LRU, MMAP). They always use direct blob file seek + streaming. On stream creation error, the handler falls through to the normal `get_file_optimized()` 3-tier path.
-
-### Limitations
-
-- **Multipart ranges not supported**: only the first range in a multi-range request is served.
-- **`If-Range` not handled**: no conditional range support.
-- **`If-Modified-Since` not handled**: only `If-None-Match` (ETag) is checked.
-
----
-
-## Upload Flow
-
-```
-Request → file size < 1MB? → Buffered write (sync to blob store)
- → file size ≥ 1MB → Streaming write (chunk-by-chunk to blob store)
-```
-
-### Upload Strategy Selection
-
-**File**: `src/application/services/file_upload_service.rs`
-
-```rust
-pub enum UploadStrategy {
- Buffered, // < 1 MB — collect bytes, write to blob store
- Streaming, // ≥ 1 MB — chunk-by-chunk write via save_file_from_stream
-}
-```
-
-| Constant | Value |
-|---|---|
-| `STREAMING_UPLOAD_THRESHOLD` | 1 MB |
-
-### Handler-Level Buffering
-
-Upload handlers buffer the multipart body in RAM as `Vec` before calling the service layer:
-
-```rust
-let mut chunks: Vec = Vec::new();
-while let Some(chunk) = field.chunk().await {
- chunks.push(chunk);
-}
-upload_service.smart_upload(..., chunks, total_size).await
-```
-
-### Buffered Path (< 1 MB)
-
-Uses `save_file()` — all bytes are passed to `FileBlobWriteRepository`, which calls `DedupService.store_bytes()` to compute hash and store the blob, then INSERTs metadata into `storage.files`.
-
-### Streaming Path (≥ 1 MB)
-
-`smart_upload()` converts the in-memory `Vec` into a `futures::stream::iter()` and passes it to `save_file_from_stream()`:
-
-```rust
-let chunk_stream = stream::iter(chunks.into_iter().map(|c| Ok(c)));
-self.file_write.save_file_from_stream(name, folder_id, content_type, chunk_stream).await
-```
-
-`FileBlobWriteRepository.save_file_from_stream()` collects the stream, stores via DedupService, and INSERTs metadata.
-
-### Dedup Integration
-
-Deduplication is handled at the **repository layer** (not the service layer) for all upload strategies. `FileBlobWriteRepository` always calls `DedupService.store_bytes()` which:
-
-1. Computes SHA-256 hash of content
-2. Checks if blob already exists (dedup hit → increment ref count, skip write)
-3. If new → atomic write to `.blobs/{prefix}/{hash}.blob`
-4. Returns the hash for storage in `storage.files.blob_hash`
diff --git a/doc/caldav-technical-spec.md b/doc/caldav-technical-spec.md
deleted file mode 100644
index 9590f20a..00000000
--- a/doc/caldav-technical-spec.md
+++ /dev/null
@@ -1,239 +0,0 @@
-# 26 - CalDAV Technical Spec
-
-CalDAV (RFC 4791) provides calendar synchronization. Clients like Thunderbird, Apple Calendar, GNOME Calendar, and DAVx5 (Android) connect to manage calendars and events via standard CalDAV.
-
-## Protocol Compliance
-
-- **DAV compliance**: `1, 2, calendar-access`
-- **RFC 4791**: Calendar Access (CalDAV)
-- **iCalendar**: RFC 5545 (VEVENT parsing and generation)
-
-## Endpoint Structure
-
-All CalDAV endpoints are mounted at the top level (not under `/api`):
-
-```
-ANY /caldav → handle_caldav_methods_root
-ANY /caldav/ → handle_caldav_methods_root
-ANY /caldav/{*path} → handle_caldav_methods
-```
-
-### Path Hierarchy
-
-| Path | Resource | Description |
-|---|---|---|
-| `/caldav/` | Calendar home | User's calendar collection |
-| `/caldav/{calendar_id}/` | Calendar | Individual calendar |
-| `/caldav/{calendar_id}/{ical_uid}.ics` | Event | Individual calendar event |
-
-### Supported HTTP Methods
-
-| Method | Description |
-|---|---|
-| `OPTIONS` | Returns DAV capabilities and allowed methods |
-| `PROPFIND` | List calendars, calendar properties, events |
-| `REPORT` | CalendarQuery, CalendarMultiget, SyncCollection |
-| `MKCALENDAR` | Create a new calendar |
-| `PUT` | Create/update events (iCalendar format) |
-| `GET` | Retrieve individual event as iCalendar |
-| `DELETE` | Delete calendars or events |
-| `PROPPATCH` | Update calendar properties |
-
-## Architecture
-
-| Layer | Component | File |
-|---|---|---|
-| Domain Entity | **Calendar**, **CalendarEvent** | `src/domain/entities/calendar.rs`, `calendar_event.rs` |
-| Domain Repository | **CalendarRepository**, **CalendarEventRepository** | `src/domain/repositories/calendar_repository.rs`, `calendar_event_repository.rs` |
-| Application Port | **CalendarUseCase**, **CalendarStoragePort** | `src/application/ports/calendar_ports.rs` |
-| Application Service | **CalendarService** | `src/application/services/calendar_service.rs` |
-| Application Adapter | **CalDavAdapter** (XML parsing/generation) | `src/application/adapters/caldav_adapter.rs` |
-| Infrastructure | **CalendarPgRepository**, **CalendarEventPgRepository** | `src/infrastructure/repositories/pg/` |
-| Interfaces | **CalDavHandler** | `src/interfaces/api/handlers/caldav_handler.rs` |
-
-## Domain Entities
-
-### Calendar
-
-```rust
-pub struct Calendar {
- id: Uuid,
- name: String,
- owner_id: String,
- description: Option,
- color: Option, // #RRGGBB format
- created_at: DateTime,
- updated_at: DateTime,
- custom_properties: HashMap,
-}
-```
-
-Validation: **name** non-empty, **owner_id** non-empty, **color** must be `#RRGGBB` hex format.
-
-### CalendarEvent
-
-```rust
-pub struct CalendarEvent {
- id: Uuid,
- calendar_id: Uuid,
- summary: String,
- description: Option,
- location: Option,
- start_time: DateTime,
- end_time: DateTime,
- all_day: bool,
- rrule: Option, // iCal RRULE format (e.g., "FREQ=WEEKLY")
- ical_uid: String, // unique iCal identifier
- ical_data: String, // full VEVENT block
- created_at: DateTime,
- updated_at: DateTime,
-}
-```
-
-Validation: **summary** non-empty, `end_time >= start_time`, **rrule** starts with `FREQ=`, **ical_data** contains `BEGIN:VEVENT`/`END:VEVENT`.
-
-The constructor `from_ical(calendar_id, ical_data)` parses iCalendar data to extract summary, dates, location, etc.
-
-## REPORT Types
-
-The CalDAV **REPORT** method supports three report types:
-
-### CalendarQuery
-
-Filters events by time range. Used for initial sync and view rendering.
-
-```xml
-
-
-
-
-
-
-
-
-
-
-
-
-
-```
-
-### CalendarMultiget
-
-Fetches specific events by href. Used for selective sync.
-
-```xml
-
-
-
-
-
- /caldav/cal-1/event-1.ics
- /caldav/cal-1/event-2.ics
-
-```
-
-### SyncCollection
-
-Incremental sync using sync tokens. Used for ongoing synchronization.
-
-```xml
-
- sync-token-value
-
-
-
-
-```
-
-## XML Namespaces
-
-| Prefix | Namespace |
-|---|---|
-| `D:` | `DAV:` |
-| `C:` | `urn:ietf:params:xml:ns:caldav` |
-| `CS:` | `http://calendarserver.org/ns/` |
-
-## CalDAV Adapter
-
-**CalDavAdapter** in `src/application/adapters/caldav_adapter.rs` handles all XML parsing and generation:
-
-- `parse_report(reader)` -> **CalDavReportType**
-- `parse_mkcalendar(reader)` -> `(name, description, color)`
-- `generate_calendars_propfind_response(...)` -- multi-calendar PROPFIND
-- `generate_calendar_collection_propfind(...)` -- single calendar with events
-- `generate_calendar_events_response(...)` -- REPORT response
-
-## Calendar Sharing
-
-Calendars support sharing with access levels:
-
-| Level | Permissions |
-|---|---|
-| `read` | View calendar and events |
-| `write` | Create, modify, delete events |
-| `owner` | Full control including sharing and deletion |
-
-## Database Schema
-
-```sql
-CREATE SCHEMA IF NOT EXISTS caldav;
-
--- Calendars
-CREATE TABLE caldav.calendars (
- id UUID PRIMARY KEY,
- name TEXT NOT NULL,
- owner_id VARCHAR(36) REFERENCES auth.users(id) ON DELETE CASCADE,
- description TEXT,
- color VARCHAR(9),
- is_public BOOLEAN DEFAULT FALSE,
- ctag VARCHAR(64) DEFAULT '0',
- created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
- updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
-);
-
--- Calendar Events
-CREATE TABLE caldav.calendar_events (
- id UUID PRIMARY KEY,
- calendar_id UUID REFERENCES caldav.calendars(id) ON DELETE CASCADE,
- summary TEXT NOT NULL,
- description TEXT,
- location TEXT,
- start_time TIMESTAMPTZ NOT NULL,
- end_time TIMESTAMPTZ NOT NULL,
- all_day BOOLEAN DEFAULT FALSE,
- rrule TEXT,
- ical_uid VARCHAR(255) NOT NULL,
- ical_data TEXT,
- etag VARCHAR(64),
- created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
- updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
-);
-
--- Calendar Shares
-CREATE TABLE caldav.calendar_shares (
- id SERIAL PRIMARY KEY,
- calendar_id UUID REFERENCES caldav.calendars(id) ON DELETE CASCADE,
- user_id VARCHAR(36) REFERENCES auth.users(id) ON DELETE CASCADE,
- access_level VARCHAR(10) DEFAULT 'read',
- created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
- UNIQUE(calendar_id, user_id)
-);
-
--- Calendar Properties
-CREATE TABLE caldav.calendar_properties (
- id SERIAL PRIMARY KEY,
- calendar_id UUID REFERENCES caldav.calendars(id) ON DELETE CASCADE,
- property_name TEXT NOT NULL,
- property_value TEXT NOT NULL,
- UNIQUE(calendar_id, property_name)
-);
-```
-
-Indexes: `idx_calendars_owner_id`, `idx_calendar_events_calendar_id`, `idx_calendar_events_ical_uid`, `idx_calendar_events_time_range (start_time, end_time)`.
-
-## Client Configuration
-
-See `dav-client-setup.md` for client-specific configuration instructions.
-
-CalDAV URL: `https://oxicloud.example.com/caldav/`
diff --git a/doc/carddav-implementation-plan.md b/doc/carddav-implementation-plan.md
deleted file mode 100644
index 28693064..00000000
--- a/doc/carddav-implementation-plan.md
+++ /dev/null
@@ -1,215 +0,0 @@
-# 28 - CardDAV Implementation Plan
-
-CardDAV is an open protocol for syncing address books and contacts across applications and devices. This plan breaks the implementation into five phases over five weeks.
-
-## Implementation Roadmap
-
-### Phase 1: Core Infrastructure (Week 1)
-
-**Database Schema** -- new migration for CardDAV tables:
-- **address_books** -- stores address book collections
-- **contacts** -- stores contact data
-- **address_book_shares** -- sharing between users
-- **contact_groups** -- organizing contacts into groups
-- **group_memberships** -- associating contacts with groups
-
-**Domain Layer** -- entity models:
-- **Contact** -- core contact entity
-- **AddressBook** -- collection entity
-- **ContactGroup** -- grouping contacts
-
-Repository interfaces:
-- **ContactRepository** -- contact CRUD
-- **AddressBookRepository** -- address book management
-- **ContactGroupRepository** -- group management
-
-**Testing** -- unit tests for entity models and repository interface contract tests.
-
-### Phase 2: Infrastructure Layer (Week 2)
-
-**Repository Implementations** -- PostgreSQL:
-- **ContactPgRepository**
-- **AddressBookPgRepository**
-- **ContactGroupPgRepository**
-
-Also implement vCard parsing/generation utilities and any data migration tools needed.
-
-**Integration** -- update DI system to include new repositories and connect with existing auth system.
-
-**Testing** -- repository implementation tests, vCard parsing/generation tests, integration tests with the database.
-
-### Phase 3: Application Layer (Week 3)
-
-**Services** -- business logic:
-- **ContactService** -- contact management
-- **AddressBookService** -- address book management
-- **ContactGroupService** -- group management
-
-**DTOs and Ports** -- create DTOs for contact operations, define service interface ports, implement request/response mapping.
-
-**CardDAV Adapter** -- protocol translation adapter with vCard conversion logic and XML parsing/generation utilities.
-
-**Testing** -- service unit tests and integration tests for the adapter.
-
-### Phase 4: Interface Layer (Week 4)
-
-**REST API** -- endpoints for address book operations, contact management, contact groups. Document with OpenAPI.
-
-**CardDAV Protocol Endpoints** -- WebDAV method handlers:
-- PROPFIND -- discovery and property retrieval
-- REPORT -- querying contacts
-- MKCOL -- creating address books
-- GET/PUT/DELETE -- contact operations
-- CardDAV-specific XML handling
-
-**Integration** -- connect all layers, end-to-end testing, test with various CardDAV clients.
-
-**Testing** -- API endpoint tests, CardDAV protocol compliance tests, client compatibility tests.
-
-### Phase 5: Refinement and Optimization (Week 5)
-
-**Performance** -- caching for frequently accessed resources, query optimization, efficient sync mechanisms.
-
-**Security** -- review auth, validate I/O, add rate limiting.
-
-**Final Testing** -- stress testing with large address books, security testing, user acceptance testing.
-
-**Documentation** -- update API docs, user guides, client setup procedures.
-
-## Technical Specifications
-
-### Database Schema
-
-```sql
--- Address books table
-CREATE TABLE IF NOT EXISTS carddav.address_books (
- id UUID PRIMARY KEY,
- name VARCHAR(255) NOT NULL,
- owner_id VARCHAR(36) NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
- description TEXT,
- color VARCHAR(50),
- is_public BOOLEAN NOT NULL DEFAULT FALSE,
- created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
- updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
- UNIQUE(owner_id, name)
-);
-
--- Address book sharing
-CREATE TABLE IF NOT EXISTS carddav.address_book_shares (
- address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
- user_id VARCHAR(36) NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
- can_write BOOLEAN NOT NULL DEFAULT FALSE,
- PRIMARY KEY(address_book_id, user_id)
-);
-
--- Contacts table
-CREATE TABLE IF NOT EXISTS carddav.contacts (
- id UUID PRIMARY KEY,
- address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
- uid VARCHAR(255) NOT NULL,
- full_name VARCHAR(255),
- first_name VARCHAR(255),
- last_name VARCHAR(255),
- nickname VARCHAR(255),
- email JSONB,
- phone JSONB,
- address JSONB,
- organization VARCHAR(255),
- title VARCHAR(255),
- notes TEXT,
- photo_url TEXT,
- birthday DATE,
- anniversary DATE,
- vcard TEXT NOT NULL,
- etag VARCHAR(255) NOT NULL,
- created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
- updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
- UNIQUE(address_book_id, uid)
-);
-
--- Contact groups
-CREATE TABLE IF NOT EXISTS carddav.contact_groups (
- id UUID PRIMARY KEY,
- address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
- name VARCHAR(255) NOT NULL,
- created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
- updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
-);
-
--- Group memberships
-CREATE TABLE IF NOT EXISTS carddav.group_memberships (
- group_id UUID NOT NULL REFERENCES carddav.contact_groups(id) ON DELETE CASCADE,
- contact_id UUID NOT NULL REFERENCES carddav.contacts(id) ON DELETE CASCADE,
- PRIMARY KEY(group_id, contact_id)
-);
-```
-
-### API Endpoints
-
-#### REST API
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/address-books` | List all address books |
-| POST | `/api/address-books` | Create a new address book |
-| GET | `/api/address-books/:id` | Get a specific address book |
-| PUT | `/api/address-books/:id` | Update an address book |
-| DELETE | `/api/address-books/:id` | Delete an address book |
-| GET | `/api/address-books/:id/contacts` | List contacts in an address book |
-| POST | `/api/address-books/:id/contacts` | Create a new contact |
-| GET | `/api/address-books/:id/contacts/:contactId` | Get a specific contact |
-| PUT | `/api/address-books/:id/contacts/:contactId` | Update a contact |
-| DELETE | `/api/address-books/:id/contacts/:contactId` | Delete a contact |
-
-#### CardDAV Protocol Endpoints
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| PROPFIND | `/carddav/` | List all address books |
-| PROPFIND | `/carddav/:addressBookId/` | Get address book information |
-| REPORT | `/carddav/:addressBookId/` | Query contacts in an address book |
-| GET | `/carddav/:addressBookId/:contactId.vcf` | Get a specific contact (vCard) |
-| PUT | `/carddav/:addressBookId/:contactId.vcf` | Create or update a contact |
-| DELETE | `/carddav/:addressBookId/:contactId.vcf` | Delete a contact |
-
-### Dependencies
-
-- vCard parsing/generation library (e.g., `vcard-rs` or similar)
-- XML processing (for CardDAV protocol)
-- Database access (PostgreSQL)
-- WebDAV base functionality
-
-## Resources Required
-
-- Developer time: 1 full-time developer for 5 weeks
-- Testing resources: multiple CardDAV clients (Apple Contacts, Thunderbird, Android)
-- Server resources: test environment with PostgreSQL
-
-## Success Criteria
-
-1. Users can create, update, and delete address books
-2. Contacts can be managed within address books
-3. Address books can be shared between users
-4. Standard CardDAV clients can sync with the server
-5. Acceptable performance with large address books (1000+ contacts)
-6. Security measures properly implemented
-
-## Client Setup Guides
-
-After implementation, setup guides will be created for:
-
-- Apple Contacts (macOS/iOS)
-- Thunderbird/Evolution
-- Android (using DAVx5)
-- Other common CardDAV clients
-
-See `dav-client-setup.md` for general DAV client configuration.
-
-## Future Enhancements
-
-1. Advanced contact search
-2. Contact merging for duplicate detection
-3. Bulk import/export
-4. Contact photo management
-5. Extended fields for specialized contact info
-6. Integration with external systems (e.g., LDAP directories)
diff --git a/doc/carddav-technical-spec.md b/doc/carddav-technical-spec.md
deleted file mode 100644
index ee2fa6f4..00000000
--- a/doc/carddav-technical-spec.md
+++ /dev/null
@@ -1,343 +0,0 @@
-# 27 - CardDAV Technical Spec
-
-CardDAV (RFC 6352) enables contact synchronization across devices and applications. It extends WebDAV (RFC 4918) to manage address books and vCard-formatted contacts.
-
-## Architecture
-
-The CardDAV implementation follows the hexagonal architecture pattern:
-
-```
-┌───────────────────┐ ┌────────────────────┐ ┌────────────────────┐
-│ │ │ │ │ │
-│ Interfaces │ │ Application │ │ Infrastructure │
-│ - CardDAV API │────▶│ - Contact Service │────▶│ - Contact Repo │
-│ - Contact API │ │ - CardDAV Adapter │ │ - PG Repository │
-│ │ │ │ │ │
-└───────────────────┘ └────────────────────┘ └────────────────────┘
- │
- ▼
- ┌────────────────────┐
- │ │
- │ Domain │
- │ - Contact Entity │
- │ - Address Book │
- │ │
- └────────────────────┘
-```
-
-### Components
-
-1. **Domain Layer**
- - **Contact** entity -- name, email, phone, etc.
- - **AddressBook** entity -- a collection of contacts
- - Repository interfaces for contact management
-
-2. **Application Layer**
- - **ContactService** -- business logic for managing contacts
- - **CardDAVAdapter** -- converts between CardDAV protocol requests/responses and domain objects
-
-3. **Infrastructure Layer**
- - **ContactPgRepository** -- PostgreSQL implementation of contact repositories
- - **AddressBookPgRepository** -- PostgreSQL implementation of address book repositories
-
-4. **Interface Layer**
- - REST API endpoints for contact management
- - CardDAV protocol endpoints (WebDAV extension)
-
-## Database Schema
-
-```sql
--- Address books table
-CREATE TABLE IF NOT EXISTS carddav.address_books (
- id UUID PRIMARY KEY,
- name VARCHAR(255) NOT NULL,
- owner_id VARCHAR(36) NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
- description TEXT,
- color VARCHAR(50),
- is_public BOOLEAN NOT NULL DEFAULT FALSE,
- created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
- updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
- UNIQUE(owner_id, name)
-);
-
--- Address book sharing
-CREATE TABLE IF NOT EXISTS carddav.address_book_shares (
- address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
- user_id VARCHAR(36) NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
- can_write BOOLEAN NOT NULL DEFAULT FALSE,
- PRIMARY KEY(address_book_id, user_id)
-);
-
--- Contacts table
-CREATE TABLE IF NOT EXISTS carddav.contacts (
- id UUID PRIMARY KEY,
- address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
- uid VARCHAR(255) NOT NULL,
- full_name VARCHAR(255),
- first_name VARCHAR(255),
- last_name VARCHAR(255),
- nickname VARCHAR(255),
- email JSONB,
- phone JSONB,
- address JSONB,
- organization VARCHAR(255),
- title VARCHAR(255),
- notes TEXT,
- photo_url TEXT,
- birthday DATE,
- anniversary DATE,
- vcard TEXT NOT NULL,
- etag VARCHAR(255) NOT NULL,
- created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
- updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
- UNIQUE(address_book_id, uid)
-);
-
--- Contact groups
-CREATE TABLE IF NOT EXISTS carddav.contact_groups (
- id UUID PRIMARY KEY,
- address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
- name VARCHAR(255) NOT NULL,
- created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
- updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
-);
-
--- Group memberships
-CREATE TABLE IF NOT EXISTS carddav.group_memberships (
- group_id UUID NOT NULL REFERENCES carddav.contact_groups(id) ON DELETE CASCADE,
- contact_id UUID NOT NULL REFERENCES carddav.contacts(id) ON DELETE CASCADE,
- PRIMARY KEY(group_id, contact_id)
-);
-```
-
-## API Endpoints
-
-### REST API
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/address-books` | List all address books |
-| POST | `/api/address-books` | Create a new address book |
-| GET | `/api/address-books/:id` | Get a specific address book |
-| PUT | `/api/address-books/:id` | Update an address book |
-| DELETE | `/api/address-books/:id` | Delete an address book |
-| GET | `/api/address-books/:id/contacts` | List contacts in an address book |
-| POST | `/api/address-books/:id/contacts` | Create a new contact |
-| GET | `/api/address-books/:id/contacts/:contactId` | Get a specific contact |
-| PUT | `/api/address-books/:id/contacts/:contactId` | Update a contact |
-| DELETE | `/api/address-books/:id/contacts/:contactId` | Delete a contact |
-| GET | `/api/address-books/:id/groups` | List contact groups |
-| POST | `/api/address-books/:id/groups` | Create a new contact group |
-
-### CardDAV Protocol Endpoints
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| PROPFIND | `/carddav/` | List all address books |
-| PROPFIND | `/carddav/:addressBookId/` | Get address book info |
-| REPORT | `/carddav/:addressBookId/` | Query contacts in an address book |
-| GET | `/carddav/:addressBookId/:contactId.vcf` | Get a specific contact (vCard) |
-| PUT | `/carddav/:addressBookId/:contactId.vcf` | Create or update a contact |
-| DELETE | `/carddav/:addressBookId/:contactId.vcf` | Delete a contact |
-| MKCOL | `/carddav/:addressBookId/` | Create a new address book |
-| DELETE | `/carddav/:addressBookId/` | Delete an address book |
-
-## Data Model
-
-### Contact Entity
-
-```rust
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct Contact {
- pub id: Uuid,
- pub address_book_id: Uuid,
- pub uid: String,
- pub full_name: Option,
- pub first_name: Option,
- pub last_name: Option,
- pub nickname: Option,
- pub email: Vec,
- pub phone: Vec,
- pub address: Vec,
- pub organization: Option,
- pub title: Option,
- pub notes: Option,
- pub photo_url: Option,
- pub birthday: Option,
- pub anniversary: Option,
- pub vcard: String,
- pub etag: String,
- pub created_at: DateTime,
- pub updated_at: DateTime,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct Email {
- pub email: String,
- pub r#type: String, // home, work, other
- pub is_primary: bool,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct Phone {
- pub number: String,
- pub r#type: String, // mobile, home, work, fax, other
- pub is_primary: bool,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct Address {
- pub street: Option,
- pub city: Option,
- pub state: Option,
- pub postal_code: Option,
- pub country: Option,
- pub r#type: String, // home, work, other
- pub is_primary: bool,
-}
-```
-
-### AddressBook Entity
-
-```rust
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct AddressBook {
- pub id: Uuid,
- pub name: String,
- pub owner_id: String,
- pub description: Option,
- pub color: Option,
- pub is_public: bool,
- pub created_at: DateTime,
- pub updated_at: DateTime,
-}
-```
-
-## Repositories
-
-### ContactRepository Interface
-
-```rust
-#[async_trait]
-pub trait ContactRepository: Send + Sync + 'static {
- async fn create_contact(&self, contact: Contact) -> ContactRepositoryResult;
- async fn update_contact(&self, contact: Contact) -> ContactRepositoryResult;
- async fn delete_contact(&self, id: &Uuid) -> ContactRepositoryResult<()>;
- async fn get_contact_by_id(&self, id: &Uuid) -> ContactRepositoryResult>;
- async fn get_contact_by_uid(&self, address_book_id: &Uuid, uid: &str) -> ContactRepositoryResult>;
- async fn get_contacts_by_address_book(&self, address_book_id: &Uuid) -> ContactRepositoryResult>;
- async fn get_contacts_by_email(&self, email: &str) -> ContactRepositoryResult>;
- async fn get_contacts_by_group(&self, group_id: &Uuid) -> ContactRepositoryResult>;
-}
-```
-
-### AddressBookRepository Interface
-
-```rust
-#[async_trait]
-pub trait AddressBookRepository: Send + Sync + 'static {
- async fn create_address_book(&self, address_book: AddressBook) -> AddressBookRepositoryResult;
- async fn update_address_book(&self, address_book: AddressBook) -> AddressBookRepositoryResult;
- async fn delete_address_book(&self, id: &Uuid) -> AddressBookRepositoryResult<()>;
- async fn get_address_book_by_id(&self, id: &Uuid) -> AddressBookRepositoryResult>;
- async fn get_address_books_by_owner(&self, owner_id: &str) -> AddressBookRepositoryResult>;
- async fn get_shared_address_books(&self, user_id: &str) -> AddressBookRepositoryResult>;
- async fn get_public_address_books(&self) -> AddressBookRepositoryResult>;
- async fn share_address_book(&self, address_book_id: &Uuid, user_id: &str, can_write: bool) -> AddressBookRepositoryResult<()>;
- async fn unshare_address_book(&self, address_book_id: &Uuid, user_id: &str) -> AddressBookRepositoryResult<()>;
- async fn get_address_book_shares(&self, address_book_id: &Uuid) -> AddressBookRepositoryResult>;
-}
-```
-
-## CardDAV Protocol Features
-
-1. **Address Book Discovery** -- clients discover available address books
-2. **Address Book Collection** -- manage contacts within address books
-3. **vCard Support** -- store and retrieve contacts in vCard format (3.0 and 4.0)
-4. **Query Support** -- filter contacts by properties
-5. **Multiget Support** -- retrieve multiple contacts in a single request
-6. **Sync-Collection** -- efficient incremental synchronization
-
-### CardDAV Adapter
-
-The **CardDAVAdapter** handles:
-
-1. Parsing CardDAV XML requests
-2. Converting between vCard and **Contact** entities
-3. Generating CardDAV XML responses
-4. Supporting **PROPFIND**, **REPORT**, and other WebDAV methods
-5. Implementing proper WebDAV properties for CardDAV
-
-## Integration Points
-
-1. **Authentication** -- reuses existing auth mechanisms
-2. **WebDAV Infrastructure** -- extends the existing WebDAV implementation
-3. **Database Layer** -- stores contacts in PostgreSQL
-4. **User Management** -- connects contacts with user accounts
-
-## Client Compatibility
-
-Target clients:
-
-- Apple Contacts
-- Google Contacts
-- Thunderbird
-- Outlook
-- Android DAVx5
-- iOS native contacts app
-- Evolution
-
-See `dav-client-setup.md` for detailed connection instructions.
-
-## Implementation Phases
-
-### Phase 1: Core Infrastructure
-- Database schema creation
-- Entity definitions
-- Repository interfaces
-- Basic DTO and port definitions
-
-### Phase 2: Core Business Logic
-- Address book management service
-- Contact management service
-- vCard parsing and generation
-
-### Phase 3: REST API
-- Address book endpoints
-- Contact management endpoints
-- Contact group endpoints
-
-### Phase 4: CardDAV Protocol
-- **CardDAVAdapter** implementation
-- WebDAV method handlers
-- XML parsing and generation
-- Protocol compliance testing
-
-### Phase 5: Testing and Refinement
-- Integration testing with client applications
-- Performance optimization
-- Edge case handling
-
-## Security
-
-1. **Authentication** -- proper authentication for all operations
-2. **Authorization** -- verify permissions for each address book operation
-3. **Data Validation** -- validate vCard input to prevent injection attacks
-4. **Resource Limits** -- limits to prevent abuse
-5. **Error Handling** -- appropriate error responses without leaking sensitive data
-
-## Performance
-
-1. **Indexing** -- proper database indexes for contact queries
-2. **Caching** -- cache frequently accessed address books and contacts
-3. **Pagination** -- support pagination for large address books
-4. **Incremental Sync** -- efficient sync with client devices
-5. **ETags** -- prevent unnecessary data transfers
-
-## Testing Strategy
-
-1. **Unit Tests** -- test individual components in isolation
-2. **Integration Tests** -- test component interactions
-3. **Protocol Compliance Tests** -- verify adherence to the CardDAV spec (RFC 6352)
-4. **Client Compatibility Tests** -- test with various CardDAV clients
-5. **Performance Tests** -- measure performance with large address books
diff --git a/doc/chunked-uploads.md b/doc/chunked-uploads.md
deleted file mode 100644
index 453bcfa1..00000000
--- a/doc/chunked-uploads.md
+++ /dev/null
@@ -1,175 +0,0 @@
-# 07 - Chunked Uploads
-
-OxiCloud implements a TUS-like chunked upload protocol for large files (≥10 MB). Files are split into chunks (default 5 MB) that can be uploaded in parallel (up to 6 concurrent), with progress tracking, optional MD5 checksums, and automatic session expiration.
-
-## Architecture
-
-| Layer | Component | File |
-|---|---|---|
-| Application Port | **ChunkedUploadPort** trait + DTOs | `src/application/ports/chunked_upload_ports.rs` |
-| Infrastructure | **ChunkedUploadService** | `src/infrastructure/services/chunked_upload_service.rs` |
-| Interfaces | **ChunkedUploadHandler** | `src/interfaces/api/handlers/chunked_upload_handler.rs` |
-
-## Constants
-
-| Constant | Value | Description |
-|---|---|---|
-| `CHUNKED_UPLOAD_THRESHOLD` | 10 MB | Files above this should use chunked upload |
-| `DEFAULT_CHUNK_SIZE` | 5 MB | Default chunk size (minimum 1 MB) |
-| `MAX_PARALLEL_CHUNKS` | 6 | Maximum concurrent chunk uploads |
-| `SESSION_EXPIRATION` | 24 hours | Sessions expire after this duration |
-
-## REST API
-
-All routes under `/api/uploads`, authentication required.
-
-| Method | Path | Handler | Description |
-|---|---|---|---|
-| `POST` | `/api/uploads` | `create_upload` | Create upload session |
-| `PATCH` | `/api/uploads/{upload_id}` | `upload_chunk` | Upload a single chunk |
-| `HEAD` | `/api/uploads/{upload_id}` | `get_upload_status` | Query upload progress |
-| `POST` | `/api/uploads/{upload_id}/complete` | `complete_upload` | Assemble chunks → create file |
-| `DELETE` | `/api/uploads/{upload_id}` | `cancel_upload` | Cancel and cleanup |
-
-## Protocol Flow
-
-```
-1. POST /api/uploads
- Body: { "filename": "video.mp4", "total_size": 104857600, "content_type": "video/mp4" }
- Response: { "upload_id": "abc-123", "chunk_size": 5242880, "total_chunks": 20, "expires_at": 1707868800 }
-
-2. PATCH /api/uploads/abc-123?chunk_index=0 ──┐
- PATCH /api/uploads/abc-123?chunk_index=1 ──┼── Up to 6 in parallel
- PATCH /api/uploads/abc-123?chunk_index=2 ──┘
- Body: raw chunk bytes
- Response: { "chunk_index": 0, "bytes_received": 52428800, "progress": 50.0, "is_complete": false }
-
-3. HEAD /api/uploads/abc-123
- Response headers: Upload-Offset, Upload-Length, Upload-Progress, Upload-Chunks-Total, Upload-Chunks-Complete
-
-4. POST /api/uploads/abc-123/complete
- Response: { "file_id": "def-456", "filename": "video.mp4", "size": 104857600, "path": "/videos" }
- Status: 201 Created
-```
-
-## Request/Response DTOs
-
-### Create Upload Request
-
-```rust
-pub struct CreateUploadRequest {
- pub filename: String,
- pub folder_id: Option,
- pub content_type: Option, // default: "application/octet-stream"
- pub total_size: u64,
- pub chunk_size: Option, // default: 5 MB, minimum: 1 MB
-}
-```
-
-### Chunk Upload Query Parameters
-
-```rust
-pub struct ChunkUploadParams {
- pub chunk_index: usize,
- pub checksum: Option, // MD5 hash (also via Content-MD5 header)
-}
-```
-
-### Upload Status Response
-
-```rust
-pub struct UploadStatusResponseDto {
- pub upload_id: String,
- pub filename: String,
- pub total_size: u64,
- pub bytes_received: u64,
- pub progress: f64, // 0.0 - 100.0
- pub total_chunks: usize,
- pub completed_chunks: usize,
- pub pending_chunks: Vec,
- pub is_complete: bool,
-}
-```
-
-### Complete Upload Response
-
-```rust
-pub struct CompleteUploadResponse {
- pub file_id: String,
- pub filename: String,
- pub size: u64,
- pub path: String,
-}
-```
-
-## Custom Response Headers
-
-### On upload_chunk (PATCH)
-- `Upload-Offset`: total bytes received so far
-- `Upload-Progress`: percentage complete (0-100)
-- `Upload-Complete: true` (only when all chunks are uploaded)
-
-### On get_upload_status (HEAD)
-- `Upload-Offset`: bytes received
-- `Upload-Length`: total expected size
-- `Upload-Progress`: percentage
-- `Upload-Chunks-Total`: total chunk count
-- `Upload-Chunks-Complete`: completed chunk count
-
-## Internal Storage
-
-```
-/
- /
- chunk_000000 ← individual chunk files
- chunk_000001
- chunk_000002
- ...
- assembled ← final assembled file (after complete)
-```
-
-## Completion Flow
-
-1. `complete_upload()` assembles all chunks in order into a single `assembled` file
-2. Reads the assembled file content
-3. Delegates to **FileUploadService::upload_file()** to create the permanent file record
-4. Calls `finalize_upload()` to clean up the session and temp directory
-5. Returns `201 Created` with file metadata
-
-## Session Management
-
-- **In-memory sessions**: `HashMap` protected by `RwLock`
-- **Chunk status tracking**: each chunk has a status: `Pending` → `Uploading` → `Complete` (or `Failed`)
-- **Expiration**: sessions expire after 24 hours of inactivity
-- **Cleanup**: background task runs hourly to remove expired sessions and orphaned temp directories
-
-## Client Usage Example
-
-```bash
-# 1. Create upload session
-RESPONSE=$(curl -s -X POST -H "Authorization: Bearer $TOKEN" \
- -H "Content-Type: application/json" \
- -d '{"filename":"large-file.zip","total_size":52428800}' \
- "https://oxicloud.example.com/api/uploads")
-
-UPLOAD_ID=$(echo $RESPONSE | jq -r '.upload_id')
-CHUNK_SIZE=$(echo $RESPONSE | jq -r '.chunk_size')
-TOTAL_CHUNKS=$(echo $RESPONSE | jq -r '.total_chunks')
-
-# 2. Upload chunks in parallel
-for i in $(seq 0 $((TOTAL_CHUNKS - 1))); do
- dd if=large-file.zip bs=$CHUNK_SIZE skip=$i count=1 2>/dev/null | \
- curl -s -X PATCH -H "Authorization: Bearer $TOKEN" \
- --data-binary @- \
- "https://oxicloud.example.com/api/uploads/$UPLOAD_ID?chunk_index=$i" &
-done
-wait
-
-# 3. Complete upload
-curl -X POST -H "Authorization: Bearer $TOKEN" \
- "https://oxicloud.example.com/api/uploads/$UPLOAD_ID/complete"
-
-# 4. Check progress (optional)
-curl -I -H "Authorization: Bearer $TOKEN" \
- "https://oxicloud.example.com/api/uploads/$UPLOAD_ID"
-```
diff --git a/doc/database-transactions.md b/doc/database-transactions.md
deleted file mode 100644
index 402e3bc3..00000000
--- a/doc/database-transactions.md
+++ /dev/null
@@ -1,119 +0,0 @@
-# 19 - Database Transactions
-
-OxiCloud uses explicit transactions on PostgreSQL to guarantee data integrity. All transactional operations follow ACID properties:
-
-- **Atomicity** -- all-or-nothing. If any part fails, the entire transaction fails.
-- **Consistency** -- the database moves from one valid state to another.
-- **Isolation** -- concurrent transactions behave as if sequential.
-- **Durability** -- once committed, the transaction survives system failures.
-
-## Implementation
-
-The **with_transaction** helper wraps the standard pattern: begin, execute, commit on success, rollback on error.
-
-### Transaction Utility
-
-Located in `src/infrastructure/repositories/pg/transaction_utils.rs`:
-
-```rust
-/// Helper function to execute database operations in a transaction
-pub async fn with_transaction(
- pool: &Arc,
- operation_name: &str,
- operation: F,
-) -> Result
-where
- F: for<'c> FnOnce(&'c mut Transaction<'_, Postgres>) -> futures::future::BoxFuture<'c, Result>,
- E: From + std::fmt::Display
-{ ... }
-```
-
-This function takes a connection pool and a closure with operations, handles begin/commit/rollback automatically, and provides detailed logging of the transaction lifecycle.
-
-### Repository Usage Example
-
-```rust
-// Creación de un usuario con transacción explícita
-async fn create_user(&self, user: User) -> UserRepositoryResult {
- with_transaction(
- &self.pool,
- "create_user",
- |tx| {
- Box::pin(async move {
- // Operación principal - insertar usuario
- sqlx::query("INSERT INTO auth.users ...")
- .bind(...)
- .execute(&mut **tx)
- .await?;
-
- // Operaciones adicionales dentro de la misma transacción
- // ...
-
- Ok(user_clone)
- })
- }
- ).await
-}
-```
-
-## Use Cases
-
-### UserPgRepository
-
-1. **User creation** -- guarantees all insert operations are atomic. Allows related operations (like permission setup) to be bundled.
-
-2. **User update** -- ensures modifications apply fully or not at all. Supports combined operations like profile info and preference updates.
-
-### SessionPgRepository
-
-1. **Session creation** -- inserts the session and updates the user's last-access timestamp in a single transaction. Keeps sessions and user data consistent.
-
-2. **Session revocation** -- ensures revoking one or all sessions for a user is atomic. Allows logging security events within the same transaction.
-
-## Isolation Levels
-
-OxiCloud supports different transaction isolation levels via **with_transaction_isolation**:
-
-```rust
-// Ejemplo de uso con nivel de aislamiento específico
-with_transaction_isolation(
- &pool,
- "operacion_critica",
- sqlx::postgres::PgIsolationLevel::Serializable,
- |tx| { ... }
-).await
-```
-
-Available isolation levels:
-
-1. **Read Committed** (default) -- guarantees reads see only committed data. Does not prevent non-repeatable or phantom reads.
-
-2. **Repeatable Read** -- guarantees consistent reads throughout the transaction. Prevents non-repeatable reads but not phantom reads.
-
-3. **Serializable** -- highest isolation level. Transactions behave as if executed serially. Can cause serialization errors that require retry.
-
-## Best Practices
-
-1. **Transaction duration** -- keep transactions as short as possible. Avoid long-running operations inside them.
-
-2. **Error handling** -- errors inside a transaction trigger automatic rollback. Use proper logging to diagnose failures.
-
-3. **Transaction boundaries** -- define clearly where transactions begin and end. Group related operations into a single transaction.
-
-4. **Appropriate isolation** -- use the lowest isolation level that fits the use case. Consider serializable for critical operations with conflict potential.
-
-## Benefits
-
-- **Data integrity** -- ACID guarantees for complex operations, prevents inconsistent states.
-- **Error handling** -- automatic rollback on failure, predictable behavior.
-- **Safe concurrency** -- proper handling of simultaneous operations, prevents race conditions.
-- **Performance** -- fewer round-trips to the database, batch operations for better efficiency.
-
-## Performance Considerations
-
-Transactions add some overhead. Performance can be affected by:
-
-- Transaction duration
-- Isolation level
-- Number of affected records
-- Lock contention
diff --git a/doc/dav-client-setup.md b/doc/dav-client-setup.md
deleted file mode 100644
index 0318604d..00000000
--- a/doc/dav-client-setup.md
+++ /dev/null
@@ -1,309 +0,0 @@
-# 25 - DAV Client Setup
-
-Step-by-step instructions for connecting native OS clients via WebDAV, CalDAV, and CardDAV. Covers Windows, macOS, Linux, iOS, and Android.
-
-## Table of Contents
-
-- [WebDAV Setup](#webdav-setup) (File Access)
-- [CalDAV Setup](#caldav-setup) (Calendar Sync)
-- [CardDAV Setup](#carddav-setup) (Contact Sync)
-- [Troubleshooting](#troubleshooting)
-
----
-
-## WebDAV Setup
-
-### Connection Information
-
-- **Server URL**: `https://[your-oxicloud-server]/webdav/`
-- **Username**: Your OxiCloud username
-- **Password**: Your OxiCloud password
-
-### Windows
-
-#### Windows 10/11 (File Explorer)
-
-1. Open File Explorer
-2. Right-click on "This PC" and select "Add a network location"
-3. Click "Next"
-4. Select "Choose a custom network location" and click "Next"
-5. Enter the WebDAV URL: `https://[your-oxicloud-server]/webdav/`
-6. When prompted, enter your username and password
-7. Give the connection a name (e.g., "OxiCloud") and click "Next"
-8. Click "Finish"
-
-Files now appear as a network drive in File Explorer.
-
-#### Alternative: Map Network Drive
-
-1. Open File Explorer
-2. Right-click on "This PC" and select "Map network drive"
-3. Choose a drive letter
-4. Enter the WebDAV URL: `https://[your-oxicloud-server]/webdav/`
-5. Check "Connect using different credentials"
-6. Click "Finish"
-7. Enter your username and password
-
-**Windows Troubleshooting:**
-
-If connections fail on Windows:
-
-1. Open Registry Editor (regedit.exe)
-2. Navigate to `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WebClient\Parameters`
-3. Modify **BasicAuthLevel** to value `2`
-4. Restart the WebClient service or reboot
-
-To increase the file size limit:
-1. In the same registry location, modify **FileSizeLimitInBytes** to a higher value (e.g., `4294967295` for 4GB)
-2. Restart the WebClient service
-
-### macOS
-
-#### Finder
-
-1. Open Finder
-2. From the menu bar, click "Go" > "Connect to Server" (or press Cmd+K)
-3. Enter the WebDAV URL: `https://[your-oxicloud-server]/webdav/`
-4. Click "Connect"
-5. Enter your username and password
-6. Click "Connect"
-
-Files appear as a mounted drive in Finder.
-
-### Linux
-
-#### GNOME (Nautilus)
-
-1. Open Files (Nautilus)
-2. Click the "+" button in the sidebar or press Ctrl+L
-3. Enter: `davs://[your-oxicloud-server]/webdav/`
-4. Enter credentials when prompted
-5. Click "Connect"
-
-#### KDE (Dolphin)
-
-1. Open Dolphin
-2. In the address bar, enter: `webdavs://[your-oxicloud-server]/webdav/`
-3. Enter credentials when prompted
-4. Click "Connect"
-
-#### Command Line (davfs2)
-
-1. Install davfs2: `sudo apt-get install davfs2` (Debian/Ubuntu) or equivalent
-2. Create a mount point: `sudo mkdir /mnt/oxicloud`
-3. Edit `/etc/davfs2/secrets` and add: `/mnt/oxicloud [username] [password]`
-4. Mount: `sudo mount -t davfs https://[your-oxicloud-server]/webdav/ /mnt/oxicloud`
-
-To auto-mount at boot, add to `/etc/fstab`:
-```
-https://[your-oxicloud-server]/webdav/ /mnt/oxicloud davfs user,rw,auto 0 0
-```
-
----
-
-## CalDAV Setup
-
-### Apple Calendar (macOS/iOS)
-
-#### macOS:
-
-1. Open the Calendar app
-2. Go to **Calendar** > **Add Account** > **Other CalDAV Account**
-3. Enter:
- - **Account Type**: Advanced
- - **Username**: Your OxiCloud username
- - **Password**: Your OxiCloud password
- - **Server Address**: `https://[your-oxicloud-server]/caldav`
-4. Click **Sign In**
-5. Select the calendars you want to sync and click **Done**
-
-#### iOS:
-
-1. Go to **Settings** > **Calendar** > **Accounts** > **Add Account** > **Other**
-2. Tap **Add CalDAV Account**
-3. Enter:
- - **Server**: `https://[your-oxicloud-server]/caldav`
- - **Username**: Your OxiCloud username
- - **Password**: Your OxiCloud password
- - **Description**: OxiCloud Calendar (or any name)
-4. Tap **Next**
-5. Turn on **Calendars** and tap **Save**
-
-### Thunderbird with Lightning
-
-1. Open Thunderbird and go to the **Calendar** tab
-2. Right-click in the left pane and select **New Calendar**
-3. Select **On the Network** and click **Next**
-4. Choose **CalDAV** as the format
-5. Enter the location: `https://[your-oxicloud-server]/caldav/calendars/your-calendar-id`
-6. Click **Next**
-7. Enter a name for the calendar and choose a color
-8. Click **Next** and then **Finish**
-9. When prompted, enter your username and password
-
-### Android (DAVx5)
-
-1. Install [DAVx5](https://play.google.com/store/apps/details?id=at.bitfire.davdroid) from Google Play Store
-2. Open DAVx5 and tap the **+** button
-3. Select **Login with URL and username**
-4. Enter:
- - **Base URL**: `https://[your-oxicloud-server]/caldav`
- - **Username**: Your OxiCloud username
- - **Password**: Your OxiCloud password
-5. Tap **Connect**
-6. Select the calendars you want to sync
-7. Tap the checkbox to enable syncing
-
-### Windows (Outlook)
-
-1. Download and install [CalDAV Synchronizer](https://caldavsynchronizer.org/)
-2. Open Outlook and navigate to the **CalDAV Synchronizer** tab
-3. Click **Synchronization Profiles**
-4. Click **Add** to create a new profile
-5. Enter:
- - **Profile Name**: OxiCloud Calendar (or any name)
- - **CalDAV URL**: `https://[your-oxicloud-server]/caldav/calendars/your-calendar-id`
- - **Username**: Your OxiCloud username
- - **Password**: Your OxiCloud password
-6. Click **Test or discover settings**
-7. Select the Outlook calendar to sync with
-8. Click **OK** to save the profile
-
----
-
-## CardDAV Setup
-
-### Apple Contacts (macOS/iOS)
-
-#### macOS:
-
-1. Open the Contacts app
-2. Go to **Contacts** > **Add Account** > **Other contacts account**
-3. Select **CardDAV account**
-4. Enter:
- - **Server**: `https://[your-oxicloud-server]/carddav`
- - **Username**: Your OxiCloud username
- - **Password**: Your OxiCloud password
- - **Description**: OxiCloud Contacts (or any name)
-5. Click **Sign In**
-
-#### iOS:
-
-1. Go to **Settings** > **Contacts** > **Accounts** > **Add Account** > **Other**
-2. Tap **Add CardDAV Account**
-3. Enter:
- - **Server**: `https://[your-oxicloud-server]/carddav`
- - **Username**: Your OxiCloud username
- - **Password**: Your OxiCloud password
- - **Description**: OxiCloud Contacts (or any name)
-4. Tap **Next**
-5. Turn on **Contacts** and tap **Save**
-
-### Thunderbird
-
-1. Open Thunderbird and go to the **Address Book**
-2. Click on **Tools** > **Address Book**
-3. Go to **File** > **New** > **Remote Address Book**
-4. Enter:
- - **Name**: OxiCloud Contacts (or any name)
- - **URL**: `https://[your-oxicloud-server]/carddav/address-books/your-address-book-id`
-5. Click **OK**
-6. When prompted, enter your username and password
-
-### Android (DAVx5)
-
-1. Install [DAVx5](https://play.google.com/store/apps/details?id=at.bitfire.davdroid) from Google Play Store
-2. Open DAVx5 and tap the **+** button
-3. Select **Login with URL and username**
-4. Enter:
- - **Base URL**: `https://[your-oxicloud-server]/carddav`
- - **Username**: Your OxiCloud username
- - **Password**: Your OxiCloud password
-5. Tap **Connect**
-6. Select the address books you want to sync
-7. Tap the checkbox to enable syncing
-
-### Windows (Outlook)
-
-1. Download and install [CardDAV Synchronizer](https://caldavsynchronizer.org/) (same tool as CalDAV)
-2. Open Outlook and navigate to the **CardDAV Synchronizer** tab
-3. Click **Synchronization Profiles**
-4. Click **Add** to create a new profile
-5. Select **CardDAV** as the synchronization resource
-6. Enter:
- - **Profile Name**: OxiCloud Contacts (or any name)
- - **CardDAV URL**: `https://[your-oxicloud-server]/carddav/address-books/your-address-book-id`
- - **Username**: Your OxiCloud username
- - **Password**: Your OxiCloud password
-7. Click **Test or discover settings**
-8. Select the Outlook contacts folder to sync with
-9. Click **OK** to save the profile
-
----
-
-## Troubleshooting
-
-### Common Issues
-
-#### WebDAV Connection Issues
-
-- Verify the server URL includes the `/webdav/` path
-- Double-check username and password
-- Check if your network blocks ports 80/443
-- Confirm WebDAV is enabled on the server
-
-#### Calendar/Contact Sync Issues
-
-- Verify the server URL includes the full path (`/caldav` or `/carddav`)
-- Confirm the server is reachable from your network
-- Verify the calendar or address book ID is correct
-- Check you have proper permissions for the resource
-
-#### Calendar Not Showing
-
-- Confirm the calendar is enabled in your client
-- Check if the calendar is shared with your account
-- Ensure your client supports the CalDAV protocol version in use
-
-#### Contact Photos Not Syncing
-
-- Some clients have photo sync limitations
-- Verify the photo is in a supported format (usually JPEG)
-- Check photo size limits on the client side
-
-### Client-Specific Issues
-
-#### Windows File Explorer
-
-- Make sure the **WebClient** service is running
-- Increase timeout values in the registry
-- Try a third-party WebDAV client like Cyberduck
-
-#### iOS Devices
-
-- If connection fails, try **Settings** > **Accounts & Passwords** and add the account manually
-- For persistent issues, remove the account and re-add it
-
-#### Android
-
-- DAVx5 requires battery optimization to be disabled for reliable background sync
-- Go to **Settings** > **Apps** > **DAVx5** > **Battery** > **Unrestricted**
-
-#### Outlook
-
-- Make sure you have the latest version of CalDAV/CardDAV Synchronizer
-- The plugin may need reactivation after Outlook updates
-
-### Performance Tips
-
-1. **Large Files** -- for files over 100MB, download locally before editing
-2. **Slow Connections** -- enable offline caching in your client when available
-3. **File Locking** -- some clients support WebDAV locking to prevent conflicts
-
-### Getting Help
-
-If issues persist:
-
-1. Check the server logs for error messages
-2. Capture screenshots of any errors
-3. Contact support with details about your client application, version, steps to reproduce, and error messages
diff --git a/doc/dav-implementation-plan.md b/doc/dav-implementation-plan.md
deleted file mode 100644
index 1ecbbebd..00000000
--- a/doc/dav-implementation-plan.md
+++ /dev/null
@@ -1,286 +0,0 @@
-# 24 - DAV Implementation Plan
-
-A phased plan for adding WebDAV, CalDAV, and CardDAV support. The order is WebDAV first (file access), then CalDAV (calendars), then CardDAV (contacts). Each phase builds on the shared infrastructure from phase 1.
-
-## Executive Summary
-
-DAV protocol support lets the platform interoperate with a wide range of clients and devices. The plan uses an incremental approach -- common infrastructure first, then each protocol in turn.
-
-## Implementation Phases
-
-### Phase 1: Common DAV Infrastructure (Est. 2-3 weeks)
-
-**Goals:**
-- Build the shared infrastructure used by all DAV protocols
-- Implement XML request/response handling
-- Create adapters for basic DAV operations
-
-**Tasks:**
-1. **Week 1: Design and Architecture**
- - Design DAV component architecture
- - Define interfaces for DAV adapters
- - Select libraries for XML processing and RFC 4918 support
-
-2. **Week 2: Base Implementation**
- - Implement XML serialization/deserialization handlers
- - Develop middleware for DAV request processing
- - Create shared structures (properties, namespaces)
- - Implement DAV request validation
-
-3. **Week 3: Test Framework**
- - Set up test environment for DAV protocols
- - Implement automated test clients
- - Create test cases for basic DAV operations
-
-**Deliverables:**
-- XML processing framework for DAV requests/responses
-- Base adapters for existing entities
-- Test suite for DAV operations
-
-### Phase 2: WebDAV (Est. 3-4 weeks)
-
-**Goals:**
-- Implement the full WebDAV protocol (RFC 4918)
-- Enable file and folder access via WebDAV
-- Ensure compatibility with common WebDAV clients
-
-**Tasks:**
-1. **Week 1: Basic Operations**
- - Implement **PROPFIND** and **PROPPATCH** methods
- - Develop **OPTIONS** endpoint (capability discovery)
- - Implement **GET**, **HEAD**, **PUT** (read/write)
-
-2. **Week 2: Advanced Operations**
- - Implement **MKCOL** (directory creation)
- - Develop **DELETE** for WebDAV resources
- - Implement **COPY** and **MOVE** for files and directories
-
-3. **Week 3: Locking and Extended Features**
- - Implement **LOCK** and **UNLOCK** for resources
- - Add support for custom properties
- - Develop extended WebDAV features as needed
-
-4. **Week 4: Testing and Optimization**
- - Test with real clients (Windows, macOS, Linux)
- - Optimize performance for large transfers
- - Document WebDAV API and behavior
-
-**Deliverables:**
-- Full WebDAV implementation (RFC 4918)
-- Usage documentation
-- Compatibility with the most common WebDAV clients
-
-### Phase 3: CalDAV (Est. 4-5 weeks)
-
-**Goals:**
-- Implement the CalDAV protocol (RFC 4791)
-- Create entities and repositories for calendars and events
-- Support calendar operations with common clients
-
-**Tasks:**
-1. **Week 1: Data Model**
- - Implement **Calendar** and **CalendarEvent** entities
- - Develop storage repositories
- - Create CalDAV DTOs and adapters
-
-2. **Week 2: Basic Endpoints**
- - Implement **PROPFIND** for calendar discovery
- - Develop **MKCALENDAR** for calendar creation
- - Implement **GET**/**PUT** for individual events
-
-3. **Week 3: Advanced Queries**
- - Implement **REPORT** for calendar queries
- - Develop date-range search support
- - Add recurrence handling (**RRULE** rules)
-
-4. **Week 4: Interoperability**
- - Implement efficient sync (**collection-sync**)
- - Add timezone support
- - Develop alarm and notification handling
-
-5. **Week 5: Testing and Refinement**
- - Test with popular CalDAV clients
- - Optimize performance for large calendars
- - Document CalDAV API and behavior
-
-**Deliverables:**
-- Full CalDAV implementation (RFC 4791)
-- Calendar creation and management support
-- Compatibility with popular CalDAV clients
-- CalDAV usage documentation
-
-### Phase 4: CardDAV (Est. 3-4 weeks)
-
-**Goals:**
-- Implement the CardDAV protocol (RFC 6352)
-- Create entities and repositories for address books and contacts
-- Support contact operations with common clients
-
-**Tasks:**
-1. **Week 1: Data Model**
- - Implement **AddressBook** and **Contact** entities
- - Develop storage repositories
- - Create CardDAV DTOs and adapters
-
-2. **Week 2: Basic Endpoints**
- - Implement **PROPFIND** for address book discovery
- - Develop **MKCOL** for address book creation
- - Implement **GET**/**PUT** for individual contacts
-
-3. **Week 3: Queries and Search**
- - Implement **REPORT** for contact queries
- - Develop criteria-based contact search
- - Add support for contact groups
-
-4. **Week 4: Testing and Refinement**
- - Test with popular CardDAV clients
- - Optimize performance for large address books
- - Document CardDAV API and behavior
-
-**Deliverables:**
-- Full CardDAV implementation (RFC 6352)
-- Address book creation and management support
-- Compatibility with popular CardDAV clients
-- CardDAV usage documentation
-
-### Phase 5: Integration and Release (Est. 2-3 weeks)
-
-**Goals:**
-- Integrate all DAV protocols into a cohesive solution
-- Ensure cross-protocol compatibility
-- Prepare documentation and release materials
-
-**Tasks:**
-1. **Week 1: Integration**
- - Consolidate shared code across protocols
- - Ensure behavioral consistency
- - Refine error handling and recovery
-
-2. **Week 2: System Testing**
- - Run end-to-end integration tests
- - Validate performance under load
- - Verify security and permissions
-
-3. **Week 3: Documentation and Release**
- - Finalize user guides for DAV clients
- - Create developer documentation
- - Prepare release package
-
-**Deliverables:**
-- Complete, integrated DAV solution
-- User and developer documentation
-- Release-ready deployment package
-
-## Infrastructure Requirements
-
-### Library Dependencies
-
-```toml
-# Add to Cargo.toml
-[dependencies]
-# XML processing
-quick-xml = "0.30.0"
-xml-rs = "0.8.14"
-
-# iCalendar support
-icalendar = "0.15.0"
-
-# vCard support
-vcard = "0.2.0"
-
-# DAV utilities
-http-multipart = "0.3.0"
-```
-
-### Database Schema
-
-New tables for CalDAV and CardDAV are created during their respective phases. See `dav-integration.md` for the full schema.
-
-## Testing Strategy
-
-### Unit Tests
-
-- XML serialization/deserialization tests
-- Input validation tests
-- Business logic tests for each DAV operation
-
-### Integration Tests
-
-- End-to-end tests with simulated clients
-- Full-flow tests (create, update, delete)
-- Concurrency and conflict handling tests
-
-### Compatibility Tests
-
-- Test matrix with real clients (at least 3 per protocol)
-- Testing across different operating systems
-- RFC conformance verification
-
-## Performance Considerations
-
-1. **Query Optimization**
- - Implement pagination for large result sets
- - Optimize SQL queries for calendars and contacts
- - Use proper indexes for fast lookups
-
-2. **Caching**
- - Cache properties for **PROPFIND** responses
- - Use ETags for cache validation
- - Apply query caching for frequent reports
-
-3. **Efficient Processing**
- - Efficient XML processing for large requests
- - Data streaming for large files
- - Async processing for expensive operations
-
-## Risks and Mitigation
-
-| Risk | Impact | Likelihood | Mitigation Strategy |
-|------|--------|------------|---------------------|
-| Client compatibility issues | High | Medium | Early testing with a variety of clients, strict adherence to specs |
-| Insufficient performance | Medium | Low | Load testing from the start, design for scalability |
-| Excessive complexity | Medium | Medium | Modular approach, clear abstractions, frequent code reviews |
-| Security vulnerabilities | High | Low | Security reviews, strict input validation, penetration testing |
-| Schedule delays | Medium | Medium | Conservative planning, clear milestones, iterative approach |
-
-## Success Criteria
-
-1. **Compatibility**
- - All protocols comply with their respective RFCs
- - Verified compatibility with at least 3 major clients per protocol
- - Works on all major operating systems
-
-2. **Performance**
- - Typical operation response time < 500ms
- - Supports calendars with 1000+ events without significant degradation
- - Supports address books with 1000+ contacts without significant degradation
-
-3. **Usability**
- - Simple, documented client setup process
- - Clear and specific error messages
- - Full documentation for users and developers
-
-## Required Resources
-
-1. **Development Team**
- - 1-2 backend developers (Rust)
- - 1 frontend developer (for UI integration if needed)
- - 1 tester
-
-2. **Infrastructure**
- - Multi-OS test environment
- - Assorted DAV clients for testing
- - CI/CD server for automated tests
-
-3. **Skills**
- - Experience with advanced HTTP protocols
- - XML processing knowledge
- - Familiarity with WebDAV, CalDAV, and CardDAV standards
-
-## Next Steps
-
-1. Assign resources to the project
-2. Set up code repository and initial structure
-3. Start Phase 1 (Common DAV Infrastructure)
-4. Configure CI/CD environment for testing
-5. Review and refine the plan as needed during implementation
diff --git a/doc/dav-integration.md b/doc/dav-integration.md
deleted file mode 100644
index e5717934..00000000
--- a/doc/dav-integration.md
+++ /dev/null
@@ -1,637 +0,0 @@
-# 23 - DAV Integration
-
-WebDAV, CalDAV, and CardDAV extend the platform to support clients and devices that speak these standard protocols. The implementation follows the existing hexagonal architecture -- each protocol gets its own adapter, service, and domain layer.
-
-## Table of Contents
-
-1. [Introduction](#introduction)
-2. [Implementation Architecture](#implementation-architecture)
-3. [WebDAV](#webdav)
-4. [CalDAV](#caldav)
-5. [CardDAV](#carddav)
-6. [Security Considerations](#security-considerations)
-7. [Testing and Compatibility](#testing-and-compatibility)
-
-## Introduction
-
-### WebDAV (Web Distributed Authoring and Versioning)
-An HTTP extension that lets clients create, modify, move, and delete files and directories on a remote server.
-
-### CalDAV (Calendaring Extensions to WebDAV)
-A WebDAV-based protocol for accessing and managing calendar data (events and tasks).
-
-### CardDAV (vCard Extensions to WebDAV)
-Extends WebDAV to allow access and management of contact data in vCard format.
-
-## Implementation Architecture
-
-DAV protocols plug into the existing hexagonal architecture:
-
-```
-┌────────────────────────────────────────────────────────────────────┐
-│ INTERFACES │
-│ │
-│ ┌───────────────┐ ┌───────────────┐ ┌───────────────────────┐ │
-│ │ │ │ │ │ │ │
-│ │ REST API │ │ WebDAV API │ │ CalDAV/CardDAV API │ │
-│ │ │ │ │ │ │ │
-│ └───────┬───────┘ └───────┬───────┘ └───────────┬───────────┘ │
-│ │ │ │ │
-└──────────┼──────────────────┼──────────────────────┼──────────────┘
- │ │ │
- ▼ ▼ ▼
-┌──────────────────────────────────────────────────────────────────┐
-│ APPLICATION │
-│ │
-│ ┌───────────┐ ┌────────────┐ ┌───────────┐ ┌──────────────┐ │
-│ │ │ │ │ │ │ │ │ │
-│ │FileService│ │FolderService│ │CalendarSvc│ │ContactService│ │
-│ │ │ │ │ │ │ │ │ │
-│ └─────┬─────┘ └──────┬─────┘ └─────┬─────┘ └──────┬───────┘ │
-│ │ │ │ │ │
-└────────┼───────────────┼──────────────┼───────────────┼─────────┘
- │ │ │ │
- ▼ ▼ ▼ ▼
-┌────────────────────────────────────────────────────────────────┐
-│ DOMAIN │
-│ │
-│ ┌─────────┐ ┌──────────┐ ┌────────────┐ ┌───────────────┐ │
-│ │ │ │ │ │ │ │ │ │
-│ │ File │ │ Folder │ │ Calendar │ │ Contact │ │
-│ │ │ │ │ │ │ │ │ │
-│ └─────────┘ └──────────┘ └────────────┘ └───────────────┘ │
-│ │
-└────────────────────────────────────────────────────────────────┘
-```
-
-### Main Components
-
-1. **DAV Adapters** -- convert between DAV specs and internal models
-2. **Application Services** -- extended to include DAV-specific functionality
-3. **Domain Models** -- new entities for **Calendar** and **Contact**
-4. **Repositories** -- storage implementations for calendars and contacts
-
-## WebDAV
-
-### Required Endpoints
-
-| HTTP Method | Endpoint | Description |
-|-------------|----------|-------------|
-| OPTIONS | /webdav/{path} | Reports supported WebDAV capabilities |
-| PROPFIND | /webdav/{path} | Retrieves resource properties |
-| PROPPATCH | /webdav/{path} | Modifies resource properties |
-| MKCOL | /webdav/{path} | Creates collections (directories) |
-| GET | /webdav/{path} | Retrieves resource content |
-| HEAD | /webdav/{path} | Retrieves resource metadata |
-| PUT | /webdav/{path} | Creates or updates resources |
-| DELETE | /webdav/{path} | Deletes resources |
-| COPY | /webdav/{path} | Copies resources |
-| MOVE | /webdav/{path} | Moves resources |
-| LOCK | /webdav/{path} | Locks resources |
-| UNLOCK | /webdav/{path} | Unlocks resources |
-
-### Implementation
-
-1. **WebDAV Handler**:
-
-```rust
-// src/interfaces/api/handlers/webdav_handler.rs
-use std::sync::Arc;
-use axum::{
- Router,
- routing::get,
- extract::{Path, State, Request, Extension},
- http::StatusCode,
- response::Response,
-};
-use http::{Method, header};
-
-use crate::common::di::AppState;
-use crate::interfaces::middleware::auth::CurrentUser;
-use crate::application::ports::file_ports::{FileRetrievalUseCase, FileUploadUseCase};
-use crate::application::ports::folder_ports::FolderUseCase;
-use crate::common::errors::AppError;
-
-pub fn webdav_routes() -> Router> {
- Router::new()
- .route("/webdav/*path", get(handle_get))
- .route_with_tsr("/webdav/*path", axum::routing::on(
- Method::OPTIONS, handle_options,
- Method::PROPFIND, handle_propfind,
- Method::PROPPATCH, handle_proppatch,
- Method::MKCOL, handle_mkcol,
- Method::PUT, handle_put,
- Method::DELETE, handle_delete,
- Method::COPY, handle_copy,
- Method::MOVE, handle_move,
- Method::LOCK, handle_lock,
- Method::UNLOCK, handle_unlock,
- ))
-}
-
-// Implement functions for each WebDAV method...
-```
-
-2. **WebDAV Adapter**:
-
-```rust
-// src/application/adapters/webdav_adapter.rs
-use xml::reader::{EventReader, XmlEvent};
-use xml::writer::{EventWriter, EmitterConfig, XmlEvent as WriteEvent};
-use std::io::{Read, Write};
-use crate::application::dtos::file_dto::FileDto;
-use crate::application::dtos::folder_dto::FolderDto;
-
-/// Converts between internal objects and WebDAV representations
-pub struct WebDavAdapter;
-
-impl WebDavAdapter {
- /// Parses a PROPFIND XML property into a request object
- pub fn parse_propfind(reader: R) -> Result {
- // Implementation...
- }
-
- /// Generates PROPFIND XML response from files and folders
- pub fn generate_propfind_response(
- writer: W,
- files: &[FileDto],
- folders: &[FolderDto],
- base_url: &str,
- ) -> Result<(), Error> {
- // Implementation...
- }
-
- // Other methods for different WebDAV operations...
-}
-```
-
-## CalDAV
-
-### Required Endpoints
-
-| HTTP Method | Endpoint | Description |
-|-------------|----------|-------------|
-| PROPFIND | /caldav/{calendar} | Retrieves calendar properties |
-| REPORT | /caldav/{calendar} | Queries calendar events |
-| MKCALENDAR | /caldav/{calendar} | Creates a new calendar |
-| PUT | /caldav/{calendar}/{event}.ics | Creates or updates an event |
-| GET | /caldav/{calendar}/{event}.ics | Retrieves an event |
-| DELETE | /caldav/{calendar}/{event}.ics | Deletes an event |
-
-### Implementation
-
-1. **Domain Entities**:
-
-```rust
-// src/domain/entities/calendar.rs
-use uuid::Uuid;
-use chrono::{DateTime, Utc};
-
-#[derive(Debug, Clone)]
-pub struct Calendar {
- id: Uuid,
- name: String,
- owner_id: String,
- description: Option,
- color: Option,
- created_at: DateTime,
- updated_at: DateTime,
-}
-
-// src/domain/entities/calendar_event.rs
-use uuid::Uuid;
-use chrono::{DateTime, Utc};
-
-#[derive(Debug, Clone)]
-pub struct CalendarEvent {
- id: Uuid,
- calendar_id: Uuid,
- summary: String,
- description: Option,
- location: Option,
- start_time: DateTime,
- end_time: DateTime,
- all_day: bool,
- rrule: Option, // Recurrence rule
- ical_data: String, // Full iCalendar data
- created_at: DateTime,
- updated_at: DateTime,
-}
-```
-
-2. **Repositories**:
-
-```rust
-// src/domain/repositories/calendar_repository.rs
-use async_trait::async_trait;
-use uuid::Uuid;
-use crate::domain::entities::calendar::Calendar;
-use crate::common::errors::Result;
-
-#[async_trait]
-pub trait CalendarRepository: Send + Sync {
- async fn create_calendar(&self, calendar: Calendar) -> Result;
- async fn get_calendar_by_id(&self, id: &Uuid) -> Result;
- async fn get_calendars_by_owner(&self, owner_id: &str) -> Result>;
- async fn update_calendar(&self, calendar: Calendar) -> Result;
- async fn delete_calendar(&self, id: &Uuid) -> Result<()>;
-}
-
-// src/domain/repositories/calendar_event_repository.rs
-use async_trait::async_trait;
-use uuid::Uuid;
-use chrono::{DateTime, Utc};
-use crate::domain::entities::calendar_event::CalendarEvent;
-use crate::common::errors::Result;
-
-#[async_trait]
-pub trait CalendarEventRepository: Send + Sync {
- async fn create_event(&self, event: CalendarEvent) -> Result;
- async fn get_event_by_id(&self, id: &Uuid) -> Result;
- async fn get_events_by_calendar(&self, calendar_id: &Uuid) -> Result>;
- async fn get_events_in_timerange(
- &self,
- calendar_id: &Uuid,
- start: &DateTime,
- end: &DateTime
- ) -> Result>;
- async fn update_event(&self, event: CalendarEvent) -> Result;
- async fn delete_event(&self, id: &Uuid) -> Result<()>;
-}
-```
-
-3. **CalDAV Service**:
-
-```rust
-// src/application/services/calendar_service.rs
-use std::sync::Arc;
-use crate::application::ports::calendar_ports::CalendarStoragePort;
-use crate::application::dtos::calendar_dto::*;
-
-pub struct CalendarService {
- storage: Arc,
-}
-
-impl CalendarService {
- pub fn new(storage: Arc) -> Self {
- Self { storage }
- }
-
- // Implements CalendarUseCase for calendar and event operations...
-}
-```
-
-4. **CalDAV Handler**:
-
-```rust
-// src/interfaces/api/handlers/caldav_handler.rs
-use std::sync::Arc;
-use axum::{
- Router,
- routing::{get, put, delete},
- extract::{Path, State, Request, Extension},
- http::StatusCode,
- response::Response,
-};
-use http::{Method, header};
-
-use crate::common::di::AppState;
-use crate::interfaces::middleware::auth::CurrentUser;
-use crate::application::services::caldav_service::CalDavService;
-use crate::common::errors::AppError;
-
-pub fn caldav_routes() -> Router> {
- Router::new()
- .route("/caldav/", get(get_calendars))
- .route("/caldav/:calendar", get(get_calendar))
- .route_with_tsr("/caldav/:calendar", axum::routing::on(
- Method::PROPFIND, handle_calendar_propfind,
- Method::REPORT, handle_calendar_report,
- Method::MKCALENDAR, handle_mkcalendar,
- ))
- .route("/caldav/:calendar/:event", get(get_event))
- .route("/caldav/:calendar/:event", put(put_event))
- .route("/caldav/:calendar/:event", delete(delete_event))
-}
-
-// Implement functions for each CalDAV method...
-```
-
-## CardDAV
-
-### Required Endpoints
-
-| HTTP Method | Endpoint | Description |
-|-------------|----------|-------------|
-| PROPFIND | /carddav/addressbooks/{addressbook} | Retrieves address book properties |
-| REPORT | /carddav/addressbooks/{addressbook} | Queries contacts |
-| MKCOL | /carddav/addressbooks/{addressbook} | Creates a new address book |
-| PUT | /carddav/addressbooks/{addressbook}/{contact}.vcf | Creates or updates a contact |
-| GET | /carddav/addressbooks/{addressbook}/{contact}.vcf | Retrieves a contact |
-| DELETE | /carddav/addressbooks/{addressbook}/{contact}.vcf | Deletes a contact |
-
-### Implementation
-
-1. **Domain Entities**:
-
-```rust
-// Note: AddressBook and Contact are both defined in src/domain/entities/contact.rs
-
-#[derive(Debug, Clone)]
-pub struct AddressBook {
- id: Uuid,
- name: String,
- owner_id: String,
- description: Option,
- color: Option,
- is_public: bool,
- created_at: DateTime,
- updated_at: DateTime,
-}
-
-#[derive(Debug, Clone)]
-pub struct Contact {
- id: Uuid,
- address_book_id: Uuid,
- uid: String,
- full_name: Option,
- first_name: Option,
- last_name: Option,
- nickname: Option,
- email: Vec, // Struct with email, type, is_primary
- phone: Vec, // Struct with number, type, is_primary
- address: Vec, // Struct with street, city, state, postal_code, country, type, is_primary
- organization: Option,
- title: Option,
- notes: Option,
- photo_url: Option,
- birthday: Option,
- anniversary: Option,
- vcard: String, // Full vCard data
- etag: String,
- created_at: DateTime,
- updated_at: DateTime,
-}
-```
-
-2. **Repositories**:
-
-```rust
-// src/domain/repositories/address_book_repository.rs
-use async_trait::async_trait;
-use uuid::Uuid;
-use crate::domain::entities::address_book::AddressBook;
-use crate::common::errors::Result;
-
-#[async_trait]
-pub trait AddressBookRepository: Send + Sync {
- async fn create_address_book(&self, address_book: AddressBook) -> Result;
- async fn get_address_book_by_id(&self, id: &Uuid) -> Result;
- async fn get_address_books_by_owner(&self, owner_id: &str) -> Result>;
- async fn update_address_book(&self, address_book: AddressBook) -> Result;
- async fn delete_address_book(&self, id: &Uuid) -> Result<()>;
-}
-
-// src/domain/repositories/contact_repository.rs
-use async_trait::async_trait;
-use uuid::Uuid;
-use crate::domain::entities::contact::Contact;
-use crate::common::errors::Result;
-
-#[async_trait]
-pub trait ContactRepository: Send + Sync {
- async fn create_contact(&self, contact: Contact) -> Result;
- async fn get_contact_by_id(&self, id: &Uuid) -> Result;
- async fn get_contacts_by_address_book(&self, address_book_id: &Uuid) -> Result>;
- async fn search_contacts(&self, address_book_id: &Uuid, query: &str) -> Result>;
- async fn update_contact(&self, contact: Contact) -> Result;
- async fn delete_contact(&self, id: &Uuid) -> Result<()>;
-}
-```
-
-3. **CardDAV Service**:
-
-```rust
-// src/application/services/contact_service.rs
-use std::sync::Arc;
-use crate::application::dtos::contact_dto::*;
-use crate::application::dtos::address_book_dto::*;
-
-pub struct ContactService {
- // Implements AddressBookUseCase and ContactUseCase
- // Uses ContactStorageAdapter as infrastructure
-}
-
-impl ContactService {
- // Implements methods for CardDAV operations...
-}
-```
-
-4. **CardDAV Handler**:
-
-```rust
-// src/interfaces/api/handlers/carddav_handler.rs
-use std::sync::Arc;
-use axum::{
- Router,
- routing::{get, put, delete},
- extract::{Path, State, Request, Extension},
- http::StatusCode,
- response::Response,
-};
-use http::{Method, header};
-
-use crate::common::di::AppState;
-use crate::interfaces::middleware::auth::CurrentUser;
-use crate::application::services::carddav_service::CardDavService;
-use crate::common::errors::AppError;
-
-pub fn carddav_routes() -> Router> {
- Router::new()
- .route("/carddav/addressbooks/", get(get_address_books))
- .route("/carddav/addressbooks/:addressbook", get(get_address_book))
- .route_with_tsr("/carddav/addressbooks/:addressbook", axum::routing::on(
- Method::PROPFIND, handle_addressbook_propfind,
- Method::REPORT, handle_addressbook_report,
- Method::MKCOL, handle_mkaddressbook,
- ))
- .route("/carddav/addressbooks/:addressbook/:contact", get(get_contact))
- .route("/carddav/addressbooks/:addressbook/:contact", put(put_contact))
- .route("/carddav/addressbooks/:addressbook/:contact", delete(delete_contact))
-}
-
-// Implement functions for each CardDAV method...
-```
-
-## Database Schema
-
-```sql
--- CalDAV schema
-CREATE SCHEMA IF NOT EXISTS caldav;
-
-CREATE TABLE IF NOT EXISTS caldav.calendars (
- id UUID PRIMARY KEY,
- name VARCHAR(255) NOT NULL,
- owner_id VARCHAR(36) NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
- description TEXT,
- color VARCHAR(50),
- is_public BOOLEAN NOT NULL DEFAULT FALSE,
- ctag VARCHAR(255),
- created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
- updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-
-CREATE TABLE IF NOT EXISTS caldav.calendar_events (
- id UUID PRIMARY KEY,
- calendar_id UUID NOT NULL REFERENCES caldav.calendars(id) ON DELETE CASCADE,
- summary VARCHAR(255) NOT NULL,
- description TEXT,
- location TEXT,
- start_time TIMESTAMPTZ NOT NULL,
- end_time TIMESTAMPTZ NOT NULL,
- all_day BOOLEAN NOT NULL DEFAULT FALSE,
- rrule TEXT,
- ical_uid VARCHAR(255) NOT NULL,
- ical_data TEXT NOT NULL,
- etag VARCHAR(255),
- created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
- updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-
-CREATE TABLE IF NOT EXISTS caldav.calendar_shares (
- id SERIAL PRIMARY KEY,
- calendar_id UUID NOT NULL REFERENCES caldav.calendars(id) ON DELETE CASCADE,
- user_id VARCHAR(36) NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
- access_level VARCHAR(20) NOT NULL DEFAULT 'read',
- UNIQUE(calendar_id, user_id)
-);
-
-CREATE TABLE IF NOT EXISTS caldav.calendar_properties (
- id SERIAL PRIMARY KEY,
- calendar_id UUID NOT NULL REFERENCES caldav.calendars(id) ON DELETE CASCADE,
- property_name VARCHAR(255) NOT NULL,
- property_value TEXT,
- UNIQUE(calendar_id, property_name)
-);
-
--- CardDAV schema
-CREATE SCHEMA IF NOT EXISTS carddav;
-
-CREATE TABLE IF NOT EXISTS carddav.address_books (
- id UUID PRIMARY KEY,
- name VARCHAR(255) NOT NULL,
- owner_id VARCHAR(36) NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
- description TEXT,
- color VARCHAR(50),
- is_public BOOLEAN NOT NULL DEFAULT FALSE,
- ctag VARCHAR(255),
- created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
- updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
- UNIQUE(owner_id, name)
-);
-
-CREATE TABLE IF NOT EXISTS carddav.contacts (
- id UUID PRIMARY KEY,
- address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
- uid VARCHAR(255) NOT NULL,
- full_name VARCHAR(255),
- first_name VARCHAR(255),
- last_name VARCHAR(255),
- nickname VARCHAR(255),
- organization VARCHAR(255),
- title VARCHAR(255),
- notes TEXT,
- photo_url TEXT,
- birthday DATE,
- anniversary DATE,
- email JSONB,
- phone JSONB,
- address JSONB,
- vcard TEXT NOT NULL,
- etag VARCHAR(255) NOT NULL,
- created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
- updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
- UNIQUE(address_book_id, uid)
-);
-
-CREATE TABLE IF NOT EXISTS carddav.address_book_shares (
- id SERIAL PRIMARY KEY,
- address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
- user_id VARCHAR(36) NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
- can_write BOOLEAN NOT NULL DEFAULT FALSE,
- UNIQUE(address_book_id, user_id)
-);
-
-CREATE TABLE IF NOT EXISTS carddav.contact_groups (
- id UUID PRIMARY KEY,
- address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
- name VARCHAR(255) NOT NULL,
- created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
- updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-
-CREATE TABLE IF NOT EXISTS carddav.group_memberships (
- id SERIAL PRIMARY KEY,
- group_id UUID NOT NULL REFERENCES carddav.contact_groups(id) ON DELETE CASCADE,
- contact_id UUID NOT NULL REFERENCES carddav.contacts(id) ON DELETE CASCADE,
- UNIQUE(group_id, contact_id)
-);
-
--- Indexes for efficient lookup
-CREATE INDEX IF NOT EXISTS idx_calendars_owner ON caldav.calendars(owner_id);
-CREATE INDEX IF NOT EXISTS idx_calendar_events_calendar ON caldav.calendar_events(calendar_id);
-CREATE INDEX IF NOT EXISTS idx_address_books_owner ON carddav.address_books(owner_id);
-CREATE INDEX IF NOT EXISTS idx_contacts_address_book ON carddav.contacts(address_book_id);
-CREATE INDEX IF NOT EXISTS idx_contacts_full_name ON carddav.contacts(full_name);
-```
-
-## Security Considerations
-
-1. **Authentication**
- - Uses existing authentication
- - Supports HTTP Basic Authentication for DAV clients
- - Digest authentication can be added if needed
-
-2. **Authorization**
- - Verify user permissions before granting resource access
- - Owner-based and shared-permission access control
- - Users can only access their own calendars and address books
-
-3. **Attack Prevention**
- - Validate and sanitize all XML input
- - Limit maximum payload size
- - Rate limiting on DAV endpoints
-
-## Testing and Compatibility
-
-### Clients to Test
-
-1. **WebDAV**
- - Windows Explorer
- - macOS Finder
- - Cyberduck
- - FileZilla (with WebDAV extension)
-
-2. **CalDAV**
- - Apple Calendar
- - Mozilla Thunderbird (Lightning)
- - Microsoft Outlook (with CalDAV add-in)
- - Google Calendar (via sync)
-
-3. **CardDAV**
- - Apple Contacts
- - Mozilla Thunderbird
- - Microsoft Outlook (with CardDAV add-in)
- - Google Contacts (via sync)
-
-### Compliance Testing
-
-- Use the **CalDAVTester** suite to verify standards conformance
-- Validate RFC compliance for each protocol
-- Stress tests to evaluate performance under load
-
-### Debugging
-
-- Detailed logging for DAV operations
-- Diagnostic tools for debugging complex DAV requests
-- Clear error messages for troubleshooting
diff --git a/doc/deduplication.md b/doc/deduplication.md
deleted file mode 100644
index 74d917d0..00000000
--- a/doc/deduplication.md
+++ /dev/null
@@ -1,456 +0,0 @@
-# 06 - Deduplication
-
-OxiCloud uses **content-defined chunking (CDC)** via FastCDC for sub-file deduplication. Files are split into variable-size chunks (64 KB – 1 MB, average 256 KB) using the FastCDC 2020 algorithm. Each chunk is individually BLAKE3-hashed and stored in a pluggable blob backend (local FS, S3, Azure). A PostgreSQL *manifest* maps the whole-file BLAKE3 hash to the ordered list of chunk hashes that compose it. Identical chunks across any files are stored once and reference-counted.
-
-Deduplication is always enabled and non-fatal — if dedup fails, file operations proceed normally with a warning log.
-
-**Backward compatibility**: files uploaded before CDC (legacy whole-file blobs in `storage.blobs`) are served transparently. When no manifest row exists for a hash, the service falls back to direct blob reads.
-
-## Architecture
-
-```
-┌─────────────────┐ ┌─────────────────────┐ ┌───────────────┐
-│ storage.files │────▶│ chunk_manifests │────▶│ storage.blobs │──▶ Blob Store
-│ (references) │ │ (file→[chunk_hashes])│ │ (chunks) │ (Local/S3/Azure)
-└─────────────────┘ └─────────────────────┘ └───────────────┘
-```
-
-### Database Tables
-
-| Table | Schema | Purpose |
-|---|---|---|
-| `storage.chunk_manifests` | `storage` | Maps file_hash → ordered chunk_hashes[] + chunk_sizes[] + ref_count |
-| `storage.blobs` | `storage` | Per-chunk metadata: hash (PK), size, ref_count, content_type |
-
-Defined in `migrations/20260414000000_chunk_manifests.sql`. Blobs table is part of the initial schema.
-
-### Layer Placement
-
-| Layer | Component | File |
-|---|---|---|
-| Application Port | **DedupPort** trait + DTOs | `src/application/ports/dedup_ports.rs` |
-| Application Port | **BlobStorageBackend** trait | `src/application/ports/blob_storage_ports.rs` |
-| Infrastructure | **DedupService** implementation | `src/infrastructure/services/dedup_service.rs` |
-| Infrastructure | Blob backends (Local, S3, Azure, Retry, Encrypted, Cached, Migration) | `src/infrastructure/services/*_blob_backend.rs` |
-| Interfaces | **DedupHandler** REST endpoints | `src/interfaces/api/handlers/dedup_handler.rs` |
-| Integration | **FileBlobWriteRepository** (dedup on upload) | `src/infrastructure/repositories/pg/file_blob_write_repository.rs` |
-| Integration | **FileBlobReadRepository** (dedup reads) | `src/infrastructure/repositories/pg/file_blob_read_repository.rs` |
-
-## Constants
-
-| Constant | Value | Description |
-|---|---|---|
-| `CDC_MIN_CHUNK` | 64 KB (`65_536`) | Minimum CDC chunk size |
-| `CDC_AVG_CHUNK` | 256 KB (`262_144`) | Average / target CDC chunk size |
-| `CDC_MAX_CHUNK` | 1 MB (`1_048_576`) | Maximum CDC chunk size |
-| `CHUNK_UPLOAD_CONCURRENCY` | 8 | Maximum parallel chunk uploads to blob backend |
-
-Hardcoded in `dedup_service.rs`.
-
-## Write Path: `store_from_file`
-
-The core write operation follows a **write-first strategy** that never holds a PG connection during disk I/O:
-
-```
-store_from_file(source_path, content_type, pre_computed_hash)
- │
- ├─ Fast path: pre_computed_hash provided?
- │ └─ try_dedup_hit() → check manifest + legacy blob
- │ └─ Hit? → bump ref_count, delete source, return ExistingBlob
- │
- ├─ CDC analysis (single mmap pass, spawn_blocking):
- │ ├─ Memory-map the file (memmap2)
- │ ├─ FastCDC 2020 boundary detection → ChunkMeta[]
- │ └─ BLAKE3 whole-file hash (concurrent with chunking)
- │
- ├─ Second dedup check with computed hash (if no pre_computed_hash)
- │
- ├─ store_chunks() — 3-phase pipeline:
- │ │
- │ ├─ Phase 0: Batch-check existing chunks (single PG query)
- │ │ SELECT hash FROM storage.blobs WHERE hash = ANY($1)
- │ │ → HashSet of already-stored chunk hashes
- │ │
- │ ├─ Phase 1: Selective disk read (sequential, one pass)
- │ │ For each chunk:
- │ │ existing? → skip read (None)
- │ │ new? → seek + read_exact → Some(Bytes)
- │ │
- │ └─ Phase 2: Parallel operations (buffer_unordered × 8)
- │ new chunk: put_blob_from_bytes + INSERT ON CONFLICT
- │ existing chunk: UPDATE ref_count + 1 (no disk I/O)
- │
- ├─ INSERT manifest into storage.chunk_manifests
- │ (file_hash, chunk_hashes[], chunk_sizes[], total_size, chunk_count)
- │
- └─ Delete source file, return NewBlob { hash, size }
-```
-
-### Dedup Skip Optimization
-
-The **biggest I/O saving** for versioned files. Before reading any chunk from disk or uploading it to the blob backend, `store_chunks` batch-queries PG to discover which chunk hashes already exist:
-
-```sql
-SELECT hash FROM storage.blobs WHERE hash = ANY($1)
-```
-
-This single round-trip returns all known chunks. For each existing chunk, the service skips:
-- `seek()` + `read_exact()` from the source file (no disk I/O)
-- `put_blob_from_bytes()` to the backend (no network I/O for S3/Azure)
-
-Only a lightweight `UPDATE ref_count + 1` is executed in PG (~0.1 ms per chunk).
-
-**Impact**: for a 100 MB versioned file where 95% of chunks are unchanged, only ~5 MB is read from disk and uploaded. The remaining 95% costs only PG ref-count bumps.
-
-### Parallel Chunk Storage
-
-Phase 2 of `store_chunks` uses `futures::stream::buffer_unordered(8)` to execute up to 8 concurrent chunk operations. This is a major win for S3/Azure backends where each PUT has 50-200 ms of network latency.
-
-Chunk order in the returned `(chunk_hashes, chunk_sizes)` is preserved by deriving both from the original `ChunkMeta` slice (CDC order), not from the unordered parallel results.
-
-### Full-File Dedup Hit (Fast Path)
-
-When a file with the exact same BLAKE3 hash already has a manifest, `try_dedup_hit` returns immediately:
-- Bumps `chunk_manifests.ref_count`
-- Deletes the source file
-- Returns `ExistingBlob` — **zero chunk I/O**
-
-Also checks legacy whole-file blobs in `storage.blobs` for backward compatibility.
-
-## Read Path
-
-### Streaming Read (`read_blob_stream`)
-
-CDC-aware with legacy fallback:
-
-1. Query `chunk_manifests` for `chunk_hashes[]`
-2. If found: stream chunks in order via `backend.get_blob_stream(chunk_hash)`, concatenated into a single byte stream with `buffered(1) + try_flatten`
-3. If not found: fall back to `backend.get_blob_stream(hash)` for legacy blobs
-
-### Range Read (`read_blob_range_stream`)
-
-For HTTP Range requests (and WOPI/WebDAV partial reads):
-
-1. Query manifest for `chunk_hashes[]`, `chunk_sizes[]`, `total_size`
-2. Calculate which chunks overlap `[start, end)` using cumulative offsets
-3. For each overlapping chunk, compute the sub-range within that chunk
-4. Stream only the relevant chunk portions via `backend.get_blob_range_stream()`
-
-### Blob Size (`blob_size`)
-
-Returns `total_size` from the manifest (O(1) PG lookup). Falls back to `backend.blob_size()` for legacy blobs. Used by HEAD requests for Content-Length.
-
-## Reference Counting
-
-### Adding References (`add_reference`)
-
-Manifest-aware with legacy fallback:
-1. Try `UPDATE chunk_manifests SET ref_count = ref_count + 1 WHERE file_hash = $1`
-2. If no rows affected, try `UPDATE storage.blobs SET ref_count + 1 WHERE hash = $1`
-3. If neither exists, return NotFound error
-
-### Removing References (`remove_reference`)
-
-**CDC manifest path** (transactional):
-1. Check `chunk_manifests` for the file hash
-2. If `ref_count > 1`: decrement manifest ref_count → commit
-3. If `ref_count == 1` (last reference):
- - `SELECT ... FOR UPDATE` to lock the manifest row
- - `DELETE FROM chunk_manifests`
- - `UPDATE storage.blobs SET ref_count = ref_count - 1 WHERE hash = ANY(chunk_hashes)`
- - `DELETE FROM storage.blobs WHERE hash = ANY(chunk_hashes) AND ref_count <= 0 RETURNING hash`
- - Commit TX
- - Delete orphaned chunk blob files from backend (after commit)
-
-**Legacy blob path** (transactional):
-1. `SELECT ref_count, size FROM storage.blobs WHERE hash = $1 FOR UPDATE`
-2. If `ref_count == 1`: `DELETE FROM storage.blobs` + delete blob file
-3. If `ref_count > 1`: `UPDATE SET ref_count = ref_count - 1`
-
-## Port: DedupPort Trait
-
-Defined in `src/application/ports/dedup_ports.rs`:
-
-```rust
-pub trait DedupPort: Send + Sync + 'static {
- /// Store content with CDC deduplication (from file).
- async fn store_from_file(
- &self,
- source_path: &Path,
- content_type: Option,
- pre_computed_hash: Option,
- ) -> Result;
-
- /// Check if a blob exists by hash (manifest or legacy).
- async fn blob_exists(&self, hash: &str) -> bool;
-
- /// Get metadata for a blob.
- async fn get_blob_metadata(&self, hash: &str) -> Option;
-
- /// Stream blob content — CDC-aware with legacy fallback.
- async fn read_blob_stream(&self, hash: &str)
- -> Result> + Send>>, DomainError>;
-
- /// Stream a byte range — CDC-aware with legacy fallback.
- async fn read_blob_range_stream(&self, hash: &str, start: u64, end: Option)
- -> Result> + Send>>, DomainError>;
-
- /// Get blob size without reading content.
- async fn blob_size(&self, hash: &str) -> Result;
-
- /// Increment reference count (manifest-aware).
- async fn add_reference(&self, hash: &str) -> Result<(), DomainError>;
-
- /// Decrement reference count. Returns true if blob was deleted.
- async fn remove_reference(&self, hash: &str) -> Result;
-
- /// Calculate BLAKE3 hash of a file (mmap + rayon).
- async fn hash_file(&self, path: &Path) -> Result;
-
- /// Get local filesystem path for a blob hash.
- fn blob_path(&self, hash: &str) -> PathBuf;
-
- /// Get deduplication statistics (computed from PG).
- async fn get_stats(&self) -> DedupStatsDto;
-
- /// Flush index to persistent storage (no-op for PG backend).
- async fn flush(&self) -> Result<(), DomainError>;
-
- /// Verify integrity of all stored blobs and manifests.
- async fn verify_integrity(&self) -> Result, DomainError>;
-}
-```
-
-### Port DTOs
-
-```rust
-/// Result of a dedup store operation.
-pub enum DedupResultDto {
- NewBlob { hash: String, size: u64 },
- ExistingBlob { hash: String, size: u64, saved_bytes: u64 },
-}
-// Methods: hash(), size(), was_deduplicated()
-
-/// Metadata for a stored blob.
-pub struct BlobMetadataDto {
- pub hash: String, // BLAKE3 hex string
- pub size: u64,
- pub ref_count: u32,
- pub content_type: Option,
-}
-
-/// Aggregate dedup statistics (computed from PG).
-pub struct DedupStatsDto {
- pub total_blobs: u64,
- pub total_bytes_stored: u64,
- pub total_bytes_referenced: u64,
- pub bytes_saved: u64,
- pub dedup_hits: u64,
- pub dedup_ratio: f64,
-}
-```
-
-## Infrastructure: DedupService
-
-Implemented in `src/infrastructure/services/dedup_service.rs`.
-
-### Struct
-
-```rust
-pub struct DedupService {
- backend: Arc, // Pluggable blob storage (Local/S3/Azure/...)
- pool: Arc, // Primary pool (request-path operations)
- maintenance_pool: Arc, // Isolated pool (verify_integrity, GC)
-}
-```
-
-### Key Methods
-
-| Method | Description |
-|---|---|
-| `new(backend, pool, maintenance_pool)` | Construct — wires pluggable backend + dual PG pools |
-| `initialize()` | Initialize backend + log blob/manifest counts from PG |
-| `cdc_hash_and_chunk_file(path)` | Single mmap pass: BLAKE3 whole-file hash + FastCDC chunk boundaries + per-chunk BLAKE3 |
-| `cdc_chunk_file(path)` | CDC without whole-file hash (when hash is pre-computed) |
-| `hash_file(path)` | BLAKE3 hash via mmap + rayon parallelism |
-| `store_from_file(path, ct, hash)` | CDC → store_chunks → manifest INSERT (main write path) |
-| `try_dedup_hit(hash, path)` | Check manifest/legacy for full-file dedup hit |
-| `store_chunks(path, chunks)` | 3-phase: batch-check → selective read → parallel upload |
-| `blob_exists(hash)` | Check manifest + legacy blob existence |
-| `user_owns_blob_reference(hash, user_id)` | Authorization: check file ownership |
-| `get_blob_metadata(hash)` | Manifest-aware metadata with legacy fallback |
-| `add_reference(hash)` | Manifest-aware ref_count increment |
-| `remove_reference(hash)` | Manifest-aware ref_count decrement + cascade cleanup |
-| `read_blob_stream(hash)` | CDC chunk-streaming with legacy fallback |
-| `read_blob_range_stream(hash, start, end)` | CDC range-streaming with legacy fallback |
-| `blob_size(hash)` | O(1) from manifest, fallback to backend |
-| `get_stats()` | Compute stats from PG (blobs + manifests) |
-| `verify_integrity()` | Verify manifests (counts, sizes) + blobs (existence, size, re-hash) |
-| `garbage_collect()` | Batch-delete orphaned manifests/blobs (uses maintenance pool) |
-
-### Key Behaviors
-
-- **CDC analysis in `spawn_blocking`**: mmap + FastCDC runs off the async runtime to avoid blocking the event loop
-- **Dual PG pools**: request-path operations use the primary pool; `verify_integrity` and `garbage_collect` use the maintenance pool to prevent starvation
-- **Pluggable blob backend**: all chunk I/O goes through `Arc` — works with local FS, S3, Azure, or any composed backend (retry, encryption, caching)
-- **Atomic chunk storage**: `put_blob_from_bytes` is idempotent; `INSERT ON CONFLICT` handles concurrent uploads of the same chunk
-- **Delete-after-commit**: blob files are deleted from the backend only after the PG transaction commits, preventing orphaned PG rows
-- **Flush is no-op**: PG handles durability via WAL/commit — no explicit index persistence needed
-
-## REST API Endpoints
-
-All routes under `/api/dedup`, authentication required.
-
-| Method | Path | Handler | Description |
-|---|---|---|---|
-| `GET` | `/api/dedup/check/{hash}` | `DedupHandler::check_hash` | Check if a blob exists by BLAKE3 hash |
-| `POST` | `/api/dedup/upload` | `DedupHandler::upload_with_dedup` | Multipart upload with automatic dedup |
-| `GET` | `/api/dedup/stats` | `DedupHandler::get_stats` | Get deduplication statistics |
-| `GET` | `/api/dedup/blob/{hash}` | `DedupHandler::get_blob` | Retrieve raw blob content by hash |
-| `DELETE` | `/api/dedup/blob/{hash}` | `DedupHandler::remove_reference` | Decrement ref-count (deletes blob if 0) |
-| `POST` | `/api/dedup/recalculate` | `DedupHandler::recalculate_stats` | Run integrity verification + refresh stats |
-
-### API Response Types
-
-**Hash Check** (`GET /api/dedup/check/{hash}`):
-```json
-{
- "exists": true,
- "hash": "a1b2c3d4...",
- "existing_size": 1048576,
- "ref_count": 3
-}
-```
-
-**Dedup Upload** (`POST /api/dedup/upload`):
-```json
-{
- "is_new": false,
- "hash": "a1b2c3d4...",
- "size": 1048576,
- "bytes_saved": 1048576,
- "ref_count": 2
-}
-```
-
-**Stats** (`GET /api/dedup/stats`):
-```json
-{
- "unique_blobs": 150,
- "total_references": 300,
- "bytes_saved": 524288000,
- "total_logical_bytes": 1073741824,
- "total_physical_bytes": 549453824,
- "dedup_ratio": 2.0,
- "savings_percentage": 48.8
-}
-```
-
-## DI Wiring
-
-In `src/common/di.rs`:
-
-```rust
-// Blob backend is assembled from layered backends:
-// LocalBlobBackend / S3BlobBackend / AzureBlobBackend
-// → RetryBlobBackend → EncryptedBlobBackend → CachedBlobBackend
-let blob_backend: Arc = /* ... */;
-
-// DedupService receives the composed blob backend + dual PG pools
-let dedup_service = Arc::new(DedupService::new(
- blob_backend,
- db_pool.clone(),
- maintenance_pool.clone(),
-));
-dedup_service.initialize().await?;
-
-// Stored in CoreServices as:
-pub struct CoreServices {
- pub dedup_service: Arc,
- // ...
-}
-
-// Injected into blob repositories:
-FileBlobReadRepository::new(pool, core.dedup_service.clone(), folder_repo)
-FileBlobWriteRepository::new(pool, core.dedup_service.clone(), folder_repo)
-```
-
-## Maintenance
-
-### Garbage Collection (`garbage_collect`)
-
-Two-phase batch deletion using the maintenance pool:
-
-1. **Phase 1 — Orphaned manifests**: `DELETE FROM chunk_manifests WHERE ref_count <= 0` (batches of 500). For each deleted manifest, `UPDATE storage.blobs SET ref_count = ref_count - 1` for its chunks.
-2. **Phase 2 — Orphaned blobs**: `DELETE FROM storage.blobs WHERE ref_count <= 0` (batches of 500). Deletes blob files from backend + thumbnail cleanup (best-effort).
-
-Uses `tokio::task::yield_now()` between batches to avoid starving other tasks.
-
-### Integrity Verification (`verify_integrity`)
-
-Phase 1 — Verify CDC manifests:
-- `chunk_hashes.len() == chunk_sizes.len()`
-- `SUM(chunk_sizes) == total_size`
-- Every referenced chunk exists in the blob backend with correct size
-
-Phase 2 — Verify blobs (chunks + legacy):
-- Blob file exists in backend
-- Actual size matches PG record
-- (Local backends only) Re-hash file content to verify BLAKE3 integrity
-- Processes 16 blobs concurrently via `buffer_unordered`
-
-## Tests
-
-Located at the bottom of `src/infrastructure/services/dedup_service.rs` (12 tests):
-
-| Test | Description |
-|---|---|
-| `test_cdc_deterministic_same_content` | Same content → same file hash + same chunk hashes/offsets/lengths |
-| `test_cdc_empty_file` | Empty file → zero chunks, correct BLAKE3 empty hash |
-| `test_cdc_small_file_single_chunk` | File below min chunk → single chunk covering entire file |
-| `test_cdc_chunk_sizes_within_bounds` | All non-last chunks are within [64 KB, 1 MB] |
-| `test_cdc_file_hash_matches_hash_file` | CDC whole-file hash matches standalone `hash_file()` |
-| `test_cdc_chunk_hashes_are_correct` | Each chunk hash == BLAKE3 of that chunk's data |
-| `test_cdc_reassembly_matches_original` | Concatenating chunks reproduces original file |
-| `test_cdc_chunks_are_contiguous` | Chunks cover entire file with no gaps or overlaps |
-| `test_cdc_similar_files_share_chunks` | Editing last 64 KB of 2 MB file → most chunks shared |
-| `test_cdc_chunk_file_matches_full` | `cdc_chunk_file` produces same chunks as `cdc_hash_and_chunk_file` |
-| `test_cdc_large_file_chunk_count` | 8 MB file produces 8-128 chunks (avg ~256 KB) |
-| `test_cdc_insert_at_beginning_preserves_later_chunks` | 128 KB prefix insert → CDC resynchronizes, later chunks shared |
-
-## Performance Characteristics
-
-| Scenario | Behavior |
-|---|---|
-| **First upload of new file** | Single mmap pass (CDC + hash) → parallel chunk upload → manifest INSERT |
-| **Re-upload of identical file** | `try_dedup_hit` → manifest ref_count bump → zero chunk I/O |
-| **Upload of edited file (5% changed)** | CDC → batch-check finds 95% existing → reads only 5% → uploads 5% → ref-bumps 95% |
-| **Range read (1 MB from 1 GB file)** | Manifest lookup → identify overlapping chunks → stream only those portions |
-| **Delete last reference** | TX: delete manifest → batch-decrement chunks → delete zero-ref chunks → commit → delete blob files |
-| **Garbage collection** | Maintenance pool, batches of 500, yields between batches |
-
-## Client Usage Example
-
-```bash
-# 1. Check if file already exists by hash
-HASH=$(b3sum myfile.txt | cut -d' ' -f1)
-curl -H "Authorization: Bearer $TOKEN" \
- "https://oxicloud.example.com/api/dedup/check/$HASH"
-
-# 2. Upload with dedup (if not exists)
-curl -X POST -H "Authorization: Bearer $TOKEN" \
- -F "file=@myfile.txt" \
- "https://oxicloud.example.com/api/dedup/upload"
-
-# 3. Get dedup statistics
-curl -H "Authorization: Bearer $TOKEN" \
- "https://oxicloud.example.com/api/dedup/stats"
-
-# 4. Retrieve blob content
-curl -H "Authorization: Bearer $TOKEN" \
- "https://oxicloud.example.com/api/dedup/blob/$HASH" -o output.bin
-
-# 5. Recalculate stats with integrity check
-curl -X POST -H "Authorization: Bearer $TOKEN" \
- "https://oxicloud.example.com/api/dedup/recalculate"
-```
diff --git a/doc/deployment.md b/doc/deployment.md
deleted file mode 100644
index 1b41bea7..00000000
--- a/doc/deployment.md
+++ /dev/null
@@ -1,247 +0,0 @@
-# 02 - Deployment
-
-OxiCloud is deployed as a containerized application with PostgreSQL.
-
----
-
-## Docker Setup
-
-### Quick Start
-
-1. **Copy the example environment file and customize it:**
- ```bash
- cp example.env .env
- # Edit .env with your settings
- ```
-
-2. **Start the services:**
- ```bash
- docker compose up -d
- ```
-
-3. **Access OxiCloud:**
- Open `http://localhost:8086` in your browser.
-
-### Docker Compose
-
-```yaml
-# docker-compose.yml
-services:
- postgres:
- image: postgres:17.4-alpine
- environment:
- POSTGRES_DB: oxicloud
- POSTGRES_USER: postgres
- POSTGRES_PASSWORD: postgres
- volumes:
- - pg_data:/var/lib/postgresql/
- - ./db/schema.sql:/docker-entrypoint-initdb.d/schema.sql
- healthcheck:
- test: ["CMD-SHELL", "pg_isready -U postgres"]
- interval: 5s
- timeout: 5s
- retries: 5
-
- oxicloud:
- image: diocrafts/oxicloud:latest
- ports:
- - "8086:8086"
- env_file:
- - .env
- volumes:
- - storage_data:/app/storage
- depends_on:
- postgres:
- condition: service_healthy
-
-volumes:
- pg_data:
- storage_data:
-```
-
-### Dockerfile
-
-3-stage Alpine-based build:
-1. **Cacher** -- pre-builds dependency layer
-2. **Builder** -- compiles OxiCloud (`rust:1.93.0-alpine3.23`)
-3. **Runtime** -- minimal Alpine image (`alpine:3.23.3`) with `libgcc`, `ca-certificates`, `libpq`, `tzdata`, `su-exec`
-
-Non-root user: `oxicloud` (UID/GID 1001). Exposed port: `8086`. Entrypoint: `entrypoint.sh` (chown storage + drop privileges via `su-exec`).
-
----
-
-## Environment Variables
-
-### Server
-
-| Variable | Default | Description |
-|---|---|---|
-| `OXICLOUD_STORAGE_PATH` | `./storage` | Root storage directory |
-| `OXICLOUD_STATIC_PATH` | `./static` | Static files directory |
-| `OXICLOUD_SERVER_PORT` | `8086` | Server port |
-| `OXICLOUD_SERVER_HOST` | `127.0.0.1` | Server bind address |
-| `OXICLOUD_BASE_URL` | (auto-detected) | Public base URL for share links. If not set, uses `http://{host}:{port}` |
-
-### Database
-
-| Variable | Default | Description |
-|---|---|---|
-| `OXICLOUD_DB_CONNECTION_STRING` | `postgres://postgres:postgres@localhost:5432/oxicloud` | PostgreSQL connection string |
-| `OXICLOUD_DB_MAX_CONNECTIONS` | `20` | Max pool connections |
-| `OXICLOUD_DB_MIN_CONNECTIONS` | `5` | Min pool connections |
-
-### Authentication
-
-| Variable | Default | Description |
-|---|---|---|
-| `OXICLOUD_JWT_SECRET` | (auto-generated) | JWT signing secret. If empty, a random 32-byte hex secret is generated per session |
-| `OXICLOUD_ACCESS_TOKEN_EXPIRY_SECS` | `3600` (1h) | Access token lifetime |
-| `OXICLOUD_REFRESH_TOKEN_EXPIRY_SECS` | `2592000` (30d) | Refresh token lifetime |
-
-### Feature Flags
-
-| Variable | Default | Description |
-|---|---|---|
-| `OXICLOUD_ENABLE_AUTH` | `true` | Enable authentication system |
-| `OXICLOUD_ENABLE_USER_STORAGE_QUOTAS` | `false` | Enable per-user storage quotas |
-| `OXICLOUD_ENABLE_FILE_SHARING` | `true` | Enable file/folder sharing |
-| `OXICLOUD_ENABLE_TRASH` | `true` | Enable trash/recycle bin |
-| `OXICLOUD_ENABLE_SEARCH` | `true` | Enable search functionality |
-
-### OIDC / SSO
-
-| Variable | Default | Description |
-|---|---|---|
-| `OXICLOUD_OIDC_ENABLED` | `false` | Enable OIDC authentication |
-| `OXICLOUD_OIDC_ISSUER_URL` | (empty) | OIDC provider issuer URL |
-| `OXICLOUD_OIDC_CLIENT_ID` | (empty) | OIDC client ID |
-| `OXICLOUD_OIDC_CLIENT_SECRET` | (empty) | OIDC client secret |
-| `OXICLOUD_OIDC_REDIRECT_URI` | `http://localhost:8086/api/auth/oidc/callback` | Callback URL |
-| `OXICLOUD_OIDC_SCOPES` | `openid profile email` | Requested OIDC scopes |
-| `OXICLOUD_OIDC_FRONTEND_URL` | `http://localhost:8086` | Frontend URL for redirects |
-| `OXICLOUD_OIDC_AUTO_PROVISION` | `true` | Auto-create users on first login |
-| `OXICLOUD_OIDC_ADMIN_GROUPS` | (empty) | OIDC groups that grant admin role |
-| `OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN` | `false` | Disable password login when OIDC is active |
-| `OXICLOUD_OIDC_PROVIDER_NAME` | `SSO` | Display name for the OIDC provider |
-
-### OIDC Validation
-
-If **OXICLOUD_OIDC_ENABLED** is `true` but **issuer_url**, **client_id**, or **client_secret** are empty, OIDC is automatically disabled with an error log.
-
-### WOPI (Office Document Editing)
-
-| Variable | Default | Description |
-|---|---|---|
-| `OXICLOUD_WOPI_ENABLED` | `false` | Enable WOPI integration for office document editing |
-| `OXICLOUD_WOPI_DISCOVERY_URL` | (empty) | WOPI client discovery URL (e.g., Collabora, OnlyOffice) |
-| `OXICLOUD_WOPI_SECRET` | (falls back to JWT secret) | Secret key for signing WOPI access tokens |
-| `OXICLOUD_WOPI_TOKEN_TTL_SECS` | `86400` (24h) | WOPI access token lifetime |
-| `OXICLOUD_WOPI_LOCK_TTL_SECS` | `1800` (30m) | WOPI lock expiration time |
-
----
-
-## Internal Configuration (Not Environment-Configurable)
-
-Hardcoded defaults in `src/common/config.rs`:
-
-### Cache
-
-| Parameter | Default |
-|---|---|
-| File cache TTL | 60,000 ms (1 min) |
-| Directory cache TTL | 120,000 ms (2 min) |
-| Max cache entries | 10,000 |
-
-### Timeouts
-
-| Parameter | Default |
-|---|---|
-| File operation | 10,000 ms |
-| Directory operation | 30,000 ms |
-| Lock acquisition | 5,000 ms |
-| Network operation | 15,000 ms |
-
-### Resources
-
-| Parameter | Default |
-|---|---|
-| Large file threshold | 100 MB |
-| Large directory threshold | 1,000 entries |
-| Streaming chunk size | 1 MB |
-| Max in-memory file size | 50 MB |
-
-### Concurrency
-
-| Parameter | Default |
-|---|---|
-| Max concurrent files | 10 |
-| Max concurrent dirs | 5 |
-| Max concurrent I/O | 20 |
-| Max parallel chunks | 8 |
-| Min size for parallel chunks | 200 MB |
-| Parallel chunk size | 8 MB |
-
-### Storage
-
-| Parameter | Default |
-|---|---|
-| Trash retention | 30 days |
-
-### Auth Hashing (Argon2id)
-
-| Parameter | Default |
-|---|---|
-| Memory cost | 65,536 KB (64 MB) |
-| Time cost | 3 iterations |
-
----
-
-## Feature Dependency Matrix
-
-| Feature | Requires DB | Requires Auth | Feature Flag |
-|---|---|---|---|
-| File storage | Yes | No | Always on |
-| Authentication | Yes | -- | `OXICLOUD_ENABLE_AUTH` |
-| OIDC / SSO | Yes | Yes | `OXICLOUD_OIDC_ENABLED` |
-| File sharing | Yes | Yes | `OXICLOUD_ENABLE_FILE_SHARING` |
-| Trash | Yes | No | `OXICLOUD_ENABLE_TRASH` |
-| Search | Yes | No | `OXICLOUD_ENABLE_SEARCH` |
-| Favorites | Yes | Yes | Always on (when DB available) |
-| Recent items | Yes | Yes | Always on (when DB available) |
-| Storage quotas | Yes | Yes | `OXICLOUD_ENABLE_USER_STORAGE_QUOTAS` |
-| Admin panel | Yes | Yes | Always on (when auth enabled) |
-| WebDAV | Yes | Optional | Always on |
-| CalDAV | Yes | Yes | Always on (when DB available) |
-| CardDAV | Yes | Yes | Always on (when DB available) |
-| Deduplication | No | No | Always on |
-| Thumbnails | No | No | Always on |
-| Chunked uploads | No | No | Always on |
-
-# Kubernetes Setup
-
-## 01 - Dependencies
-- K8S Cluster
-- Default StorageClass
-- Ingress Controller
-- Helm
-
-## 02 - Deployment
-Change the `charts/oxicloud/values.yaml` to match your setup.
-
-To install the Chart run:
-```bash
-helm upgrade --install oxicloud charts/oxicloud -f charts/oxicloud/values.yaml
-```
-
-## 03 - Verification
-
-To verify your deployment run:
-```bash
-kubectl get pods -n oxicloud
-kubectl logs statefulset/oxicloud -n oxicloud
-```
-
-If you have collabora enabled you want to check the logs:
-```bash
-kubectl logs statefulset/oxicloud -n oxicloud | grep "WOPI discovery loaded"
-```
\ No newline at end of file
diff --git a/doc/favorites-and-recent.md b/doc/favorites-and-recent.md
deleted file mode 100644
index 7180c0dc..00000000
--- a/doc/favorites-and-recent.md
+++ /dev/null
@@ -1,171 +0,0 @@
-# 13 - Favorites and Recent Items
-
-Two per-user item tracking features:
-
-- **Favorites** -- users mark files and folders for quick access.
-- **Recent Items** -- automatically tracks recently accessed files and folders.
-
-Both require PostgreSQL and are only available when a database connection is configured.
-
----
-
-## Favorites
-
-### Architecture
-
-| Layer | Component | File |
-|---|---|---|
-| Application Port | **FavoritesUseCase**, **FavoritesRepositoryPort** | `src/application/ports/favorites_ports.rs` |
-| Application Service | **FavoritesService** | `src/application/services/favorites_service.rs` |
-| Application DTO | **FavoriteItemDto** | `src/application/dtos/favorites_dto.rs` |
-| Infrastructure | **FavoritesPgRepository** | `src/infrastructure/repositories/pg/favorites_pg_repository.rs` |
-| Interfaces | `favorites_handler` (free functions) | `src/interfaces/api/handlers/favorites_handler.rs` |
-
-### DTO
-
-```rust
-pub struct FavoriteItemDto {
- pub id: String,
- pub user_id: String,
- pub item_id: String,
- pub item_type: String, // "file" | "folder"
- pub created_at: DateTime,
-}
-```
-
-### REST API
-
-All routes under `/api/favorites`, require authentication. User ID comes from the JWT token.
-
-| Method | Path | Handler | Description |
-|---|---|---|---|
-| `GET` | `/api/favorites/` | `get_favorites` | List all favorites for current user |
-| `POST` | `/api/favorites/{item_type}/{item_id}` | `add_favorite` | Add a file or folder to favorites |
-| `DELETE` | `/api/favorites/{item_type}/{item_id}` | `remove_favorite` | Remove from favorites |
-
-- `item_type` must be `"file"` or `"folder"` (validated by service)
-- Adding a duplicate is idempotent (`ON CONFLICT DO NOTHING`)
-- Results ordered by `created_at DESC`
-
-### Database Schema
-
-```sql
-CREATE TABLE IF NOT EXISTS auth.user_favorites (
- id SERIAL PRIMARY KEY,
- user_id VARCHAR(36) NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
- item_id TEXT NOT NULL,
- item_type TEXT NOT NULL,
- created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
- UNIQUE(user_id, item_id, item_type)
-);
-```
-
-Indexes: `user_id`, `item_id`, `item_type`, `created_at`, composite `(user_id, item_type)`.
-
-### Example
-
-```bash
-# Add file to favorites
-curl -X POST -H "Authorization: Bearer $TOKEN" \
- "https://oxicloud.example.com/api/favorites/file/abc-123"
-
-# List favorites
-curl -H "Authorization: Bearer $TOKEN" \
- "https://oxicloud.example.com/api/favorites/"
-
-# Remove from favorites
-curl -X DELETE -H "Authorization: Bearer $TOKEN" \
- "https://oxicloud.example.com/api/favorites/folder/def-456"
-```
-
----
-
-## Recent Items
-
-### Architecture
-
-| Layer | Component | File |
-|---|---|---|
-| Application Port | **RecentItemsUseCase**, **RecentItemsRepositoryPort** | `src/application/ports/recent_ports.rs` |
-| Application Service | **RecentService** | `src/application/services/recent_service.rs` |
-| Application DTO | **RecentItemDto** | `src/application/dtos/recent_dto.rs` |
-| Infrastructure | **RecentItemsPgRepository** | `src/infrastructure/repositories/pg/recent_items_pg_repository.rs` |
-| Interfaces | `recent_handler` (free functions) | `src/interfaces/api/handlers/recent_handler.rs` |
-
-### DTO
-
-```rust
-pub struct RecentItemDto {
- pub id: String,
- pub user_id: String,
- pub item_id: String,
- pub item_type: String, // "file" | "folder"
- pub accessed_at: DateTime,
-}
-```
-
-### REST API
-
-All routes under `/api/recent`, require authentication.
-
-| Method | Path | Handler | Description |
-|---|---|---|---|
-| `GET` | `/api/recent/` | `get_recent_items` | List recent items (optional `?limit=N`) |
-| `POST` | `/api/recent/{item_type}/{item_id}` | `record_item_access` | Record an access (upsert) |
-| `DELETE` | `/api/recent/{item_type}/{item_id}` | `remove_from_recent` | Remove specific item |
-| `DELETE` | `/api/recent/clear` | `clear_recent_items` | Clear all recent items |
-
-### Behavior
-
-- **Max items per user**: 50 (configured in DI, clamped to 1-100)
-- **Upsert**: re-accessing an item updates its `accessed_at` timestamp
-- **Auto-prune**: after recording access, old items beyond the limit are automatically pruned
-- **Ordering**: results ordered by `accessed_at DESC`
-- **Limit parameter**: `?limit=N` caps results (defaults to and cannot exceed **max_recent_items**)
-
-### Database Schema
-
-```sql
-CREATE TABLE IF NOT EXISTS auth.user_recent_files (
- id SERIAL PRIMARY KEY,
- user_id VARCHAR(36) NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
- item_id TEXT NOT NULL,
- item_type TEXT NOT NULL,
- accessed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
- UNIQUE(user_id, item_id, item_type)
-);
-```
-
-Indexes: `user_id`, `item_id`, `item_type`, `accessed_at`, composite `(user_id, accessed_at DESC)`.
-
-### Example
-
-```bash
-# Record file access
-curl -X POST -H "Authorization: Bearer $TOKEN" \
- "https://oxicloud.example.com/api/recent/file/abc-123"
-
-# Get recent items (last 10)
-curl -H "Authorization: Bearer $TOKEN" \
- "https://oxicloud.example.com/api/recent/?limit=10"
-
-# Clear history
-curl -X DELETE -H "Authorization: Bearer $TOKEN" \
- "https://oxicloud.example.com/api/recent/clear"
-```
-
-## DI Wiring
-
-Both services require PostgreSQL:
-
-```rust
-// Favorites
-let repo = Arc::new(FavoritesPgRepository::new(db_pool.clone()));
-let favorites_service = Arc::new(FavoritesService::new(repo));
-
-// Recent
-let repo = Arc::new(RecentItemsPgRepository::new(db_pool.clone()));
-let recent_service = Arc::new(RecentService::new(repo, 50)); // max 50 items
-```
-
-Stored as `Option>` in **AppState** -- only available when DB is connected.
diff --git a/doc/file-system-safety.md b/doc/file-system-safety.md
deleted file mode 100644
index d78e663f..00000000
--- a/doc/file-system-safety.md
+++ /dev/null
@@ -1,125 +0,0 @@
-# 03 - Storage Safety
-
-OxiCloud ensures data integrity and durability through a combination of PostgreSQL transactional guarantees and atomic blob writes. The goal: writes either complete fully or not at all, data reaches persistent storage, and the system recovers from crashes or power loss.
-
----
-
-## Storage Model
-
-OxiCloud uses a **100% blob storage model**:
-
-- **Metadata** (file names, folder hierarchy, sizes, MIME types, trash status) lives in **PostgreSQL** — protected by ACID transactions.
-- **File content** is stored as content-addressed blobs via **DedupService** at `.blobs/{prefix}/{hash}.blob` — protected by atomic writes and fsync.
-
----
-
-## PostgreSQL Safety (Metadata)
-
-All file and folder metadata operations use PostgreSQL transactions:
-
-- **Single-row operations** (INSERT, UPDATE, DELETE) are inherently atomic.
-- **Multi-step operations** (e.g., move file: UPDATE folder_id + UPDATE path) use explicit transactions via `sqlx`.
-- **Foreign key constraints** prevent orphaned records (e.g., files referencing non-existent folders).
-- **Unique constraints** prevent duplicate names within the same parent folder.
-- **Soft-delete** for trash (`is_trashed = TRUE`) preserves data until explicit permanent deletion.
-
-The `storage.trash_items` VIEW provides a unified read interface over trashed files and folders without duplicating data.
-
----
-
-## Blob Storage Safety (Content)
-
-### DedupService Atomic Writes
-
-**File:** `src/infrastructure/services/dedup_service.rs`
-
-When storing file content, DedupService uses the following pattern:
-
-1. **Hash computation** — SHA-256 hash of content determines the blob path
-2. **Deduplication check** — if a blob with the same hash exists, only increment the reference counter (no write needed)
-3. **Atomic write** — if new content:
- - Write to a temporary file (`.blob.tmp`)
- - Call `fsync` to ensure data reaches persistent storage
- - Atomically rename temp file to final path (`.blobs/{prefix}/{hash}.blob`)
-4. **Reference counting** — track how many files reference each blob
-
-This ensures that a blob either fully exists or doesn't — no partial writes.
-
-### FileSystemUtils
-
-**File:** `src/infrastructure/services/file_system_utils.rs`
-
-Low-level utilities used internally by DedupService and other infrastructure services:
-
-```rust
-/// Atomic write: temp file → fsync → rename
-pub async fn atomic_write>(path: P, contents: &[u8]) -> Result<(), IoError>
-
-/// Directory creation with fsync
-pub async fn create_dir_with_sync>(path: P) -> Result<(), IoError>
-
-/// Rename with directory sync
-pub async fn rename_with_sync(from: P, to: Q) -> Result<(), IoError>
-
-/// Delete with directory sync
-pub async fn remove_file_with_sync>(path: P) -> Result<(), IoError>
-```
-
-### fsync Guarantees
-
-- `sync_all()` on written files ensures data and metadata reach the physical storage device
-- Directory entries are synced after create/rename/delete operations
-- Prevents data loss during crashes or power failures between OS buffer flush and disk write
-
----
-
-## Transaction Flow: File Upload
-
-```
-1. DedupService.store_bytes(content)
- → Compute SHA-256 hash
- → Check if blob exists (dedup hit → increment ref, return hash)
- → Write to .blobs/{prefix}/{hash}.blob.tmp
- → fsync + rename → .blobs/{prefix}/{hash}.blob
-
-2. FileBlobWriteRepository.save_file()
- → BEGIN TRANSACTION
- → INSERT INTO storage.files (name, folder_id, blob_hash, size, ...)
- → COMMIT
-```
-
-If step 1 fails, no metadata is written. If step 2 fails, the blob exists but is unreferenced (cleaned up by garbage collection). Data is never in an inconsistent state.
-
-## Transaction Flow: File Deletion
-
-```
-1. FileBlobWriteRepository.delete_file_permanently()
- → BEGIN TRANSACTION
- → DELETE FROM storage.files WHERE id = $1 (captures blob_hash first)
- → COMMIT
-
-2. DedupService.decrement_ref(blob_hash)
- → Decrement reference counter
- → If counter reaches 0, delete the blob file
-```
-
-If step 2 fails, an unreferenced blob may remain on disk (occupies space but is not a correctness issue). Future garbage collection can clean these up.
-
----
-
-## Benefits
-
-1. **ACID transactions** — metadata operations are atomic, consistent, isolated, and durable
-2. **Content-addressable storage** — identical content is stored once, referenced by hash
-3. **Crash resilience** — atomic blob writes + PostgreSQL WAL ensure recovery
-4. **No partial writes** — temp file + rename pattern guarantees all-or-nothing
-5. **Referential integrity** — foreign keys prevent orphaned metadata
-
----
-
-## Performance Considerations
-
-- PostgreSQL connection pooling (`sqlx::PgPool`) amortizes connection overhead
-- Dedup hash computation is CPU-bound but avoids unnecessary disk writes for duplicate content
-- Blob fsync adds latency vs. buffered writes, but ensures durability for critical user data
-- Content cache (in-memory LRU) serves repeat reads without disk or DB access
diff --git a/doc/i18n.md b/doc/i18n.md
deleted file mode 100644
index f012f00f..00000000
--- a/doc/i18n.md
+++ /dev/null
@@ -1,100 +0,0 @@
-# 16 - Internationalization
-
-JSON-based translation system. Translations are loaded from static files, cached in memory, and served via a public REST API (no auth required).
-
-## Supported Languages
-
-| Locale | Code | File |
-|---|---|---|
-| English | `en` | `static/locales/en.json` |
-| Spanish | `es` | `static/locales/es.json` |
-| French | `fr` | `static/locales/fr.json` |
-| German | `de` | `static/locales/de.json` |
-| Portuguese | `pt` | `static/locales/pt.json` |
-| Persian | `fa` | `static/locales/fa.json` |
-| Chinese | `zh` | `static/locales/zh.json` |
-| Dutch | `nl` | `static/locales/nl.json` |
-
-Default locale: **en** (English).
-
-## Architecture
-
-| Layer | Component | File |
-|---|---|---|
-| Domain Port | **I18nService** trait, **Locale** enum | `src/domain/services/i18n_service.rs` |
-| Application Service | **I18nApplicationService** | `src/application/services/i18n_application_service.rs` |
-| Application DTOs | **LocaleDto**, **TranslationRequestDto**, etc. | `src/application/dtos/i18n_dto.rs` |
-| Infrastructure | **FileSystemI18nService** | `src/infrastructure/services/file_system_i18n_service.rs` |
-| Interfaces | **I18nHandler** | `src/interfaces/api/handlers/i18n_handler.rs` |
-
-## REST API
-
-Public endpoints (no authentication), under `/api/i18n`:
-
-| Method | Path | Handler | Description |
-|---|---|---|---|
-| `GET` | `/api/i18n/locales` | `get_locales` | List available locales |
-| `GET` | `/api/i18n/translate` | `translate` | Translate a key (`?key=...&locale=...`) |
-| `GET` | `/api/i18n/locales/{locale_code}` | `get_translations_by_locale` | Get all translations for a locale |
-
-### Examples
-
-```bash
-# List available locales
-curl "https://oxicloud.example.com/api/i18n/locales"
-# [{"code":"en","name":"English"},{"code":"es","name":"Spanish"}, ...]
-
-# Translate a key
-curl "https://oxicloud.example.com/api/i18n/translate?key=app.title&locale=es"
-# {"key":"app.title","locale":"es","text":"OxiCloud"}
-
-# Get all translations for a locale
-curl "https://oxicloud.example.com/api/i18n/locales/en"
-# { "app": { "title": "OxiCloud", ... }, "nav": { ... }, ... }
-```
-
-## Translation File Format
-
-Nested JSON with dot-delimited key lookups:
-
-```json
-{
- "app": {
- "title": "OxiCloud",
- "description": "Your personal cloud storage"
- },
- "nav": {
- "files": "Files",
- "shared": "Shared",
- "recent": "Recent",
- "favorites": "Favorites",
- "trash": "Trash"
- },
- "actions": {
- "search": "Search files...",
- "new_folder": "New folder",
- "upload": "Upload",
- "download": "Download",
- "delete": "Delete"
- },
- "share": { ... },
- "user_menu": { ... }
-}
-```
-
-Key lookup: `"nav.files"` resolves to `"Files"`.
-
-## Fallback Behavior
-
-If a key is missing in the requested locale, the system falls back to English (`en`). If still not found, returns an `I18nError::KeyNotFound`.
-
-## Caching
-
-Translations are cached in-memory via `RwLock>`. Loaded lazily on first request per locale.
-
-## Frontend Integration
-
-The frontend uses `static/js/i18n.js` and `static/js/languageSelector.js` to:
-1. Detect the user's preferred language
-2. Load translations via `/api/i18n/locales/{code}`
-3. Apply translations to DOM elements
diff --git a/doc/important-delta-sync-implementation.md b/doc/important-delta-sync-implementation.md
deleted file mode 100644
index 374e0016..00000000
--- a/doc/important-delta-sync-implementation.md
+++ /dev/null
@@ -1,1152 +0,0 @@
-# 20 - Delta Sync Implementation
-
-Delta sync transfers only the modified parts of a file instead of the whole thing. Based on the rsync algorithm, it can save 90-99% bandwidth in common scenarios.
-
-**Status**: pending implementation
-**Priority**: medium
-**Estimated savings**: 10-100x less data transfer
-
-## Contents
-
-1. [Problem Statement](#problem-statement)
-2. [How It Works](#how-it-works)
-3. [Key Algorithms](#key-algorithms)
-4. [Proposed Architecture](#proposed-architecture)
-5. [Data Structures](#data-structures)
-6. [API Endpoints](#api-endpoints)
-7. [Step-by-Step Implementation](#step-by-step-implementation)
-8. [Integration with Existing System](#integration-with-existing-system)
-9. [Use Cases and Effectiveness](#use-cases-and-effectiveness)
-10. [Performance Considerations](#performance-considerations)
-11. [Testing](#testing)
-12. [Required Dependencies](#required-dependencies)
-
----
-
-## Key Benefits
-
-| Metric | Without Delta Sync | With Delta Sync |
-|---------|----------------|----------------|
-| Edit 1 line in 100MB | 100MB transferred | ~1KB transferred |
-| Sync time (slow connection) | 4+ minutes | <1 second |
-| Bandwidth consumption | 100% | 0.1-10% |
-
----
-
-## Problem Statement
-
-### Current scenario (no delta sync)
-
-```
-User has document.docx (50MB) on OxiCloud
- │
- ▼
-Downloads full file (50MB) ──────────────────────► 50MB ↓
- │
- ▼
-Edits one word
- │
- ▼
-Uploads full file again (50MB) ──────────────────► 50MB ↑
- │
- ▼
-TOTAL: 100MB transferred to change one word
-```
-
-### Target scenario (with delta sync)
-
-```
-User has document.docx (50MB) on OxiCloud
- │
- ▼
-Downloads full file (50MB) ──────────────────────► 50MB ↓ (first time)
- │
- ▼
-Edits one word
- │
- ▼
-Uploads ONLY modified blocks ───────────────────► ~50KB ↑
- │
- ▼
-TOTAL: 50.05MB (99.9% savings on upload)
-```
-
----
-
-## How It Works
-
-### Block (chunk) concept
-
-The file gets divided into fixed-size blocks (typically 4KB-64KB):
-
-```
-Original file (server):
-┌────────┬────────┬────────┬────────┬────────┐
-│ Bloque │ Bloque │ Bloque │ Bloque │ Bloque │
-│ 0 │ 1 │ 2 │ 3 │ 4 │
-│ 4KB │ 4KB │ 4KB │ 4KB │ 4KB │
-│ │ │ │ │ │
-│ weak:A │ weak:B │ weak:C │ weak:D │ weak:E │
-│ sha:X1 │ sha:X2 │ sha:X3 │ sha:X4 │ sha:X5 │
-└────────┴────────┴────────┴────────┴────────┘
-
-Modified file (client):
-┌────────┬────────┬────────┬────────┬────────┐
-│ Bloque │ Bloque │ Bloque │ Bloque │ Bloque │
-│ 0 │ 1 │ 2 │ 3 │ 4 │
-│ 4KB │ 4KB │ 4KB │ 4KB │ 4KB │
-│ │ │ │ │ │
-│ weak:A │ weak:B │ weak:F │ weak:D │ weak:E │ ← Block 2 changed
-│ sha:X1 │ sha:X2 │ sha:Y3 │ sha:X4 │ sha:X5 │
-└────────┴────────┴───▲────┴────────┴────────┘
- │
- ONLY THIS ONE GETS TRANSFERRED
-```
-
-### Sync flow
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│ DELTA SYNC FLOW │
-├─────────────────────────────────────────────────────────────────────┤
-│ │
-│ CLIENT SERVER │
-│ │
-│ 1. Has modified 1. Has original file │
-│ file + block index │
-│ │
-│ 2. Requests signatures ─────────────► │
-│ GET /files/{id}/signatures │
-│ │
-│ ◄────────────── 3. Returns signature list │
-│ [(weak, strong), ...] │
-│ │
-│ 4. Compares local blocks │
-│ against server │
-│ signatures │
-│ │
-│ 5. Generates delta ──────────────────► │
-│ POST /files/{id}/delta │
-│ [References + New data] │
-│ │
-│ 6. Reconstructs file │
-│ by applying delta │
-│ │
-│ ◄────────────── 7. Confirms update │
-│ │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Key Algorithms
-
-### 1. Rolling Checksum (modified Adler-32)
-
-The rolling checksum computes the hash of a sliding window in O(1):
-
-```rust
-/// Rolling checksum para búsqueda rápida de bloques coincidentes
-/// Similar al usado por rsync (Adler-32 modificado)
-pub struct RollingChecksum {
- a: u32, // Suma simple de bytes
- b: u32, // Suma ponderada
- window_size: usize,
- buffer: VecDeque,
-}
-
-impl RollingChecksum {
- pub fn new(window_size: usize) -> Self {
- Self {
- a: 0,
- b: 0,
- window_size,
- buffer: VecDeque::with_capacity(window_size),
- }
- }
-
- /// Añadir un byte y calcular nuevo checksum
- /// Complejidad: O(1)
- pub fn roll(&mut self, new_byte: u8) -> u32 {
- if self.buffer.len() >= self.window_size {
- // Remover byte antiguo
- let old_byte = self.buffer.pop_front().unwrap() as u32;
- self.a = self.a.wrapping_sub(old_byte).wrapping_add(new_byte as u32);
- self.b = self.b.wrapping_sub(old_byte * self.window_size as u32)
- .wrapping_add(self.a);
- } else {
- // Ventana no llena todavía
- self.a = self.a.wrapping_add(new_byte as u32);
- self.b = self.b.wrapping_add(self.a);
- }
-
- self.buffer.push_back(new_byte);
- self.checksum()
- }
-
- /// Calcular checksum actual
- pub fn checksum(&self) -> u32 {
- (self.b << 16) | (self.a & 0xFFFF)
- }
-
- /// Reset para nuevo archivo
- pub fn reset(&mut self) {
- self.a = 0;
- self.b = 0;
- self.buffer.clear();
- }
-}
-```
-
-### 2. Block Signature
-
-Each block carries two signatures:
-- **Weak checksum** (32-bit) -- fast O(1) lookup
-- **Strong hash** (SHA-256) -- definitive verification
-
-```rust
-/// Firma de un bloque para identificación
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct BlockSignature {
- /// Índice del bloque en el archivo
- pub index: u32,
- /// Offset en bytes desde el inicio del archivo
- pub offset: u64,
- /// Tamaño del bloque (puede ser menor para el último)
- pub size: u32,
- /// Rolling checksum (32-bit) - búsqueda rápida
- pub weak_checksum: u32,
- /// SHA-256 hash (256-bit) - verificación definitiva
- pub strong_hash: [u8; 32],
-}
-
-/// Genera firmas para todos los bloques de un archivo
-pub fn generate_signatures(data: &[u8], block_size: usize) -> Vec {
- let mut signatures = Vec::new();
- let mut offset = 0u64;
- let mut index = 0u32;
-
- for chunk in data.chunks(block_size) {
- // Weak checksum (rolling)
- let weak = adler32_checksum(chunk);
-
- // Strong hash (SHA-256)
- let mut hasher = Sha256::new();
- hasher.update(chunk);
- let strong: [u8; 32] = hasher.finalize().into();
-
- signatures.push(BlockSignature {
- index,
- offset,
- size: chunk.len() as u32,
- weak_checksum: weak,
- strong_hash: strong,
- });
-
- offset += chunk.len() as u64;
- index += 1;
- }
-
- signatures
-}
-
-fn adler32_checksum(data: &[u8]) -> u32 {
- let mut a: u32 = 1;
- let mut b: u32 = 0;
-
- for &byte in data {
- a = (a + byte as u32) % 65521;
- b = (b + a) % 65521;
- }
-
- (b << 16) | a
-}
-```
-
-### 3. Delta Generation
-
-```rust
-/// Instrucción de delta
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub enum DeltaInstruction {
- /// Copiar bloque existente del archivo original
- Copy {
- /// Índice del bloque en el archivo original
- block_index: u32,
- },
- /// Insertar datos literales nuevos
- Literal {
- /// Datos nuevos a insertar
- data: Vec,
- },
-}
-
-/// Delta completo para actualizar un archivo
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct FileDelta {
- /// ID del archivo base
- pub base_file_id: String,
- /// Hash del archivo base (para verificación)
- pub base_file_hash: String,
- /// Nuevo tamaño del archivo
- pub new_size: u64,
- /// Instrucciones de delta
- pub instructions: Vec,
- /// Hash del archivo resultante (para verificación)
- pub result_hash: String,
-}
-
-/// Genera delta comparando archivo local con firmas remotas
-pub fn generate_delta(
- local_data: &[u8],
- remote_signatures: &[BlockSignature],
- block_size: usize,
-) -> FileDelta {
- // Crear índice de weak checksums para búsqueda O(1)
- let mut weak_index: HashMap> = HashMap::new();
- for sig in remote_signatures {
- weak_index.entry(sig.weak_checksum)
- .or_default()
- .push(sig);
- }
-
- let mut instructions = Vec::new();
- let mut rolling = RollingChecksum::new(block_size);
- let mut pos = 0;
- let mut literal_buffer = Vec::new();
-
- while pos < local_data.len() {
- // Calcular rolling checksum de la ventana actual
- let end = (pos + block_size).min(local_data.len());
- let window = &local_data[pos..end];
-
- let weak = if window.len() == block_size {
- rolling.reset();
- for &b in window {
- rolling.roll(b);
- }
- rolling.checksum()
- } else {
- adler32_checksum(window)
- };
-
- // Buscar coincidencia
- let mut found_match = false;
-
- if let Some(candidates) = weak_index.get(&weak) {
- // Verificar con strong hash
- let mut hasher = Sha256::new();
- hasher.update(window);
- let strong: [u8; 32] = hasher.finalize().into();
-
- for sig in candidates {
- if sig.strong_hash == strong && sig.size as usize == window.len() {
- // ¡Coincidencia encontrada!
-
- // Flush literal buffer si hay datos pendientes
- if !literal_buffer.is_empty() {
- instructions.push(DeltaInstruction::Literal {
- data: std::mem::take(&mut literal_buffer),
- });
- }
-
- // Añadir instrucción de copia
- instructions.push(DeltaInstruction::Copy {
- block_index: sig.index,
- });
-
- pos += window.len();
- found_match = true;
- break;
- }
- }
- }
-
- if !found_match {
- // No hay coincidencia, añadir byte a literal buffer
- literal_buffer.push(local_data[pos]);
- pos += 1;
- }
- }
-
- // Flush remaining literal buffer
- if !literal_buffer.is_empty() {
- instructions.push(DeltaInstruction::Literal {
- data: literal_buffer,
- });
- }
-
- // Calcular hash del resultado
- let mut hasher = Sha256::new();
- hasher.update(local_data);
- let result_hash = hex::encode(hasher.finalize());
-
- FileDelta {
- base_file_id: String::new(), // Se llena al enviar
- base_file_hash: String::new(), // Se llena al enviar
- new_size: local_data.len() as u64,
- instructions,
- result_hash,
- }
-}
-```
-
-### 4. Delta Application
-
-```rust
-/// Aplica delta a un archivo base para obtener el nuevo archivo
-pub fn apply_delta(
- base_data: &[u8],
- signatures: &[BlockSignature],
- delta: &FileDelta,
- block_size: usize,
-) -> Result, DeltaSyncError> {
- let mut result = Vec::with_capacity(delta.new_size as usize);
-
- for instruction in &delta.instructions {
- match instruction {
- DeltaInstruction::Copy { block_index } => {
- // Copiar bloque del archivo base
- let sig = signatures.get(*block_index as usize)
- .ok_or(DeltaSyncError::InvalidBlockIndex(*block_index))?;
-
- let start = sig.offset as usize;
- let end = start + sig.size as usize;
-
- if end > base_data.len() {
- return Err(DeltaSyncError::InvalidBlockRange);
- }
-
- result.extend_from_slice(&base_data[start..end]);
- }
- DeltaInstruction::Literal { data } => {
- // Insertar datos literales
- result.extend_from_slice(data);
- }
- }
- }
-
- // Verificar hash del resultado
- let mut hasher = Sha256::new();
- hasher.update(&result);
- let actual_hash = hex::encode(hasher.finalize());
-
- if actual_hash != delta.result_hash {
- return Err(DeltaSyncError::HashMismatch {
- expected: delta.result_hash.clone(),
- actual: actual_hash,
- });
- }
-
- Ok(result)
-}
-```
-
----
-
-## Proposed Architecture
-
-### File structure
-
-```
-src/
-├── infrastructure/
-│ └── services/
-│ ├── mod.rs # Añadir: pub mod delta_sync_service;
-│ └── delta_sync_service.rs # NUEVO: Servicio principal
-│
-├── interfaces/
-│ └── api/
-│ └── handlers/
-│ ├── mod.rs # Añadir: pub mod delta_sync_handler;
-│ └── delta_sync_handler.rs # NUEVO: Endpoints API
-│
-└── common/
- └── di.rs # Añadir: delta_sync_service a AppState
-```
-
-### Main service (delta_sync_service.rs)
-
-```rust
-//! Delta Sync Service - Sincronización eficiente por diferencias
-//!
-//! Implementa algoritmo similar a rsync para transferir solo
-//! las partes modificadas de los archivos.
-
-use std::collections::HashMap;
-use std::path::{Path, PathBuf};
-use std::sync::Arc;
-use tokio::fs;
-use tokio::sync::RwLock;
-use sha2::{Sha256, Digest};
-use serde::{Deserialize, Serialize};
-
-/// Tamaño de bloque por defecto (16KB - buen balance)
-pub const DEFAULT_BLOCK_SIZE: usize = 16 * 1024;
-
-/// Tamaño mínimo de archivo para usar delta sync
-pub const MIN_DELTA_SYNC_SIZE: u64 = 64 * 1024; // 64KB
-
-/// Errores del servicio Delta Sync
-#[derive(Debug, thiserror::Error)]
-pub enum DeltaSyncError {
- #[error("Archivo no encontrado: {0}")]
- FileNotFound(String),
-
- #[error("Firmas no encontradas para archivo: {0}")]
- SignaturesNotFound(String),
-
- #[error("Índice de bloque inválido: {0}")]
- InvalidBlockIndex(u32),
-
- #[error("Rango de bloque inválido")]
- InvalidBlockRange,
-
- #[error("Hash no coincide: esperado {expected}, actual {actual}")]
- HashMismatch { expected: String, actual: String },
-
- #[error("Error de I/O: {0}")]
- IoError(#[from] std::io::Error),
-
- #[error("Error de serialización: {0}")]
- SerializationError(String),
-}
-
-/// Servicio de Delta Sync
-pub struct DeltaSyncService {
- /// Directorio para almacenar índices de firmas
- signatures_dir: PathBuf,
- /// Cache en memoria de firmas recientes
- signature_cache: Arc>>>,
- /// Tamaño de bloque configurado
- block_size: usize,
- /// Máximo de entradas en cache
- max_cache_entries: usize,
-}
-
-impl DeltaSyncService {
- pub fn new(storage_root: &Path) -> Self {
- Self {
- signatures_dir: storage_root.join(".delta_signatures"),
- signature_cache: Arc::new(RwLock::new(HashMap::new())),
- block_size: DEFAULT_BLOCK_SIZE,
- max_cache_entries: 1000,
- }
- }
-
- pub fn with_block_size(mut self, block_size: usize) -> Self {
- self.block_size = block_size;
- self
- }
-
- /// Inicializar servicio (crear directorios)
- pub async fn initialize(&self) -> std::io::Result<()> {
- fs::create_dir_all(&self.signatures_dir).await?;
- tracing::info!("Delta Sync service initialized with block size: {}KB",
- self.block_size / 1024);
- Ok(())
- }
-
- /// Generar y almacenar firmas para un archivo
- pub async fn index_file(
- &self,
- file_id: &str,
- file_path: &Path
- ) -> Result, DeltaSyncError> {
- let data = fs::read(file_path).await?;
-
- // No indexar archivos pequeños
- if data.len() < MIN_DELTA_SYNC_SIZE as usize {
- return Ok(Vec::new());
- }
-
- let signatures = generate_signatures(&data, self.block_size);
-
- // Guardar en disco
- let sig_path = self.signature_path(file_id);
- let sig_json = serde_json::to_vec(&signatures)
- .map_err(|e| DeltaSyncError::SerializationError(e.to_string()))?;
- fs::write(&sig_path, sig_json).await?;
-
- // Actualizar cache
- {
- let mut cache = self.signature_cache.write().await;
- if cache.len() >= self.max_cache_entries {
- // LRU simple: eliminar primera entrada
- if let Some(key) = cache.keys().next().cloned() {
- cache.remove(&key);
- }
- }
- cache.insert(file_id.to_string(), signatures.clone());
- }
-
- tracing::debug!("Indexed file {} with {} blocks", file_id, signatures.len());
- Ok(signatures)
- }
-
- /// Obtener firmas de un archivo
- pub async fn get_signatures(
- &self,
- file_id: &str
- ) -> Result, DeltaSyncError> {
- // Buscar en cache primero
- {
- let cache = self.signature_cache.read().await;
- if let Some(sigs) = cache.get(file_id) {
- return Ok(sigs.clone());
- }
- }
-
- // Cargar de disco
- let sig_path = self.signature_path(file_id);
- if !sig_path.exists() {
- return Err(DeltaSyncError::SignaturesNotFound(file_id.to_string()));
- }
-
- let sig_json = fs::read(&sig_path).await?;
- let signatures: Vec = serde_json::from_slice(&sig_json)
- .map_err(|e| DeltaSyncError::SerializationError(e.to_string()))?;
-
- // Actualizar cache
- {
- let mut cache = self.signature_cache.write().await;
- cache.insert(file_id.to_string(), signatures.clone());
- }
-
- Ok(signatures)
- }
-
- /// Aplicar delta a un archivo
- pub async fn apply_delta(
- &self,
- file_id: &str,
- base_path: &Path,
- delta: &FileDelta,
- ) -> Result, DeltaSyncError> {
- let base_data = fs::read(base_path).await?;
- let signatures = self.get_signatures(file_id).await?;
-
- apply_delta(&base_data, &signatures, delta, self.block_size)
- }
-
- /// Eliminar firmas de un archivo (cuando se borra)
- pub async fn remove_signatures(&self, file_id: &str) -> Result<(), DeltaSyncError> {
- // Eliminar de cache
- {
- let mut cache = self.signature_cache.write().await;
- cache.remove(file_id);
- }
-
- // Eliminar de disco
- let sig_path = self.signature_path(file_id);
- if sig_path.exists() {
- fs::remove_file(&sig_path).await?;
- }
-
- Ok(())
- }
-
- /// Estadísticas del servicio
- pub async fn get_stats(&self) -> DeltaSyncStats {
- let cache = self.signature_cache.read().await;
- DeltaSyncStats {
- cached_files: cache.len() as u64,
- block_size: self.block_size,
- }
- }
-
- fn signature_path(&self, file_id: &str) -> PathBuf {
- // Usar primeros 2 chars del ID para subdirectorio
- let prefix = &file_id[..2.min(file_id.len())];
- self.signatures_dir.join(prefix).join(format!("{}.sig", file_id))
- }
-}
-
-#[derive(Debug, Clone, Serialize)]
-pub struct DeltaSyncStats {
- pub cached_files: u64,
- pub block_size: usize,
-}
-```
-
----
-
-## API Endpoints
-
-### Handler (delta_sync_handler.rs)
-
-```rust
-use axum::{
- extract::{Path, State, Json},
- http::StatusCode,
- response::IntoResponse,
-};
-use crate::common::di::AppState;
-use crate::infrastructure::services::delta_sync_service::*;
-
-pub struct DeltaSyncHandler;
-
-impl DeltaSyncHandler {
- /// GET /api/files/{id}/signatures
- ///
- /// Obtiene las firmas de bloques de un archivo para calcular delta
- pub async fn get_signatures(
- State(state): State,
- Path(file_id): Path,
- ) -> impl IntoResponse {
- let delta_service = &state.core.delta_sync_service;
-
- match delta_service.get_signatures(&file_id).await {
- Ok(signatures) => {
- Json(SignaturesResponse {
- file_id,
- block_size: delta_service.block_size,
- block_count: signatures.len() as u32,
- signatures,
- }).into_response()
- }
- Err(DeltaSyncError::SignaturesNotFound(_)) => {
- // Archivo no indexado - cliente debe hacer upload completo
- (StatusCode::NOT_FOUND, Json(serde_json::json!({
- "error": "Signatures not found",
- "hint": "File not indexed for delta sync, use full upload"
- }))).into_response()
- }
- Err(e) => {
- (StatusCode::INTERNAL_SERVER_ERROR, Json(serde_json::json!({
- "error": e.to_string()
- }))).into_response()
- }
- }
- }
-
- /// POST /api/files/{id}/delta
- ///
- /// Aplica un delta para actualizar un archivo
- pub async fn apply_delta(
- State(state): State,
- Path(file_id): Path,
- Json(delta): Json,
- ) -> impl IntoResponse {
- let delta_service = &state.core.delta_sync_service;
- let file_service = &state.applications.file_service;
-
- // Obtener path del archivo actual
- let file = match file_service.get_file(&file_id).await {
- Ok(f) => f,
- Err(_) => {
- return (StatusCode::NOT_FOUND, Json(serde_json::json!({
- "error": "File not found"
- }))).into_response();
- }
- };
-
- // Aplicar delta
- let file_path = state.core.path_service.resolve_path(file.path());
- match delta_service.apply_delta(&file_id, &file_path, &delta).await {
- Ok(new_data) => {
- // Guardar nuevo contenido
- if let Err(e) = tokio::fs::write(&file_path, &new_data).await {
- return (StatusCode::INTERNAL_SERVER_ERROR, Json(serde_json::json!({
- "error": format!("Failed to write file: {}", e)
- }))).into_response();
- }
-
- // Re-indexar archivo
- if let Err(e) = delta_service.index_file(&file_id, &file_path).await {
- tracing::warn!("Failed to re-index file after delta: {}", e);
- }
-
- // Calcular estadísticas
- let delta_size: usize = delta.instructions.iter()
- .filter_map(|i| match i {
- DeltaInstruction::Literal { data } => Some(data.len()),
- _ => None,
- })
- .sum();
-
- Json(DeltaApplyResponse {
- success: true,
- new_size: new_data.len() as u64,
- delta_size: delta_size as u64,
- savings_percent: if new_data.len() > 0 {
- ((1.0 - (delta_size as f64 / new_data.len() as f64)) * 100.0) as u32
- } else { 0 },
- }).into_response()
- }
- Err(e) => {
- (StatusCode::BAD_REQUEST, Json(serde_json::json!({
- "error": e.to_string()
- }))).into_response()
- }
- }
- }
-
- /// POST /api/files/{id}/index
- ///
- /// Fuerza la indexación de un archivo para delta sync
- pub async fn index_file(
- State(state): State,
- Path(file_id): Path,
- ) -> impl IntoResponse {
- let delta_service = &state.core.delta_sync_service;
- let file_service = &state.applications.file_service;
-
- // Obtener path del archivo
- let file = match file_service.get_file(&file_id).await {
- Ok(f) => f,
- Err(_) => {
- return (StatusCode::NOT_FOUND, Json(serde_json::json!({
- "error": "File not found"
- }))).into_response();
- }
- };
-
- let file_path = state.core.path_service.resolve_path(file.path());
- match delta_service.index_file(&file_id, &file_path).await {
- Ok(signatures) => {
- Json(serde_json::json!({
- "success": true,
- "blocks_indexed": signatures.len()
- })).into_response()
- }
- Err(e) => {
- (StatusCode::INTERNAL_SERVER_ERROR, Json(serde_json::json!({
- "error": e.to_string()
- }))).into_response()
- }
- }
- }
-
- /// GET /api/delta/stats
- ///
- /// Estadísticas del servicio delta sync
- pub async fn get_stats(
- State(state): State,
- ) -> impl IntoResponse {
- let delta_service = &state.core.delta_sync_service;
- Json(delta_service.get_stats().await)
- }
-}
-
-#[derive(Serialize)]
-struct SignaturesResponse {
- file_id: String,
- block_size: usize,
- block_count: u32,
- signatures: Vec,
-}
-
-#[derive(Serialize)]
-struct DeltaApplyResponse {
- success: bool,
- new_size: u64,
- delta_size: u64,
- savings_percent: u32,
-}
-```
-
-### Routes to add in routes.rs
-
-```rust
-// Delta Sync routes
-let delta_sync_router = Router::new()
- .route("/files/:id/signatures", get(DeltaSyncHandler::get_signatures))
- .route("/files/:id/delta", post(DeltaSyncHandler::apply_delta))
- .route("/files/:id/index", post(DeltaSyncHandler::index_file))
- .route("/delta/stats", get(DeltaSyncHandler::get_stats))
- .with_state(app_state.clone());
-
-// Añadir a router principal
-router = router.nest("/api", delta_sync_router);
-```
-
----
-
-## Integration with Existing System
-
-### 1. Auto-index on upload
-
-In `file_handler.rs`, after a successful upload:
-
-```rust
-// Después de guardar el archivo...
-
-// Indexar para delta sync (archivos >64KB)
-if total_size >= 64 * 1024 {
- let delta_service = &state.core.delta_sync_service;
- if let Err(e) = delta_service.index_file(&file.id, &file_path).await {
- tracing::warn!("Failed to index file for delta sync: {}", e);
- // No es error fatal, el archivo se subió correctamente
- }
-}
-```
-
-### 2. Clean up signatures on delete
-
-In `file_handler.rs`, when deleting a file:
-
-```rust
-// Limpiar firmas de delta sync
-let delta_service = &state.core.delta_sync_service;
-if let Err(e) = delta_service.remove_signatures(&id).await {
- tracing::warn!("Failed to remove delta signatures: {}", e);
-}
-```
-
-### 3. Integration with Dedup Service
-
-Delta sync and dedup are complementary:
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│ UPLOAD WITH DELTA + DEDUP │
-├──────────────────────────────────────────────────────────────┤
-│ │
-│ 1. Client has modified file.txt │
-│ │
-│ 2. GET /files/{id}/signatures │
-│ → Server returns block signatures │
-│ │
-│ 3. Client computes delta locally │
-│ → Only 3 of 100 blocks changed │
-│ │
-│ 4. POST /files/{id}/delta │
-│ → Sends only the 3 new blocks │
-│ │
-│ 5. Server applies delta │
-│ → Reconstructs complete file │
-│ │
-│ 6. Server runs dedup on resulting file │
-│ → If another user has same content, it deduplicates │
-│ │
-│ RESULT: │
-│ ├── Delta sync: 97% less transfer │
-│ └── Dedup: 30-50% less storage │
-│ │
-└──────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Use Cases and Effectiveness
-
-| File type | Scenario | Without Delta | With Delta | Savings |
-|-----------------|-----------|-----------|-----------|--------|
-| `.txt` / `.md` | Edit paragraph | 1MB | ~4KB | **99.6%** |
-| `.json` / `.xml` | Change value | 500KB | ~1KB | **99.8%** |
-| `.rs` / `.js` | Modify function | 100KB | ~2KB | **98%** |
-| `.docx` | Edit page | 5MB | ~100KB | **98%** |
-| `.xlsx` | Change cells | 2MB | ~50KB | **97.5%** |
-| `.pdf` | Edit text | 10MB | ~2MB | **80%** |
-| `.psd` | Edit layer | 100MB | ~5MB | **95%** |
-| `.zip` | Add file | 50MB | ~5MB | **90%** |
-| `.mp4` | Re-encode | 500MB | 450MB | **10%** |
-| `.jpg` | Edit image | 5MB | 4MB | **20%** |
-
-For highly compressed or re-encoded files, delta sync is less effective.
-
----
-
-## Performance Considerations
-
-### Optimal block size
-
-| Size | Pros | Cons | Best for |
-|--------|------|------|------------|
-| 4KB | More granular, better savings | More signature overhead | Small files |
-| 16KB | Good balance | - | **General use** |
-| 64KB | Less overhead | Less granular | Large files |
-| 256KB | Minimal overhead | Little savings | Very large files |
-
-### Memory
-
-```rust
-// Estimación de memoria por archivo indexado
-//
-// BlockSignature size ≈ 48 bytes (4 + 8 + 4 + 4 + 32 - con padding)
-//
-// Archivo 100MB con bloques de 16KB:
-// - 100MB / 16KB = 6,400 bloques
-// - 6,400 × 48 bytes = ~300KB de firmas
-//
-// Cache de 1000 archivos ≈ 300MB máximo
-```
-
-### CPU
-
-```rust
-// Operaciones costosas:
-//
-// 1. generate_signatures(): O(n) donde n = tamaño archivo
-// - SHA-256: ~500MB/s en CPU moderna
-// - Adler32: ~2GB/s
-//
-// 2. generate_delta(): O(n × m) peor caso, O(n) típico
-// - n = tamaño archivo nuevo
-// - m = número de bloques originales
-// - HashMap lookup: O(1) promedio
-//
-// 3. apply_delta(): O(n) donde n = tamaño resultado
-// - Mayormente copias de memoria
-```
-
----
-
-## Testing
-
-### Unit tests
-
-```rust
-#[cfg(test)]
-mod tests {
- use super::*;
-
- #[test]
- fn test_rolling_checksum() {
- let mut rc = RollingChecksum::new(4);
-
- // Alimentar bytes
- for b in b"test" {
- rc.roll(*b);
- }
- let checksum1 = rc.checksum();
-
- // Rolling: quitar 't', añadir 'X'
- rc.roll(b'X');
- let checksum2 = rc.checksum();
-
- // Checksums deben ser diferentes
- assert_ne!(checksum1, checksum2);
- }
-
- #[test]
- fn test_generate_signatures() {
- let data = b"Hello, World! This is a test file for delta sync.";
- let sigs = generate_signatures(data, 16);
-
- assert_eq!(sigs.len(), 4); // 50 bytes / 16 = 3.125 → 4 bloques
- assert_eq!(sigs[0].offset, 0);
- assert_eq!(sigs[1].offset, 16);
- }
-
- #[test]
- fn test_delta_identical_files() {
- let data = b"Hello, World!";
- let sigs = generate_signatures(data, 8);
- let delta = generate_delta(data, &sigs, 8);
-
- // Solo instrucciones Copy, sin Literal
- for instr in &delta.instructions {
- assert!(matches!(instr, DeltaInstruction::Copy { .. }));
- }
- }
-
- #[test]
- fn test_delta_small_change() {
- let original = b"Hello, World! This is original.";
- let modified = b"Hello, World! This is MODIFIED.";
-
- let sigs = generate_signatures(original, 8);
- let delta = generate_delta(modified, &sigs, 8);
-
- // Debería haber algunas instrucciones Copy y algunas Literal
- let copies = delta.instructions.iter()
- .filter(|i| matches!(i, DeltaInstruction::Copy { .. }))
- .count();
- let literals = delta.instructions.iter()
- .filter(|i| matches!(i, DeltaInstruction::Literal { .. }))
- .count();
-
- assert!(copies > 0, "Should reuse some blocks");
- assert!(literals > 0, "Should have some new data");
- }
-
- #[test]
- fn test_apply_delta_roundtrip() {
- let original = b"The quick brown fox jumps over the lazy dog.";
- let modified = b"The quick brown cat jumps over the lazy dog.";
-
- let sigs = generate_signatures(original, 8);
- let delta = generate_delta(modified, &sigs, 8);
- let reconstructed = apply_delta(original, &sigs, &delta, 8).unwrap();
-
- assert_eq!(reconstructed, modified);
- }
-}
-```
-
-### Integration tests
-
-```rust
-#[tokio::test]
-async fn test_delta_sync_service_workflow() {
- let temp_dir = tempfile::tempdir().unwrap();
- let service = DeltaSyncService::new(temp_dir.path());
- service.initialize().await.unwrap();
-
- // Crear archivo original
- let file_path = temp_dir.path().join("test.txt");
- tokio::fs::write(&file_path, b"Original content here").await.unwrap();
-
- // Indexar
- let sigs = service.index_file("file123", &file_path).await.unwrap();
- assert!(!sigs.is_empty());
-
- // Recuperar firmas
- let retrieved = service.get_signatures("file123").await.unwrap();
- assert_eq!(sigs.len(), retrieved.len());
-
- // Simular modificación y delta
- let modified = b"Modified content here!";
- let delta = generate_delta(modified, &sigs, service.block_size);
-
- // Aplicar delta
- let result = service.apply_delta("file123", &file_path, &delta).await.unwrap();
- assert_eq!(result, modified);
-}
-```
-
----
-
-## Required Dependencies
-
-Add to `Cargo.toml`:
-
-```toml
-[dependencies]
-# Ya existentes - verificar versiones
-sha2 = "0.10"
-hex = "0.4"
-
-# Nuevas dependencias para delta sync
-thiserror = "1.0" # Para errores tipados (probablemente ya existe)
-```
-
----
-
-## Implementation Checklist
-
-- [ ] Create `delta_sync_service.rs` with basic structures
-- [ ] Implement **RollingChecksum**
-- [ ] Implement **generate_signatures()**
-- [ ] Implement **generate_delta()**
-- [ ] Implement **apply_delta()**
-- [ ] Create handler and API endpoints
-- [ ] Integrate into DI (**AppState**)
-- [ ] Add routes in `routes.rs`
-- [ ] Integrate with upload (automatic indexing)
-- [ ] Integrate with delete (signature cleanup)
-- [ ] Unit tests
-- [ ] Integration tests
-- [ ] Document API endpoints
-- [ ] Metrics and logging
-
----
-
-## References
-
-- [rsync algorithm](https://rsync.samba.org/tech_report/)
-- [Rolling hash - Wikipedia](https://en.wikipedia.org/wiki/Rolling_hash)
-- [Adler-32 checksum](https://en.wikipedia.org/wiki/Adler-32)
-- [librsync](https://github.com/librsync/librsync)
diff --git a/doc/internal-architecture.md b/doc/internal-architecture.md
deleted file mode 100644
index a89bdcf3..00000000
--- a/doc/internal-architecture.md
+++ /dev/null
@@ -1,474 +0,0 @@
-# 01 - Internal Architecture
-
-OxiCloud follows a **hexagonal (ports & adapters) architecture** organized in four layers:
-
-```
-Domain → Application → Infrastructure → Interfaces
-```
-
-All cross-layer dependencies point inward via trait-based ports. The DI container (**AppServiceFactory**) wires concrete implementations at startup.
-
----
-
-## Storage Model: 100% Blob Storage
-
-OxiCloud uses a **100% blob storage model** where:
-
-- **File metadata** (name, folder, size, user, timestamps, trash status) is stored in **PostgreSQL** (`storage.files` table).
-- **File content** is stored as content-addressed blobs via **DedupService** at `.blobs/{prefix}/{hash}.blob`.
-- **Folder structure** is purely virtual — represented as rows in `storage.folders` (no filesystem directories per user).
-- **Trash** is a soft-delete flag (`is_trashed`, `trashed_at`) on files and folders, exposed via `storage.trash_items` VIEW.
-
-There are no filesystem-based ID mappings, no `folder_ids.json`/`file_ids.json`, and no storage mediator.
-
----
-
-## Dependency Injection Container
-
-### AppServiceFactory
-
-**File:** `src/common/di.rs`
-
-```rust
-pub struct AppServiceFactory {
- storage_path: PathBuf,
- locales_path: PathBuf,
- config: AppConfig,
-}
-```
-
-Initialization order in `build_app_state()`:
-
-1. **Core services** — path, content cache, thumbnail, chunked upload, transcode, dedup, compression
-2. **Repository services** — `FolderDbRepository`, `FileBlobReadRepository`, `FileBlobWriteRepository`, `TrashDbRepository` (all PgPool-backed)
-3. **Trash service** (if **enable_trash** enabled)
-4. **Application services** — folder, file upload/retrieval/management, search, i18n
-5. **Share service** (if **enable_file_sharing** enabled)
-6. **DB-dependent services** — favorites, recent, storage usage, auth (via **auth_factory**)
-7. **Preload** translations
-8. **ZIP service** (needs file retrieval + folder service, wired last)
-9. **Assemble AppState** + admin settings + CalDAV/CardDAV
-
-### AppState (Global State)
-
-```rust
-pub struct AppState {
- pub core: CoreServices,
- pub repositories: RepositoryServices,
- pub applications: ApplicationServices,
- pub db_pool: Option>,
- pub auth_service: Option,
- pub admin_settings_service: Option>,
- pub trash_service: Option>,
- pub share_service: Option>,
- pub favorites_service: Option>,
- pub recent_service: Option>,
- pub storage_usage_service: Option>,
- pub calendar_service: Option>,
- pub contact_service: Option>,
- pub calendar_use_case: Option>,
- pub addressbook_use_case: Option>,
- pub contact_use_case: Option>,
-}
-```
-
-Builder pattern: `new()` → `with_database()` → `with_auth_services()` → `with_trash_service()` → ... → `for_routing()`. The `Default` impl uses stubs from `crate::common::stubs`.
-
-### Service Groups
-
-```rust
-pub struct CoreServices {
- pub path_service: Arc,
- pub file_content_cache: Arc,
- pub thumbnail_service: Arc,
- pub chunked_upload_service: Arc,
- pub image_transcode_service: Arc,
- pub dedup_service: Arc,
- pub compression_service: Arc,
- pub zip_service: Arc,
- pub config: AppConfig,
-}
-
-pub struct RepositoryServices {
- pub folder_repository: Arc,
- pub folder_repo_concrete: Arc,
- pub file_read_repository: Arc,
- pub file_write_repository: Arc,
- pub i18n_repository: Arc,
- pub trash_repository: Option>,
-}
-
-pub struct ApplicationServices {
- pub folder_service_concrete: Arc,
- pub folder_service: Arc,
- pub file_upload_service: Arc,
- pub file_retrieval_service: Arc,
- pub file_management_service: Arc,
- pub file_use_case_factory: Arc,
- pub i18n_service: Arc,
- pub trash_service: Option>,
- pub search_service: Option>,
- pub share_service: Option>,
- pub favorites_service: Option>,
- pub recent_service: Option>,
-}
-
-pub struct AuthServices {
- pub token_service: Arc,
- pub auth_application_service: Arc,
-}
-```
-
----
-
-## Database Schema (Storage)
-
-All file and folder metadata lives in the `storage` PostgreSQL schema:
-
-```sql
-CREATE SCHEMA IF NOT EXISTS storage;
-
-CREATE TABLE storage.folders (
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
- name TEXT NOT NULL,
- parent_id UUID REFERENCES storage.folders(id) ON DELETE CASCADE,
- user_id VARCHAR(36) NOT NULL REFERENCES auth.users(id),
- is_trashed BOOLEAN NOT NULL DEFAULT FALSE,
- trashed_at TIMESTAMPTZ,
- original_parent_id UUID,
- created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
- updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-
-CREATE TABLE storage.files (
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
- name TEXT NOT NULL,
- folder_id UUID NOT NULL REFERENCES storage.folders(id) ON DELETE CASCADE,
- user_id VARCHAR(36) NOT NULL REFERENCES auth.users(id),
- blob_hash TEXT NOT NULL,
- size BIGINT NOT NULL DEFAULT 0,
- mime_type TEXT NOT NULL DEFAULT 'application/octet-stream',
- is_trashed BOOLEAN NOT NULL DEFAULT FALSE,
- trashed_at TIMESTAMPTZ,
- original_folder_id UUID,
- created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
- updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-
-CREATE OR REPLACE VIEW storage.trash_items AS
- SELECT id, name, 'file' AS item_type, folder_id AS parent_id,
- user_id, size, mime_type, trashed_at, created_at
- FROM storage.files WHERE is_trashed = TRUE
- UNION ALL
- SELECT id, name, 'folder' AS item_type, parent_id,
- user_id, 0 AS size, NULL AS mime_type, trashed_at, created_at
- FROM storage.folders WHERE is_trashed = TRUE;
-```
-
----
-
-## Repository Layer (Infrastructure)
-
-All repositories use **PgPool** for metadata and **DedupService** for blob content.
-
-### FolderDbRepository
-
-**File:** `src/infrastructure/repositories/pg/folder_db_repository.rs`
-
-```rust
-pub struct FolderDbRepository {
- pool: Option>,
-}
-```
-
-Implements `FolderRepository`. Uses recursive CTEs for path building, unique constraints for name dedup within parent, and soft-delete flags for trash operations.
-
-Key methods: `create_folder`, `get_folder`, `get_folder_by_path`, `list_folders`, `rename_folder`, `move_folder`, `delete_folder`, `move_to_trash`, `restore_from_trash`, `create_home_folder`, `get_folder_user_id`.
-
-`new_stub()` creates a pool-less instance for `AppState::default()`.
-
-### FileBlobReadRepository
-
-**File:** `src/infrastructure/repositories/pg/file_blob_read_repository.rs`
-
-```rust
-pub struct FileBlobReadRepository {
- pool: Arc,
- dedup: Arc,
- folder_repo: Arc,
-}
-```
-
-Implements `FileReadPort`. Reads metadata from `storage.files` and content from blob store via `dedup.read_blob()` / `read_blob_bytes()`.
-
-Key methods: `get_file`, `list_files`, `get_file_content`, `get_file_stream`, `get_file_range_stream`, `get_file_mmap`, `get_file_path`, `get_parent_folder_id`.
-
-### FileBlobWriteRepository
-
-**File:** `src/infrastructure/repositories/pg/file_blob_write_repository.rs`
-
-```rust
-pub struct FileBlobWriteRepository {
- pool: Arc,
- dedup: Arc,
- folder_repo: Arc,
-}
-```
-
-Implements `FileWritePort`. Stores content via `dedup.store_bytes()` (returns hash), then INSERTs metadata into `storage.files`.
-
-Key methods: `save_file`, `save_file_from_stream`, `move_file`, `rename_file`, `delete_file`, `update_file_content`, `move_to_trash`, `restore_from_trash`, `delete_file_permanently`.
-
-### TrashDbRepository
-
-**File:** `src/infrastructure/repositories/pg/trash_db_repository.rs`
-
-```rust
-pub struct TrashDbRepository {
- pool: Arc,
- retention_days: u32,
-}
-```
-
-Implements `TrashRepository`. Reads from `storage.trash_items` VIEW. `clear_trash` DELETEs rows where `is_trashed = TRUE`. `get_expired_items` checks `trashed_at` against the configured retention period.
-
----
-
-## Path Service
-
-**File:** `src/infrastructure/services/path_service.rs`
-
-```rust
-pub struct PathService {
- root_path: PathBuf, // e.g., ./storage
-}
-```
-
-Used for resolving storage root paths (blob storage directory, thumbnail paths, etc.). Not used for per-user folder resolution — that is handled by `FolderDbRepository` via PostgreSQL.
-
-### StoragePath (Domain Value Object)
-
-**File:** `src/domain/services/path_service.rs`
-
-```rust
-#[derive(Debug, Clone, PartialEq, Eq, Default)]
-pub struct StoragePath {
- segments: Vec,
-}
-```
-
-| Method | Description |
-|---|---|
-| `root()` | Empty path (storage root) |
-| `from_string(path)` | Parse from `/`-delimited string |
-| `join(segment)` | Append a segment |
-| `file_name()` | Last segment |
-| `parent()` | All segments except last |
-| `to_string()` | Join segments with `/` |
-
-### Trait Implementations
-
-- **StoragePort** — `resolve_path()`, `ensure_directory()`, `file_exists()`, `directory_exists()`
-
----
-
-## Session Management
-
-### Session Entity
-
-**File:** `src/domain/entities/session.rs`
-
-```rust
-pub struct Session {
- id: String, // UUID v4
- user_id: String,
- refresh_token: String,
- expires_at: DateTime,
- ip_address: Option,
- user_agent: Option,
- created_at: DateTime,
- revoked: bool,
-}
-```
-
-Constructors:
-- `Session::new(user_id, refresh_token, ip_address, user_agent, expires_in_days)` — generates UUID, panics if **user_id** or **refresh_token** empty
-- `Session::from_raw(...)` — for DB reconstruction
-
-### SessionRepository (Domain Port)
-
-**File:** `src/domain/repositories/session_repository.rs`
-
-```rust
-#[async_trait]
-pub trait SessionRepository: Send + Sync + 'static {
- async fn create_session(&self, session: Session) -> SessionRepositoryResult;
- async fn get_session_by_id(&self, id: &str) -> SessionRepositoryResult;
- async fn get_session_by_refresh_token(&self, token: &str) -> SessionRepositoryResult;
- async fn get_sessions_by_user_id(&self, user_id: &str) -> SessionRepositoryResult>;
- async fn revoke_session(&self, session_id: &str) -> SessionRepositoryResult<()>;
- async fn revoke_all_user_sessions(&self, user_id: &str) -> SessionRepositoryResult;
- async fn delete_expired_sessions(&self) -> SessionRepositoryResult;
-}
-```
-
-### SessionStoragePort (Application Port)
-
-**File:** `src/application/ports/auth_ports.rs`
-
-```rust
-#[async_trait]
-pub trait SessionStoragePort: Send + Sync + 'static {
- async fn create_session(&self, session: Session) -> Result;
- async fn get_session_by_refresh_token(&self, token: &str) -> Result;
- async fn revoke_session(&self, session_id: &str) -> Result<(), DomainError>;
- async fn revoke_all_user_sessions(&self, user_id: &str) -> Result;
-}
-```
-
-### SessionPgRepository (Infrastructure)
-
-**File:** `src/infrastructure/repositories/pg/session_pg_repository.rs`
-
-```rust
-pub struct SessionPgRepository {
- pool: Arc,
-}
-```
-
-Implements both **SessionRepository** and **SessionStoragePort**. Uses `with_transaction()` helper for write operations. `create_session` also updates `auth.users.last_login_at` within the same transaction.
-
-### Database Schema
-
-```sql
-CREATE TABLE IF NOT EXISTS auth.sessions (
- id VARCHAR(36) PRIMARY KEY,
- user_id VARCHAR(36) NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
- refresh_token TEXT NOT NULL UNIQUE,
- expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
- ip_address TEXT,
- user_agent TEXT,
- created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
- revoked BOOLEAN NOT NULL DEFAULT FALSE
-);
-
-CREATE INDEX idx_sessions_user_id ON auth.sessions(user_id);
-CREATE INDEX idx_sessions_refresh_token ON auth.sessions(refresh_token);
-CREATE INDEX idx_sessions_expires_at ON auth.sessions(expires_at);
-CREATE INDEX idx_sessions_active ON auth.sessions(user_id, revoked)
- WHERE NOT revoked AND is_session_active(expires_at);
-```
-
-### Auth Service
-
-**File:** `src/application/services/auth_application_service.rs`
-
-**AuthApplicationService** orchestrates authentication using:
-- **UserStoragePort** — user CRUD
-- **SessionStoragePort** — session lifecycle
-- **PasswordHasherPort** — Argon2id hashing
-- **TokenServicePort** — JWT generation/validation
-- `RwLock` — hot-reloadable OIDC configuration
-- `Mutex>` — in-flight OIDC login states
-
-Wired by `auth_factory.rs`: **UserPgRepository** + **SessionPgRepository** + **Argon2PasswordHasher** + **JwtTokenService** → **AuthApplicationService**.
-
----
-
-## File Use Case Factory
-
-**File:** `src/application/services/file_use_case_factory.rs`
-
-```rust
-pub trait FileUseCaseFactory: Send + Sync + 'static {
- fn create_file_upload_use_case(&self) -> Arc;
- fn create_file_retrieval_use_case(&self) -> Arc;
- fn create_file_management_use_case(&self) -> Arc;
-}
-```
-
-**AppFileUseCaseFactory** creates lightweight service instances with only **FileReadPort** / **FileWritePort**.
-
-### File Operation Port Hierarchy
-
-| Port | Key Methods |
-|---|---|
-| **FileUploadUseCase** | `upload_file()`, `smart_upload()` (returns **UploadStrategy**: `Buffered` <1MB, `Streaming` ≥1MB), `create_file()`, `update_file()` |
-| **FileRetrievalUseCase** | `get_file()`, `get_file_content()`, `get_file_stream()`, `get_file_optimized()` (content-cache → WebP transcode → mmap → streaming), `get_file_range_stream()` |
-| **FileManagementUseCase** | `move_file()`, `rename_file()`, `delete_file()`, `delete_with_cleanup()` (trash-first with dedup reference cleanup) |
-
----
-
-## Architecture Diagram
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ Interfaces Layer │
-│ Axum Router → API Routes + Middleware (Auth, Compress) │
-└─────────────────────┬───────────────────────────────────────┘
- │ Arc
-┌─────────────────────▼───────────────────────────────────────┐
-│ Application Layer │
-│ ┌──────────────┐ ┌──────────────┐ ┌─────────────────────┐ │
-│ │ FileUpload │ │ FolderService│ │ AuthApplication │ │
-│ │ FileRetrieval│ │ SearchService│ │ AdminSettings │ │
-│ │ FileMgmt │ │ I18nService │ │ TrashService │ │
-│ └──────┬───────┘ └──────┬───────┘ └──────────┬──────────┘ │
-│ │ Ports (traits) │ │ │
-└─────────┼────────────────┼─────────────────────┼────────────┘
- │ │ │
-┌─────────▼────────────────▼─────────────────────▼────────────┐
-│ Infrastructure Layer │
-│ ┌────────────────┐ ┌──────────────┐ ┌──────────────────┐ │
-│ │ FileBlobRead │ │ PathService │ │ SessionPg │ │
-│ │ FileBlobWrite │ │ DedupService │ │ UserPg │ │
-│ │ FolderDb │ │ Thumbnail │ │ JwtTokenService │ │
-│ │ TrashDb │ │ Transcode │ │ Argon2Hasher │ │
-│ └────────────────┘ └──────────────┘ └──────────────────┘ │
-│ ┌────────────────┐ ┌──────────────┐ ┌──────────────────┐ │
-│ │ ContentCache │ │ Compression │ │ ChunkedUpload │ │
-│ │ BufferPool │ │ ZipService │ │ ShareFsRepo │ │
-│ └────────────────┘ └──────────────┘ └──────────────────┘ │
-└─────────────────────────────────────────────────────────────┘
- │
-┌─────────────────────▼───────────────────────────────────────┐
-│ Domain Layer │
-│ Entities: File, Folder, Session, User, Calendar, Contact │
-│ Value Objects: StoragePath │
-│ Repository Traits: FolderRepository, TrashRepository, ... │
-│ Domain Errors │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Data Flow: File Upload
-
-```
-HTTP Request (multipart)
- → FileUploadService.smart_upload()
- → FileBlobWriteRepository.save_file() / save_file_from_stream()
- → DedupService.store_bytes() → .blobs/{prefix}/{hash}.blob
- → INSERT INTO storage.files (name, folder_id, blob_hash, size, ...)
- → 201 Created (FileDto)
-```
-
-### Data Flow: File Download
-
-```
-HTTP Request (GET /api/files/{id}/download)
- → FileRetrievalService.get_file_optimized()
- → ContentCache hit? → serve from RAM
- → FileBlobReadRepository.get_file_content() / get_file_stream()
- → SELECT blob_hash FROM storage.files WHERE id = $1
- → DedupService.read_blob(hash) → bytes from .blobs/
- → Optional WebP transcode → response
-```
-
-### Data Flow: Folder Operations
-
-```
-HTTP Request (POST /api/folders)
- → FolderService.create_folder()
- → FolderDbRepository.create_folder()
- → INSERT INTO storage.folders (name, parent_id, user_id, ...)
- → 201 Created (FolderDto)
-```
diff --git a/doc/lto-optimizations.md b/doc/lto-optimizations.md
deleted file mode 100644
index 2267eb9d..00000000
--- a/doc/lto-optimizations.md
+++ /dev/null
@@ -1,82 +0,0 @@
-# 05 - LTO Optimizations
-
-OxiCloud uses Link Time Optimization (LTO) to improve runtime performance. LTO allows the compiler to optimize across module boundaries during linking -- better inlining, dead code elimination, and more efficient binaries.
-
----
-
-## Implemented Optimizations
-
-### Release Profile
-```toml
-[profile.release]
-lto = "fat" # Full cross-module optimization
-codegen-units = 1 # Maximum optimization but slower compile time
-opt-level = 3 # Maximum optimization level
-panic = "abort" # Smaller binary size by removing panic unwinding
-strip = true # Removes debug symbols for smaller binary
-```
-
-### Development Profile
-```toml
-[profile.dev]
-opt-level = 1 # Light optimization for faster build time
-debug = true # Keep debug information for development
-```
-
-### Benchmark Profile
-```toml
-[profile.bench]
-lto = "fat" # Full optimization for benchmarks
-codegen-units = 1 # Maximum optimization
-opt-level = 3 # Maximum optimization level
-```
-
----
-
-## Performance Effects
-
-1. **Smaller binary size** -- unused code and metadata removed
-2. **Faster execution** -- better inlining and code optimizations
-3. **Reduced memory usage** -- more efficient code layout
-
----
-
-## LTO Options
-
-- **fat**: Full LTO across all crate boundaries. Maximum optimization, longest compile time.
-- **thin**: Faster LTO that trades some optimization for compile speed. Good for development.
-- **off**: No cross-module optimization.
-
----
-
-## Build Time Impact
-
-LTO increases compilation time. The tradeoff:
-
-- Development builds: minimal LTO (`opt-level = 1`) for faster iteration
-- Release builds: full LTO for maximum runtime performance
-- Benchmark builds: full LTO to measure actual optimized performance
-
----
-
-## Measuring Impact
-
-```bash
-# Run benchmarks with all optimizations
-cargo bench
-
-# Compare with non-optimized build (remove for comparison only)
-RUSTFLAGS="-C lto=off" cargo bench
-```
-
----
-
-## When to Adjust
-
-Consider changing these settings if:
-
-1. You need faster compile times during development
-2. You're experiencing unexpected runtime behavior
-3. You want to experiment with optimization vs. binary size tradeoffs
-
-The defaults work well for most cases.
diff --git a/doc/oidc-architecture.md b/doc/oidc-architecture.md
deleted file mode 100644
index 9539ee44..00000000
--- a/doc/oidc-architecture.md
+++ /dev/null
@@ -1,149 +0,0 @@
-# 29 - OIDC Architecture
-
-OpenID Connect (OIDC) authentication follows the Authorization Code Flow. The system supports multiple identity providers (Authentik, Authelia, KeyCloak) through a single configurable integration point.
-
-## Architecture Diagram
-
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│ │
-│ IDENTITY PROVIDER │
-│ │
-│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
-│ │ │ │ │ │ │ │
-│ │ Authentik │ │ Authelia │ │ KeyCloak │ │
-│ │ │ │ │ │ │ │
-│ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │
-│ │ │ │ │
-└────────────┼──────────────────────┼──────────────────────┼─────────────┘
- │ │ │
- │ │ │
- │ │ │
- │ OIDC │
- │ │ │
- │ │ │
-┌────────────┼──────────────────────┼──────────────────────┼─────────────┐
-│ │ │ │ │
-│ ▼ ▼ ▼ │
-│ ┌───────────────────────────────────────────────────────────────┐ │
-│ │ │ │
-│ │ OXICLOUD │ │
-│ │ │ │
-│ │ ┌───────────────┐ ┌───────────────┐ │ │
-│ │ │ │ │ │ │ │
-│ │ │ OidcService │◄────►│ AuthService │ │ │
-│ │ │ │ │ │ │ │
-│ │ └───────┬───────┘ └───────┬───────┘ │ │
-│ │ │ │ │ │
-│ │ ▼ ▼ │ │
-│ │ ┌───────────────────────────────────────────┐ │ │
-│ │ │ │ │ │
-│ │ │ AuthApplicationService │ │ │
-│ │ │ │ │ │
-│ │ └───────────────────┬───────────────────────┘ │ │
-│ │ │ │ │
-│ │ ▼ │ │
-│ │ ┌───────────────────────────────────────────┐ │ │
-│ │ │ │ │ │
-│ │ │ Auth Handler │ │ │
-│ │ │ │ │ │
-│ │ └───────────────────────────────────────────┘ │ │
-│ │ │ │
-│ └───────────────────────────────────────────────────────────────┘ │
-│ │
-└─────────────────────────────────────────────────────────────────────────┘
- ▲
- │
- │ HTTP/HTTPS
- │
- │
-┌────────────────────────────────────────────────────────────────────────┐
-│ │
-│ WEB BROWSER │
-│ │
-│ ┌───────────────────────────────────────────────────────────────┐ │
-│ │ │ │
-│ │ User Interface │ │
-│ │ │ │
-│ │ ┌──────────────┐ ┌──────────────┐ │ │
-│ │ │ │ │ │ │ │
-│ │ │ Login.html │ │ auth.js │ │ │
-│ │ │ │ │ │ │ │
-│ │ └──────────────┘ └──────────────┘ │ │
-│ │ │ │
-│ └───────────────────────────────────────────────────────────────┘ │
-│ │
-└────────────────────────────────────────────────────────────────────────┘
-```
-
-## OIDC Authentication Flow
-
-The flow follows the standard Authorization Code Flow:
-
-1. **Authentication Start** -- the user clicks "Login with [Provider]" on the login page. The frontend generates a random state for CSRF protection and requests an authorization URL from the backend.
-
-2. **Redirect to Identity Provider** -- the backend generates and returns the authorization URL. The browser redirects the user to the provider's login page.
-
-3. **Authentication at the Provider** -- the user authenticates (password, 2FA, etc.). The provider redirects back with an authorization code.
-
-4. **Authorization Code Exchange** -- the frontend sends the authorization code to the backend. The backend exchanges it for access and ID tokens with the provider, then verifies the ID token and extracts user info.
-
-5. **User Creation/Retrieval** -- the backend looks up an existing user by the provider's external ID. If none exists and auto-provisioning is enabled, a new user is created. If disabled, an error is returned.
-
-6. **Session Token Generation** -- the backend generates its own access and refresh tokens for the user. These tokens authenticate subsequent API requests.
-
-7. **Response to Client** -- tokens and user info are returned to the frontend. The frontend stores them and redirects to the main page.
-
-## Main Components
-
-### OidcService
-
-Handles communication with OIDC providers:
-- Discovers provider OIDC endpoints
-- Generates authorization URLs
-- Exchanges authorization codes for tokens
-- Verifies tokens and extracts user info
-
-### AuthApplicationService
-
-Coordinates the authentication process:
-- Acts as interface between the API layer and domain services
-- Manages user creation/retrieval
-- Coordinates access token generation
-
-### Auth Handler
-
-Exposes HTTP endpoints for the OIDC auth flow:
-- `GET /api/auth/oidc/providers` -- lists available OIDC providers
-- `GET /api/auth/oidc/authorize` -- generates an authorization URL for the OIDC provider
-- `GET /api/auth/oidc/callback` -- receives the redirect from the provider with the authorization code
-- `POST /api/auth/oidc/exchange` -- exchanges the authorization code for session tokens
-
-### Frontend (login.html + auth.js)
-
-Handles the client-side of the auth flow:
-- Shows SSO button for the configured OIDC provider in `login.html`
-- Initiates the authentication flow via `auth.js`
-- Handles the return redirect from the provider
-- Processes and stores session tokens
-
-## Provider Configuration
-
-One OIDC provider is configured per instance via environment variables prefixed with **OXICLOUD_OIDC_***:
-
-1. **Single provider** per instance.
-2. **Environment variables**: **OXICLOUD_OIDC_ENABLED**, **OXICLOUD_OIDC_ISSUER_URL**, **OXICLOUD_OIDC_CLIENT_ID**, **OXICLOUD_OIDC_CLIENT_SECRET**, etc.
-3. **Auto-provisioning**: users can be created automatically on first OIDC login (**OXICLOUD_OIDC_AUTO_PROVISION**).
-4. **Role mapping**: admin groups are configured via **OXICLOUD_OIDC_ADMIN_GROUPS**.
-
-See `oidc-config-examples.md` for provider-specific configuration examples.
-
-## Security
-
-The OIDC implementation includes several security measures:
-
-1. **CSRF protection** -- random state parameter prevents CSRF attacks.
-2. **Token validation** -- JWT signatures and expiration are verified.
-3. **Authorization Code Flow** -- more secure than the implicit flow.
-4. **HTTPS** -- required for all OIDC communications.
-5. **Client secrets** -- stored securely, never exposed to the frontend.
diff --git a/doc/oidc-config-examples.md b/doc/oidc-config-examples.md
deleted file mode 100644
index 788bdfd8..00000000
--- a/doc/oidc-config-examples.md
+++ /dev/null
@@ -1,215 +0,0 @@
-# 31 - OIDC Config Examples
-
-Configuration examples for integrating with different OIDC (OpenID Connect) providers. One OIDC provider per instance.
-
-## Table of Contents
-
-1. [General OIDC Configuration](#general-oidc-configuration)
-2. [Authentik](#authentik)
-3. [Authelia](#authelia)
-4. [KeyCloak](#keycloak)
-5. [Troubleshooting](#troubleshooting)
-
-## General OIDC Configuration
-
-To enable OIDC, set these environment variables:
-
-```bash
-# Enable OIDC
-OXICLOUD_OIDC_ENABLED=true
-
-# OIDC provider configuration
-OXICLOUD_OIDC_PROVIDER_NAME="Display Name"
-OXICLOUD_OIDC_ISSUER_URL="https://provider.example.com/realms/your-realm"
-OXICLOUD_OIDC_CLIENT_ID="your-client-id"
-OXICLOUD_OIDC_CLIENT_SECRET="your-client-secret"
-OXICLOUD_OIDC_REDIRECT_URI="https://your-oxicloud.example.com/api/auth/oidc/callback"
-OXICLOUD_OIDC_SCOPES="openid profile email"
-OXICLOUD_OIDC_FRONTEND_URL="https://your-oxicloud.example.com"
-OXICLOUD_OIDC_AUTO_PROVISION="true"
-OXICLOUD_OIDC_ADMIN_GROUPS="admin-group"
-OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN="false"
-```
-
-## Authentik
-
-[Authentik](https://goauthentik.io/) is an open-source identity platform providing authentication, authorization, and user management.
-
-### 1. Create an Application in Authentik
-
-1. Log into the Authentik admin panel
-2. Go to "Applications" -> "Create"
-3. Enter a name for the application (e.g. "OxiCloud")
-4. Select "OAuth2/OpenID Provider" as the provider type
-5. In the OAuth2 configuration:
- - **Redirect URI/Callback URL**: `https://your-oxicloud.example.com/api/auth/oidc/callback`
- - **Client Type**: Confidential
- - **Client ID**: auto-generated (note it down)
- - **Client Secret**: auto-generated (note it down)
- - **Scopes**: openid, email, profile
-6. In the UI configuration:
- - **Launch URL**: `https://your-oxicloud.example.com/`
- - **Icon**: optional
-
-### 2. Configure for Authentik
-
-```yaml
-# docker-compose.yml
-version: '3'
-services:
- oxicloud:
- image: diocrafts/oxicloud:latest
- environment:
- OXICLOUD_OIDC_ENABLED: "true"
- OXICLOUD_OIDC_PROVIDER_NAME: "Authentik"
- OXICLOUD_OIDC_ISSUER_URL: "https://authentik.example.com/application/o/oxicloud"
- OXICLOUD_OIDC_CLIENT_ID: "your-authentik-client-id"
- OXICLOUD_OIDC_CLIENT_SECRET: "your-authentik-client-secret"
- OXICLOUD_OIDC_REDIRECT_URI: "https://oxicloud.example.com/api/auth/oidc/callback"
- OXICLOUD_OIDC_SCOPES: "openid profile email"
- OXICLOUD_OIDC_FRONTEND_URL: "https://oxicloud.example.com"
- OXICLOUD_OIDC_AUTO_PROVISION: "true"
- OXICLOUD_OIDC_ADMIN_GROUPS: ""
- OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN: "false"
- ports:
- - "8086:8086"
- volumes:
- - ./storage:/app/storage
-```
-
-## Authelia
-
-[Authelia](https://www.authelia.com/) is an open-source multi-factor authentication solution.
-
-### 1. Configure Authelia
-
-Edit your Authelia configuration (`configuration.yml`):
-
-```yaml
-identity_providers:
- oidc:
- hmac_secret: your-secure-secret # Change to a secure random value
- issuer_private_key: /config/private.pem # Path to your private key
- cors:
- endpoints: ['authorization', 'token', 'revocation', 'introspection']
- allowed_origins:
- - https://oxicloud.example.com
- clients:
- - id: oxicloud
- description: OxiCloud
- secret: your-secure-client-secret # Change this
- public: false
- authorization_policy: two_factor
- redirect_uris:
- - https://oxicloud.example.com/api/auth/oidc/callback
- scopes: ['openid', 'profile', 'email', 'groups']
- userinfo_signing_algorithm: none
-```
-
-### 2. Configure for Authelia
-
-```yaml
-# docker-compose.yml
-version: '3'
-services:
- oxicloud:
- image: diocrafts/oxicloud:latest
- environment:
- OXICLOUD_OIDC_ENABLED: "true"
- OXICLOUD_OIDC_PROVIDER_NAME: "Authelia"
- OXICLOUD_OIDC_ISSUER_URL: "https://authelia.example.com"
- OXICLOUD_OIDC_CLIENT_ID: "oxicloud"
- OXICLOUD_OIDC_CLIENT_SECRET: "your-secure-client-secret"
- OXICLOUD_OIDC_REDIRECT_URI: "https://oxicloud.example.com/api/auth/oidc/callback"
- OXICLOUD_OIDC_SCOPES: "openid profile email groups"
- OXICLOUD_OIDC_FRONTEND_URL: "https://oxicloud.example.com"
- OXICLOUD_OIDC_AUTO_PROVISION: "true"
- OXICLOUD_OIDC_ADMIN_GROUPS: ""
- OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN: "false"
- ports:
- - "8086:8086"
- volumes:
- - ./storage:/app/storage
-```
-
-## KeyCloak
-
-[KeyCloak](https://www.keycloak.org/) is an open-source identity and access management solution.
-
-### 1. Create a Client in KeyCloak
-
-1. Log into the KeyCloak admin console
-2. Select your Realm
-3. Go to "Clients" -> "Create"
-4. Fill in the form:
- - **Client ID**: `oxicloud`
- - **Client Protocol**: `openid-connect`
- - **Root URL**: `https://oxicloud.example.com`
-5. In the client configuration:
- - **Access Type**: `confidential`
- - **Valid Redirect URIs**: `https://oxicloud.example.com/api/auth/oidc/callback`
- - **Web Origins**: `https://oxicloud.example.com` (or `+` to allow all origins)
-6. Save the configuration
-7. Go to the "Credentials" tab and copy the generated "Secret"
-
-### 2. Configure for KeyCloak
-
-```yaml
-# docker-compose.yml
-version: '3'
-services:
- oxicloud:
- image: diocrafts/oxicloud:latest
- environment:
- OXICLOUD_OIDC_ENABLED: "true"
- OXICLOUD_OIDC_PROVIDER_NAME: "KeyCloak"
- OXICLOUD_OIDC_ISSUER_URL: "https://keycloak.example.com/realms/your-realm"
- OXICLOUD_OIDC_CLIENT_ID: "oxicloud"
- OXICLOUD_OIDC_CLIENT_SECRET: "your-keycloak-client-secret"
- OXICLOUD_OIDC_REDIRECT_URI: "https://oxicloud.example.com/api/auth/oidc/callback"
- OXICLOUD_OIDC_SCOPES: "openid profile email"
- OXICLOUD_OIDC_FRONTEND_URL: "https://oxicloud.example.com"
- OXICLOUD_OIDC_AUTO_PROVISION: "true"
- OXICLOUD_OIDC_ADMIN_GROUPS: "oxicloud-admins"
- OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN: "false"
- ports:
- - "8086:8086"
- volumes:
- - ./storage:/app/storage
-```
-
-## Troubleshooting
-
-### Error: "Failed to discover OIDC provider"
-
-The backend cannot reach the provider's discovery endpoint.
-
-**Fixes:**
-1. Verify the discovery URL is correct
-2. Check that the backend can reach the URL (firewalls, DNS, etc.)
-3. If using a self-signed certificate, configure the appropriate trust
-
-### Error: "Invalid redirect URI"
-
-The OIDC provider is rejecting the redirect URI.
-
-**Fixes:**
-1. Make sure the redirect URI configured in the backend matches exactly what is registered in the provider
-2. Check for protocol differences (http vs https), port, or path mismatches
-
-### Error: "User does not exist and auto-creation is disabled"
-
-**Fixes:**
-1. Enable auto-provisioning: `OXICLOUD_OIDC_AUTO_PROVISION="true"`
-2. Or manually create the user before attempting OIDC login
-
-### Error: "Could not extract user ID from claim"
-
-The backend cannot find the user ID attribute in the token claims.
-
-**Fixes:**
-1. Verify the provider returns the `sub` claim in tokens
-2. Make sure scopes in **OXICLOUD_OIDC_SCOPES** include `openid`
-3. Configure the provider to include the required claims in tokens
-
-See `oidc-architecture.md` and `oidc-integration.md` for deeper technical details.
diff --git a/doc/oidc-integration.md b/doc/oidc-integration.md
deleted file mode 100644
index cc21c649..00000000
--- a/doc/oidc-integration.md
+++ /dev/null
@@ -1,266 +0,0 @@
-# 30 - OIDC Integration
-
-OpenID Connect (OIDC) is an identity layer on top of OAuth 2.0. It lets clients verify user identity based on authentication performed by an authorization server and obtain basic profile information. Adding OIDC enables SSO with providers like Authentik, Authelia, and KeyCloak.
-
-What it gives us:
-1. Users authenticate with their existing IdP credentials
-2. No need for separate username/password management
-3. Modern auth best practices baked in
-4. Seamless experience for users already on SSO
-
-## OIDC Configuration
-
-OIDC is configured separately from **AuthConfig** via **OidcConfig** in `src/common/config.rs`. This is a single-provider model -- one OIDC provider per instance:
-
-```rust
-/// OpenID Connect (OIDC) configuration
-pub struct OidcConfig {
- pub enabled: bool, // Whether OIDC is enabled
- pub issuer_url: String, // OIDC Issuer URL
- pub client_id: String, // OIDC Client ID
- pub client_secret: String, // OIDC Client Secret
- pub redirect_uri: String, // Redirect URI (default: http://localhost:8086/api/auth/oidc/callback)
- pub scopes: String, // Scopes to request (default: "openid profile email")
- pub frontend_url: String, // Frontend URL for post-login redirect
- pub auto_provision: bool, // Auto-create users on first login (JIT provisioning)
- pub admin_groups: String, // Comma-separated OIDC groups that map to admin role
- pub disable_password_login: bool, // Disable password-based login entirely
- pub provider_name: String, // Display name (default: "SSO")
-}
-```
-
-Environment variables use the **OXICLOUD_OIDC_*** prefix:
-
-```bash
-OXICLOUD_OIDC_ENABLED=true
-OXICLOUD_OIDC_ISSUER_URL="https://authentik.example.com/application/o/oxicloud/"
-OXICLOUD_OIDC_CLIENT_ID="your-client-id"
-OXICLOUD_OIDC_CLIENT_SECRET="your-client-secret"
-OXICLOUD_OIDC_REDIRECT_URI="https://oxicloud.example.com/api/auth/oidc/callback"
-OXICLOUD_OIDC_SCOPES="openid profile email"
-OXICLOUD_OIDC_FRONTEND_URL="https://oxicloud.example.com"
-OXICLOUD_OIDC_AUTO_PROVISION=true
-OXICLOUD_OIDC_ADMIN_GROUPS="oxicloud-admins"
-OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN=false
-OXICLOUD_OIDC_PROVIDER_NAME="Authentik"
-```
-
-## OIDC Service Implementation
-
-The OIDC service lives in the infrastructure layer at `src/infrastructure/services/oidc_service.rs` and implements the **OidcServicePort** trait defined in `src/application/ports/auth_ports.rs`:
-
-```rust
-// src/application/ports/auth_ports.rs — Port trait
-#[async_trait]
-pub trait OidcServicePort: Send + Sync + 'static {
- fn enabled(&self) -> bool;
- fn provider_name(&self) -> &str;
- fn generate_auth_url(&self, state: &str) -> Result
+