Initial commit

backend/src/auth/jwt.rs

@@ -0,0 +1,100 @@
+use anyhow::Result;
+use chrono::{Duration, Utc};
+use jsonwebtoken::{decode, encode, DecodingKey, EncodingKey, Header, Validation};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::config::AppConfig;
+
+#[derive(Clone)]
+pub struct JwtService {
+    encoding: EncodingKey,
+    decoding: DecodingKey,
+    issuer: String,
+    audience: String,
+    expiry: Duration,
+    download_audience: String,
+    download_expiry: Duration,
+}
+
+impl JwtService {
+    pub fn from_config(config: &AppConfig) -> Result<Self> {
+        Ok(Self {
+            encoding: EncodingKey::from_secret(config.jwt_secret.as_bytes()),
+            decoding: DecodingKey::from_secret(config.jwt_secret.as_bytes()),
+            issuer: config.jwt_issuer.clone(),
+            audience: config.jwt_audience.clone(),
+            expiry: Duration::minutes(config.jwt_expiry_minutes),
+            download_audience: config.download_token_audience.clone(),
+            download_expiry: Duration::minutes(config.download_token_expiry_minutes),
+        })
+    }
+
+    pub fn generate_token(&self, user_id: Uuid, username: &str, role: &str) -> Result<String> {
+        let now = Utc::now();
+        let exp = now + self.expiry;
+        let claims = Claims {
+            sub: user_id,
+            username: username.to_owned(),
+            role: role.to_owned(),
+            iss: self.issuer.clone(),
+            aud: self.audience.clone(),
+            iat: now.timestamp() as usize,
+            exp: exp.timestamp() as usize,
+        };
+
+        Ok(encode(&Header::default(), &claims, &self.encoding)?)
+    }
+
+    pub fn verify_token(&self, token: &str) -> Result<Claims> {
+        let mut validation = Validation::default();
+        validation.set_audience(&[self.audience.clone()]);
+        validation.set_issuer(&[self.issuer.clone()]);
+        let data = decode::<Claims>(token, &self.decoding, &validation)?;
+        Ok(data.claims)
+    }
+
+    pub fn generate_download_token(&self, document_id: Uuid, user_id: Uuid) -> Result<String> {
+        let now = Utc::now();
+        let exp = now + self.download_expiry;
+        let claims = DownloadClaims {
+            doc_id: document_id,
+            user_id,
+            iss: self.issuer.clone(),
+            aud: self.download_audience.clone(),
+            iat: now.timestamp() as usize,
+            exp: exp.timestamp() as usize,
+        };
+
+        Ok(encode(&Header::default(), &claims, &self.encoding)?)
+    }
+
+    pub fn verify_download_token(&self, token: &str) -> Result<DownloadClaims> {
+        let mut validation = Validation::default();
+        validation.set_audience(&[self.download_audience.clone()]);
+        validation.set_issuer(&[self.issuer.clone()]);
+        let data = decode::<DownloadClaims>(token, &self.decoding, &validation)?;
+        Ok(data.claims)
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Claims {
+    pub sub: Uuid,
+    pub username: String,
+    pub role: String,
+    pub iss: String,
+    pub aud: String,
+    pub iat: usize,
+    pub exp: usize,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DownloadClaims {
+    pub doc_id: Uuid,
+    pub user_id: Uuid,
+    pub iss: String,
+    pub aud: String,
+    pub iat: usize,
+    pub exp: usize,
+}

backend/src/auth/mod.rs

@@ -0,0 +1,42 @@
+pub mod jwt;
+pub mod password;
+
+use axum::{async_trait, extract::FromRequestParts, http::request::Parts};
+use axum_extra::headers::{authorization::Bearer, Authorization};
+use axum_extra::TypedHeader;
+use serde::{Deserialize, Serialize};
+
+use crate::{error::AppError, state::AppState};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AuthenticatedUser {
+    pub user_id: uuid::Uuid,
+    pub username: String,
+    pub role: String,
+}
+
+#[async_trait]
+impl FromRequestParts<AppState> for AuthenticatedUser {
+    type Rejection = AppError;
+
+    async fn from_request_parts(
+        parts: &mut Parts,
+        state: &AppState,
+    ) -> Result<Self, Self::Rejection> {
+        let TypedHeader(Authorization(bearer)) =
+            TypedHeader::<Authorization<Bearer>>::from_request_parts(parts, state)
+                .await
+                .map_err(|_| AppError::unauthorized())?;
+
+        let claims = state
+            .jwt
+            .verify_token(bearer.token())
+            .map_err(|_| AppError::unauthorized())?;
+
+        Ok(AuthenticatedUser {
+            user_id: claims.sub,
+            username: claims.username,
+            role: claims.role,
+        })
+    }
+}

backend/src/auth/password.rs

@@ -0,0 +1,12 @@
+use anyhow::{anyhow, Result};
+use argon2::{
+    password_hash::{PasswordHash, PasswordVerifier},
+    Argon2,
+};
+
+pub fn verify_password(password: &str, password_hash: &str) -> Result<bool> {
+    let parsed_hash = PasswordHash::new(password_hash).map_err(|err| anyhow!(err))?;
+    Ok(Argon2::default()
+        .verify_password(password.as_bytes(), &parsed_hash)
+        .is_ok())
+}

backend/src/bin/maintenance.rs

@@ -0,0 +1,75 @@
+use std::env;
+
+use anyhow::{Context, Result};
+use diesel::prelude::*;
+
+use backend::{
+    config::AppConfig,
+    db,
+    models::DocumentAsset,
+    s3,
+    schema::document_assets,
+    storage::{ObjectStorage, S3Storage},
+};
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let mut args = env::args().skip(1);
+    match args.next().as_deref() {
+        Some("delete-assets") => delete_all_assets().await?,
+        Some(cmd) => {
+            eprintln!("Unknown command: {cmd}\nUsage: maintenance delete-assets");
+            std::process::exit(1);
+        }
+        None => {
+            eprintln!("Usage: maintenance delete-assets");
+            std::process::exit(1);
+        }
+    }
+
+    Ok(())
+}
+
+async fn delete_all_assets() -> Result<()> {
+    let config = AppConfig::from_env()?;
+    tracing::info!(
+        component = "maintenance",
+        database_url = %config.redacted_database_url(),
+        pool_size = config.database_max_pool_size,
+        s3_bucket = %config.s3_bucket,
+        "loaded backend configuration"
+    );
+    let pool = db::init_pool_with_size(&config.database_url, config.database_max_pool_size)?;
+
+    let s3_client = s3::build_client(&config).await?;
+    let storage = S3Storage::new(s3_client, config.s3_bucket.clone());
+
+    let mut conn = pool.get().context("failed to get database connection")?;
+
+    let assets: Vec<DocumentAsset> = document_assets::table
+        .load(&mut conn)
+        .context("failed to load document assets")?;
+
+    if assets.is_empty() {
+        println!("No assets found.");
+        return Ok(());
+    }
+
+    println!("Deleting {} assets…", assets.len());
+
+    for asset in &assets {
+        if let Err(err) = storage.delete_object(&asset.s3_key).await {
+            eprintln!(
+                "Failed to delete object {} from storage: {err}",
+                asset.s3_key
+            );
+        }
+    }
+
+    diesel::delete(document_assets::table)
+        .execute(&mut conn)
+        .context("failed to remove asset records")?;
+
+    println!("Asset records deleted.");
+    Ok(())
+}

backend/src/bin/webdav.rs

@@ -0,0 +1,60 @@
+use std::net::SocketAddr;
+use std::sync::Arc;
+
+use tokio::net::TcpListener;
+use tower::make::Shared;
+use tracing_subscriber::EnvFilter;
+
+use backend::auth::jwt::JwtService;
+use backend::config::AppConfig;
+use backend::db;
+use backend::routes::webdav;
+use backend::s3::build_client;
+use backend::state::AppState;
+use backend::storage::S3Storage;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    dotenv::dotenv().ok();
+    init_tracing();
+
+    let config = AppConfig::from_env()?;
+    tracing::info!(
+        component = "webdav",
+        database_url = %config.redacted_database_url(),
+        pool_size = config.database_max_pool_size,
+        server_host = %config.server_host,
+        server_port = config.server_port,
+        webdav_host = %config.webdav_host,
+        webdav_port = config.webdav_port,
+        quickwit_enabled = config.quickwit_endpoint.is_some(),
+        s3_bucket = %config.s3_bucket,
+        "loaded backend configuration"
+    );
+    let pool = db::init_pool_with_size(&config.database_url, config.database_max_pool_size)?;
+    let s3_client = build_client(&config).await?;
+    let storage = Arc::new(S3Storage::new(s3_client, config.s3_bucket.clone()));
+    let jwt = JwtService::from_config(&config)?;
+
+    let state = AppState::new(pool, config, storage, jwt);
+    let listen_addr: SocketAddr = {
+        let config = state.config.clone();
+        format!("{}:{}", config.webdav_host, config.webdav_port).parse()?
+    };
+    let router = webdav::create_router().with_state(state);
+
+    let listener = TcpListener::bind(listen_addr).await?;
+    tracing::info!("listening for WebDAV on {}", listen_addr);
+
+    axum::serve(listener, Shared::new(router)).await?;
+    Ok(())
+}
+
+fn init_tracing() {
+    let filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info"));
+    tracing_subscriber::fmt()
+        .with_env_filter(filter)
+        .with_target(false)
+        .compact()
+        .init();
+}

backend/src/bin/worker.rs

@@ -0,0 +1,50 @@
+use std::{sync::Arc, time::Duration};
+
+use tokio::signal;
+use tracing_subscriber::EnvFilter;
+
+use backend::{
+    auth::jwt::JwtService, config::AppConfig, db, default_handlers, s3::build_client,
+    state::AppState, storage::S3Storage, Worker,
+};
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    dotenv::dotenv().ok();
+    init_tracing();
+
+    let config = AppConfig::from_env()?;
+    tracing::info!(
+        component = "worker",
+        database_url = %config.redacted_database_url(),
+        pool_size = 1,
+        quickwit_enabled = config.quickwit_endpoint.is_some(),
+        s3_bucket = %config.s3_bucket,
+        "loaded backend configuration"
+    );
+    let pool = db::init_pool_with_size(&config.database_url, 1)?;
+    let s3_client = build_client(&config).await?;
+    let storage = Arc::new(S3Storage::new(s3_client, config.s3_bucket.clone()));
+    let jwt = JwtService::from_config(&config)?;
+
+    let state = Arc::new(AppState::new(pool, config, storage, jwt));
+    let worker = Worker::new(state, default_handlers(), Duration::from_secs(2));
+
+    tokio::select! {
+        _ = worker.run() => {}
+        _ = signal::ctrl_c() => {
+            tracing::info!("worker received shutdown signal");
+        }
+    }
+
+    Ok(())
+}
+
+fn init_tracing() {
+    let filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info"));
+    tracing_subscriber::fmt()
+        .with_env_filter(filter)
+        .with_target(false)
+        .compact()
+        .init();
+}

backend/src/config.rs

@@ -0,0 +1,147 @@
+use std::env;
+
+use anyhow::{Context, Result};
+use url::Url;
+
+use crate::db::DEFAULT_MAX_POOL_SIZE;
+
+#[derive(Clone, Debug)]
+pub struct AppConfig {
+    pub database_url: String,
+    pub database_max_pool_size: u32,
+    pub server_host: String,
+    pub server_port: u16,
+    pub webdav_host: String,
+    pub webdav_port: u16,
+    pub jwt_secret: String,
+    pub jwt_issuer: String,
+    pub jwt_audience: String,
+    pub jwt_expiry_minutes: i64,
+    pub download_token_audience: String,
+    pub download_token_expiry_minutes: i64,
+    pub refresh_token_expiry_days: i64,
+    pub refresh_cookie_secure: bool,
+    pub refresh_cookie_domain: Option<String>,
+    pub cors_allowed_origin: Option<String>,
+    pub aws_endpoint_url: Option<String>,
+    pub aws_access_key_id: Option<String>,
+    pub aws_secret_access_key: Option<String>,
+    pub aws_region: String,
+    pub s3_bucket: String,
+    pub quickwit_endpoint: Option<String>,
+    pub quickwit_index: Option<String>,
+}
+
+impl AppConfig {
+    pub fn from_env() -> Result<Self> {
+        let database_url = env::var("DATABASE_URL").context("DATABASE_URL must be set")?;
+        let database_max_pool_size = env::var("DATABASE_MAX_POOL_SIZE")
+            .ok()
+            .and_then(|value| value.parse().ok())
+            .unwrap_or(DEFAULT_MAX_POOL_SIZE);
+        let server_host = env::var("SERVER_HOST").unwrap_or_else(|_| "127.0.0.1".to_string());
+        let server_port = env::var("SERVER_PORT")
+            .unwrap_or_else(|_| "3000".to_string())
+            .parse()
+            .context("SERVER_PORT must be a valid u16")?;
+        let webdav_host = env::var("WEBDAV_HOST").unwrap_or_else(|_| server_host.clone());
+        let webdav_port = env::var("WEBDAV_PORT")
+            .unwrap_or_else(|_| "3001".to_string())
+            .parse()
+            .context("WEBDAV_PORT must be a valid u16")?;
+        let jwt_secret = env::var("JWT_SECRET").context("JWT_SECRET must be set")?;
+        let jwt_issuer = env::var("JWT_ISSUER").unwrap_or_else(|_| "papercrate".to_string());
+        let jwt_audience =
+            env::var("JWT_AUDIENCE").unwrap_or_else(|_| "papercrate-clients".to_string());
+        let jwt_expiry_minutes = env::var("JWT_EXPIRY_MINUTES")
+            .unwrap_or_else(|_| "60".to_string())
+            .parse()
+            .context("JWT_EXPIRY_MINUTES must be an integer")?;
+        let download_token_audience = env::var("DOWNLOAD_TOKEN_AUDIENCE")
+            .unwrap_or_else(|_| "papercrate-download".to_string());
+        let download_token_expiry_minutes = env::var("DOWNLOAD_TOKEN_EXPIRY_MINUTES")
+            .unwrap_or_else(|_| "60".to_string())
+            .parse()
+            .context("DOWNLOAD_TOKEN_EXPIRY_MINUTES must be an integer")?;
+        let refresh_token_expiry_days = env::var("REFRESH_TOKEN_EXPIRY_DAYS")
+            .unwrap_or_else(|_| "30".to_string())
+            .parse()
+            .context("REFRESH_TOKEN_EXPIRY_DAYS must be an integer")?;
+        let refresh_cookie_secure = env::var("REFRESH_COOKIE_SECURE")
+            .map(|v| v == "1" || v.eq_ignore_ascii_case("true"))
+            .unwrap_or(false);
+        let refresh_cookie_domain = env::var("REFRESH_COOKIE_DOMAIN").ok();
+        let cors_allowed_origin = env::var("CORS_ALLOWED_ORIGIN").ok();
+        let aws_endpoint_url = env::var("AWS_ENDPOINT_URL").ok();
+        let aws_access_key_id = env::var("AWS_ACCESS_KEY_ID").ok();
+        let aws_secret_access_key = env::var("AWS_SECRET_ACCESS_KEY").ok();
+        let aws_region = env::var("AWS_REGION").unwrap_or_else(|_| "us-east-1".to_string());
+        let s3_bucket = env::var("S3_BUCKET").context("S3_BUCKET must be set")?;
+        let quickwit_endpoint = env::var("QUICKWIT_ENDPOINT").ok();
+        let quickwit_index = env::var("QUICKWIT_INDEX").ok();
+
+        Ok(Self {
+            database_url,
+            database_max_pool_size,
+            server_host,
+            server_port,
+            webdav_host,
+            webdav_port,
+            jwt_secret,
+            jwt_issuer,
+            jwt_audience,
+            jwt_expiry_minutes,
+            download_token_audience,
+            download_token_expiry_minutes,
+            refresh_token_expiry_days,
+            refresh_cookie_secure,
+            refresh_cookie_domain,
+            cors_allowed_origin,
+            aws_endpoint_url,
+            aws_access_key_id,
+            aws_secret_access_key,
+            aws_region,
+            s3_bucket,
+            quickwit_endpoint,
+            quickwit_index,
+        })
+    }
+
+    pub fn redacted_database_url(&self) -> String {
+        redact_database_url(&self.database_url)
+    }
+}
+
+fn redact_database_url(raw: &str) -> String {
+    match Url::parse(raw) {
+        Ok(mut parsed) => {
+            let _ = parsed.set_password(Some("*****"));
+            parsed.to_string()
+        }
+        Err(_) => "***".to_string(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::redact_database_url;
+
+    #[test]
+    fn redacts_password_in_database_url() {
+        let redacted = redact_database_url("postgres://user:secret@localhost/db");
+        assert!(redacted.contains("postgres://user:*****@"));
+        assert!(!redacted.contains("secret"));
+    }
+
+    #[test]
+    fn handles_url_without_password() {
+        let redacted = redact_database_url("postgres://localhost/db");
+        assert_eq!(redacted, "postgres://localhost/db");
+    }
+
+    #[test]
+    fn falls_back_when_parse_fails() {
+        let redacted = redact_database_url("not a url");
+        assert_eq!(redacted, "***");
+    }
+}

backend/src/db.rs

@@ -0,0 +1,22 @@
+use std::time::Duration;
+
+use diesel::pg::PgConnection;
+use diesel::r2d2::{ConnectionManager, Pool};
+
+pub type PgPool = Pool<ConnectionManager<PgConnection>>;
+
+pub const DEFAULT_MAX_POOL_SIZE: u32 = 2;
+
+pub fn init_pool(database_url: &str) -> anyhow::Result<PgPool> {
+    init_pool_with_size(database_url, DEFAULT_MAX_POOL_SIZE)
+}
+
+pub fn init_pool_with_size(database_url: &str, max_size: u32) -> anyhow::Result<PgPool> {
+    let manager = ConnectionManager::<PgConnection>::new(database_url);
+    let pool_size = max_size.max(1);
+    let pool = Pool::builder()
+        .max_size(pool_size)
+        .connection_timeout(Duration::from_secs(10))
+        .build(manager)?;
+    Ok(pool)
+}

backend/src/error.rs

@@ -0,0 +1,88 @@
+use axum::{
+    http::StatusCode,
+    response::{IntoResponse, Response},
+    Json,
+};
+use serde::Serialize;
+use std::fmt::Display;
+
+pub type AppResult<T> = Result<T, AppError>;
+
+#[derive(Debug)]
+pub struct AppError {
+    status: StatusCode,
+    message: String,
+}
+
+impl AppError {
+    pub fn new(status: StatusCode, message: impl Into<String>) -> Self {
+        Self {
+            status,
+            message: message.into(),
+        }
+    }
+
+    pub fn bad_request(message: impl Into<String>) -> Self {
+        Self::new(StatusCode::BAD_REQUEST, message)
+    }
+
+    pub fn unauthorized() -> Self {
+        Self::new(StatusCode::UNAUTHORIZED, "unauthorized")
+    }
+
+    pub fn not_found() -> Self {
+        Self::new(StatusCode::NOT_FOUND, "resource not found")
+    }
+
+    pub fn internal<E: Display>(error: E) -> Self {
+        Self::new(StatusCode::INTERNAL_SERVER_ERROR, error.to_string())
+    }
+}
+
+impl IntoResponse for AppError {
+    fn into_response(self) -> Response {
+        let status = self.status;
+        let body = Json(ErrorResponse {
+            error: self.message,
+        });
+        (status, body).into_response()
+    }
+}
+
+#[derive(Serialize)]
+struct ErrorResponse {
+    error: String,
+}
+
+impl From<diesel::result::Error> for AppError {
+    fn from(value: diesel::result::Error) -> Self {
+        match value {
+            diesel::result::Error::NotFound => AppError::not_found(),
+            _ => AppError::internal(value),
+        }
+    }
+}
+
+impl From<jsonwebtoken::errors::Error> for AppError {
+    fn from(value: jsonwebtoken::errors::Error) -> Self {
+        AppError::internal(value)
+    }
+}
+
+impl From<anyhow::Error> for AppError {
+    fn from(value: anyhow::Error) -> Self {
+        AppError::internal(value)
+    }
+}
+
+impl From<std::io::Error> for AppError {
+    fn from(value: std::io::Error) -> Self {
+        AppError::internal(value)
+    }
+}
+
+impl From<serde_json::Error> for AppError {
+    fn from(value: serde_json::Error) -> Self {
+        AppError::internal(value)
+    }
+}

backend/src/jobs.rs

@@ -0,0 +1,129 @@
+use std::time::Duration;
+
+use chrono::{Duration as ChronoDuration, NaiveDateTime, Utc};
+use diesel::pg::PgConnection;
+use diesel::prelude::*;
+use serde_json::Value;
+use thiserror::Error;
+use uuid::Uuid;
+
+use crate::models::{Job, NewJob};
+use crate::schema::jobs;
+
+pub const STATUS_QUEUED: &str = "queued";
+pub const STATUS_PROCESSING: &str = "processing";
+pub const STATUS_SUCCEEDED: &str = "succeeded";
+pub const STATUS_FAILED: &str = "failed";
+
+pub const JOB_ANALYZE_DOCUMENT: &str = "analyze-document";
+pub const JOB_GENERATE_THUMBNAILS: &str = "generate-thumbnails";
+pub const JOB_GENERATE_OCR_TEXT: &str = "generate-ocr-text";
+pub const JOB_INDEX_DOCUMENT_TEXT: &str = "index-document-text";
+
+#[derive(Debug, Error)]
+pub enum JobQueueError {
+    #[error("database error: {0}")]
+    Database(#[from] diesel::result::Error),
+}
+
+pub type JobQueueResult<T> = Result<T, JobQueueError>;
+
+pub fn enqueue_job(
+    conn: &mut PgConnection,
+    job_type: &str,
+    payload: Value,
+    run_after: Option<NaiveDateTime>,
+) -> JobQueueResult<Job> {
+    let new_job = NewJob {
+        id: Uuid::new_v4(),
+        job_type: job_type.to_string(),
+        payload,
+        status: STATUS_QUEUED.to_string(),
+        run_after: run_after.unwrap_or_else(|| Utc::now().naive_utc()),
+    };
+
+    diesel::insert_into(jobs::table)
+        .values(&new_job)
+        .execute(conn)?;
+
+    let job = jobs::table.find(new_job.id).first(conn)?;
+    Ok(job)
+}
+
+pub fn reserve_job(conn: &mut PgConnection, job_types: &[&str]) -> JobQueueResult<Option<Job>> {
+    let now = Utc::now().naive_utc();
+
+    conn.transaction(|conn| {
+        let job_opt = jobs::table
+            .filter(jobs::status.eq(STATUS_QUEUED))
+            .filter(jobs::run_after.le(now))
+            .filter(jobs::job_type.eq_any(job_types))
+            .order(jobs::run_after.asc())
+            .for_update()
+            .skip_locked()
+            .first::<Job>(conn)
+            .optional()?;
+
+        if let Some(job) = job_opt {
+            diesel::update(jobs::table.find(job.id))
+                .set((
+                    jobs::status.eq(STATUS_PROCESSING),
+                    jobs::attempts.eq(job.attempts + 1),
+                    jobs::updated_at.eq(now),
+                ))
+                .execute(conn)?;
+
+            let refreshed = jobs::table.find(job.id).first(conn)?;
+            Ok::<Option<Job>, diesel::result::Error>(Some(refreshed))
+        } else {
+            Ok::<Option<Job>, diesel::result::Error>(None)
+        }
+    })
+    .map_err(JobQueueError::from)
+}
+
+pub fn mark_job_succeeded(conn: &mut PgConnection, job_id: Uuid) -> JobQueueResult<()> {
+    diesel::update(jobs::table.find(job_id))
+        .set((
+            jobs::status.eq(STATUS_SUCCEEDED),
+            jobs::last_error.eq::<Option<String>>(None),
+            jobs::updated_at.eq(Utc::now().naive_utc()),
+        ))
+        .execute(conn)?;
+    Ok(())
+}
+
+pub fn retry_job_after(
+    conn: &mut PgConnection,
+    job_id: Uuid,
+    delay: Duration,
+    error_message: &str,
+) -> JobQueueResult<()> {
+    let next_run = Utc::now()
+        + ChronoDuration::from_std(delay).unwrap_or_else(|_| ChronoDuration::seconds(30));
+
+    diesel::update(jobs::table.find(job_id))
+        .set((
+            jobs::status.eq(STATUS_QUEUED),
+            jobs::run_after.eq(next_run.naive_utc()),
+            jobs::last_error.eq(Some(error_message.to_string())),
+            jobs::updated_at.eq(Utc::now().naive_utc()),
+        ))
+        .execute(conn)?;
+    Ok(())
+}
+
+pub fn mark_job_failed(
+    conn: &mut PgConnection,
+    job_id: Uuid,
+    error_message: &str,
+) -> JobQueueResult<()> {
+    diesel::update(jobs::table.find(job_id))
+        .set((
+            jobs::status.eq(STATUS_FAILED),
+            jobs::last_error.eq(Some(error_message.to_string())),
+            jobs::updated_at.eq(Utc::now().naive_utc()),
+        ))
+        .execute(conn)?;
+    Ok(())
+}

backend/src/lib.rs

@@ -0,0 +1,14 @@
+pub mod auth;
+pub mod config;
+pub mod db;
+pub mod error;
+pub mod jobs;
+pub mod models;
+pub mod routes;
+pub mod s3;
+pub mod schema;
+pub mod state;
+pub mod storage;
+pub mod utils;
+pub mod workers;
+pub use workers::{default_handlers, Worker};

backend/src/main.rs

@@ -0,0 +1,57 @@
+use std::net::SocketAddr;
+use std::sync::Arc;
+
+use tokio::net::TcpListener;
+use tower::make::Shared;
+use tracing_subscriber::EnvFilter;
+
+use backend::auth::jwt::JwtService;
+use backend::config::AppConfig;
+use backend::db;
+use backend::routes;
+use backend::s3::build_client;
+use backend::state::AppState;
+use backend::storage::S3Storage;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    dotenv::dotenv().ok();
+    init_tracing();
+
+    let config = AppConfig::from_env()?;
+    tracing::info!(
+        component = "api",
+        database_url = %config.redacted_database_url(),
+        pool_size = config.database_max_pool_size,
+        server_host = %config.server_host,
+        server_port = config.server_port,
+        quickwit_enabled = config.quickwit_endpoint.is_some(),
+        s3_bucket = %config.s3_bucket,
+        "loaded backend configuration"
+    );
+    let pool = db::init_pool_with_size(&config.database_url, config.database_max_pool_size)?;
+    let s3_client = build_client(&config).await?;
+    let storage = Arc::new(S3Storage::new(s3_client, config.s3_bucket.clone()));
+    let jwt = JwtService::from_config(&config)?;
+
+    let state = AppState::new(pool, config, storage, jwt);
+
+    let router = routes::create_router(state.clone());
+
+    let addr: SocketAddr =
+        format!("{}:{}", state.config.server_host, state.config.server_port).parse()?;
+    let listener = TcpListener::bind(addr).await?;
+    tracing::info!("listening on {}", addr);
+
+    axum::serve(listener, Shared::new(router)).await?;
+    Ok(())
+}
+
+fn init_tracing() {
+    let filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info"));
+    tracing_subscriber::fmt()
+        .with_env_filter(filter)
+        .with_target(false)
+        .compact()
+        .init();
+}

backend/src/models.rs

@@ -0,0 +1,253 @@
+use chrono::NaiveDateTime;
+use diesel::prelude::*;
+use uuid::Uuid;
+
+use crate::schema::*;
+
+#[derive(Debug, Clone, Queryable, Identifiable)]
+#[diesel(table_name = users)]
+pub struct User {
+    pub id: Uuid,
+    pub username: String,
+    pub password_hash: String,
+    pub role: String,
+    pub created_at: NaiveDateTime,
+    pub updated_at: NaiveDateTime,
+}
+
+#[derive(Debug, Insertable)]
+#[diesel(table_name = users)]
+pub struct NewUser {
+    pub id: Uuid,
+    pub username: String,
+    pub password_hash: String,
+    pub role: String,
+}
+
+#[derive(Debug, Clone, Queryable, Identifiable)]
+#[diesel(table_name = folders)]
+pub struct Folder {
+    pub id: Uuid,
+    pub name: String,
+    pub parent_id: Option<Uuid>,
+    pub created_at: NaiveDateTime,
+    pub updated_at: NaiveDateTime,
+}
+
+#[derive(Debug, Insertable)]
+#[diesel(table_name = folders)]
+pub struct NewFolder {
+    pub id: Uuid,
+    pub name: String,
+    pub parent_id: Option<Uuid>,
+}
+
+#[derive(Debug, Clone, Queryable, Identifiable, Associations)]
+#[diesel(table_name = documents)]
+#[diesel(belongs_to(Folder, foreign_key = folder_id))]
+pub struct Document {
+    pub id: Uuid,
+    pub filename: String,
+    pub original_name: String,
+    pub content_type: Option<String>,
+    pub folder_id: Option<Uuid>,
+    pub uploaded_at: NaiveDateTime,
+    pub updated_at: NaiveDateTime,
+    pub deleted_at: Option<NaiveDateTime>,
+    pub metadata: serde_json::Value,
+    pub issued_at: Option<NaiveDateTime>,
+    pub title: String,
+    pub current_version_id: Uuid,
+}
+
+#[derive(Debug, Insertable)]
+#[diesel(table_name = documents)]
+pub struct NewDocument {
+    pub id: Uuid,
+    pub filename: String,
+    pub original_name: String,
+    pub content_type: Option<String>,
+    pub folder_id: Option<Uuid>,
+    pub current_version_id: Uuid,
+    pub metadata: serde_json::Value,
+    pub issued_at: Option<NaiveDateTime>,
+    pub title: String,
+}
+
+#[derive(Debug, Clone, Queryable, Identifiable, Associations)]
+#[diesel(table_name = document_versions)]
+#[diesel(belongs_to(Document))]
+pub struct DocumentVersion {
+    pub id: Uuid,
+    pub document_id: Uuid,
+    pub version_number: i32,
+    pub s3_key: String,
+    pub size_bytes: i64,
+    pub checksum: String,
+    pub created_at: NaiveDateTime,
+    pub operations_summary: serde_json::Value,
+    pub metadata: serde_json::Value,
+}
+
+#[derive(Debug, Insertable)]
+#[diesel(table_name = document_versions)]
+pub struct NewDocumentVersion {
+    pub id: Uuid,
+    pub document_id: Uuid,
+    pub version_number: i32,
+    pub s3_key: String,
+    pub size_bytes: i64,
+    pub checksum: String,
+    pub operations_summary: serde_json::Value,
+    pub metadata: serde_json::Value,
+}
+
+#[derive(Debug, Clone, Queryable, Identifiable, Associations)]
+#[diesel(table_name = document_assets)]
+#[diesel(belongs_to(DocumentVersion, foreign_key = document_version_id))]
+pub struct DocumentAsset {
+    pub id: Uuid,
+    pub document_version_id: Uuid,
+    pub asset_type: String,
+    pub s3_key: String,
+    pub mime_type: String,
+    pub metadata: serde_json::Value,
+    pub created_at: NaiveDateTime,
+}
+
+#[derive(Debug, Insertable)]
+#[diesel(table_name = document_assets)]
+pub struct NewDocumentAsset {
+    pub id: Uuid,
+    pub document_version_id: Uuid,
+    pub asset_type: String,
+    pub s3_key: String,
+    pub mime_type: String,
+    pub metadata: serde_json::Value,
+}
+
+#[derive(Debug, Clone, Queryable, Identifiable)]
+#[diesel(table_name = jobs)]
+pub struct Job {
+    pub id: Uuid,
+    pub job_type: String,
+    pub payload: serde_json::Value,
+    pub status: String,
+    pub attempts: i32,
+    pub run_after: NaiveDateTime,
+    pub last_error: Option<String>,
+    pub created_at: NaiveDateTime,
+    pub updated_at: NaiveDateTime,
+}
+
+#[derive(Debug, Insertable)]
+#[diesel(table_name = jobs)]
+pub struct NewJob {
+    pub id: Uuid,
+    pub job_type: String,
+    pub payload: serde_json::Value,
+    pub status: String,
+    pub run_after: NaiveDateTime,
+}
+
+#[derive(Debug, Clone, Queryable, Identifiable)]
+#[diesel(table_name = tags)]
+pub struct Tag {
+    pub id: Uuid,
+    pub label: String,
+    pub color: Option<String>,
+    pub created_at: NaiveDateTime,
+}
+
+#[derive(Debug, Insertable)]
+#[diesel(table_name = tags)]
+pub struct NewTag {
+    pub id: Uuid,
+    pub label: String,
+    pub color: Option<String>,
+}
+
+#[allow(dead_code)]
+#[derive(Debug, Clone, Queryable, Associations)]
+#[diesel(table_name = document_tags)]
+#[diesel(belongs_to(Document))]
+#[diesel(belongs_to(Tag))]
+#[diesel(primary_key(document_id, tag_id))]
+pub struct DocumentTag {
+    pub document_id: Uuid,
+    pub tag_id: Uuid,
+    pub assigned_at: NaiveDateTime,
+    pub assigned_by: Option<Uuid>,
+}
+
+#[derive(Debug, Insertable)]
+#[diesel(table_name = document_tags)]
+pub struct NewDocumentTag {
+    pub document_id: Uuid,
+    pub tag_id: Uuid,
+    pub assigned_by: Option<Uuid>,
+}
+
+#[derive(Debug, Clone, Queryable, Identifiable)]
+#[diesel(table_name = correspondents)]
+pub struct Correspondent {
+    pub id: Uuid,
+    pub name: String,
+    pub metadata: serde_json::Value,
+    pub created_at: NaiveDateTime,
+    pub updated_at: NaiveDateTime,
+}
+
+#[derive(Debug, Insertable)]
+#[diesel(table_name = correspondents)]
+pub struct NewCorrespondent {
+    pub id: Uuid,
+    pub name: String,
+    pub metadata: serde_json::Value,
+}
+
+#[derive(Debug, Clone, Queryable, Associations)]
+#[diesel(table_name = document_correspondents)]
+#[diesel(belongs_to(Document))]
+#[diesel(belongs_to(Correspondent))]
+#[diesel(primary_key(document_id, correspondent_id, role))]
+pub struct DocumentCorrespondent {
+    pub document_id: Uuid,
+    pub correspondent_id: Uuid,
+    pub role: String,
+    pub assigned_at: NaiveDateTime,
+    pub assigned_by: Option<Uuid>,
+}
+
+#[derive(Debug, Insertable)]
+#[diesel(table_name = document_correspondents)]
+pub struct NewDocumentCorrespondent {
+    pub document_id: Uuid,
+    pub correspondent_id: Uuid,
+    pub role: String,
+    pub assigned_by: Option<Uuid>,
+}
+
+#[derive(Debug, Clone, Queryable, Identifiable, Associations)]
+#[diesel(table_name = refresh_tokens)]
+#[diesel(belongs_to(User))]
+pub struct RefreshToken {
+    pub id: Uuid,
+    pub user_id: Uuid,
+    pub token_hash: String,
+    pub issued_at: NaiveDateTime,
+    pub expires_at: NaiveDateTime,
+    pub revoked_at: Option<NaiveDateTime>,
+    pub created_at: NaiveDateTime,
+    pub updated_at: NaiveDateTime,
+}
+
+#[derive(Debug, Insertable)]
+#[diesel(table_name = refresh_tokens)]
+pub struct NewRefreshToken {
+    pub id: Uuid,
+    pub user_id: Uuid,
+    pub token_hash: String,
+    pub issued_at: NaiveDateTime,
+    pub expires_at: NaiveDateTime,
+}

backend/src/routes/auth.rs

@@ -0,0 +1,267 @@
+use axum::{
+    extract::State,
+    http::{header::SET_COOKIE, HeaderMap, HeaderValue, StatusCode},
+    Json,
+};
+use axum_extra::{headers::Cookie, typed_header::TypedHeader};
+use chrono::{Duration as ChronoDuration, Utc};
+use diesel::prelude::*;
+use rand::{rngs::OsRng, RngCore};
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use uuid::Uuid;
+
+use crate::{
+    auth::{password, AuthenticatedUser},
+    error::{AppError, AppResult},
+    models::{NewRefreshToken, RefreshToken, User},
+    schema::{refresh_tokens, users::dsl},
+    state::AppState,
+};
+
+use crate::schema::refresh_tokens::dsl as refresh_dsl;
+
+const REFRESH_COOKIE_NAME: &str = "refresh_token";
+
+#[derive(Deserialize)]
+pub struct LoginRequest {
+    pub username: String,
+    pub password: String,
+}
+
+#[derive(Serialize)]
+pub struct LoginResponse {
+    pub access_token: String,
+    pub token_type: String,
+    pub expires_in: i64,
+}
+
+pub async fn login(
+    State(state): State<AppState>,
+    Json(payload): Json<LoginRequest>,
+) -> AppResult<(HeaderMap, Json<LoginResponse>)> {
+    let mut conn = state.db()?;
+
+    let user: User = dsl::users
+        .filter(dsl::username.eq(&payload.username))
+        .first(&mut conn)?;
+
+    let valid = password::verify_password(&payload.password, &user.password_hash)
+        .map_err(|_| AppError::unauthorized())?;
+
+    if !valid {
+        return Err(AppError::unauthorized());
+    }
+
+    let access_token = state
+        .jwt
+        .generate_token(user.id, &user.username, &user.role)
+        .map_err(AppError::from)?;
+
+    let now = Utc::now();
+    let refresh_value = generate_refresh_token();
+    let refresh_hash = hash_refresh_token(&refresh_value);
+    let refresh_expires_at = now + ChronoDuration::days(state.config.refresh_token_expiry_days);
+
+    let new_refresh = NewRefreshToken {
+        id: Uuid::new_v4(),
+        user_id: user.id,
+        token_hash: refresh_hash,
+        issued_at: now.naive_utc(),
+        expires_at: refresh_expires_at.naive_utc(),
+    };
+
+    diesel::insert_into(refresh_tokens::table)
+        .values(&new_refresh)
+        .execute(&mut conn)?;
+
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        SET_COOKIE,
+        build_refresh_cookie(&state, &refresh_value, refresh_expires_at),
+    );
+
+    Ok((
+        headers,
+        Json(LoginResponse {
+            access_token,
+            token_type: "Bearer".to_string(),
+            expires_in: state.config.jwt_expiry_minutes * 60,
+        }),
+    ))
+}
+
+pub async fn refresh(
+    State(state): State<AppState>,
+    jar: Option<TypedHeader<Cookie>>,
+) -> AppResult<(HeaderMap, Json<LoginResponse>)> {
+    let cookies = jar.ok_or_else(AppError::unauthorized)?;
+    let refresh_value = cookies
+        .get(REFRESH_COOKIE_NAME)
+        .ok_or_else(AppError::unauthorized)?;
+
+    let hashed = hash_refresh_token(refresh_value);
+    let mut conn = state.db()?;
+    let now = Utc::now();
+    let now_naive = now.naive_utc();
+
+    let token = match refresh_dsl::refresh_tokens
+        .filter(refresh_dsl::token_hash.eq(&hashed))
+        .filter(refresh_dsl::revoked_at.is_null())
+        .filter(refresh_dsl::expires_at.gt(now_naive))
+        .first::<RefreshToken>(&mut conn)
+    {
+        Ok(token) => token,
+        Err(diesel::result::Error::NotFound) => return Err(AppError::unauthorized()),
+        Err(err) => return Err(AppError::from(err)),
+    };
+
+    diesel::update(refresh_dsl::refresh_tokens.filter(refresh_dsl::id.eq(token.id)))
+        .set((
+            refresh_dsl::revoked_at.eq(now_naive),
+            refresh_dsl::updated_at.eq(now_naive),
+        ))
+        .execute(&mut conn)?;
+
+    let user: User = dsl::users
+        .find(token.user_id)
+        .first(&mut conn)
+        .map_err(AppError::from)?;
+
+    let access_token = state
+        .jwt
+        .generate_token(user.id, &user.username, &user.role)
+        .map_err(AppError::from)?;
+
+    let new_refresh_value = generate_refresh_token();
+    let new_refresh_hash = hash_refresh_token(&new_refresh_value);
+    let new_refresh_expires = now + ChronoDuration::days(state.config.refresh_token_expiry_days);
+
+    let new_refresh = NewRefreshToken {
+        id: Uuid::new_v4(),
+        user_id: user.id,
+        token_hash: new_refresh_hash,
+        issued_at: now_naive,
+        expires_at: new_refresh_expires.naive_utc(),
+    };
+
+    diesel::insert_into(refresh_tokens::table)
+        .values(&new_refresh)
+        .execute(&mut conn)?;
+
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        SET_COOKIE,
+        build_refresh_cookie(&state, &new_refresh_value, new_refresh_expires),
+    );
+
+    Ok((
+        headers,
+        Json(LoginResponse {
+            access_token,
+            token_type: "Bearer".to_string(),
+            expires_in: state.config.jwt_expiry_minutes * 60,
+        }),
+    ))
+}
+
+pub async fn logout(
+    State(state): State<AppState>,
+    user: AuthenticatedUser,
+    jar: Option<TypedHeader<Cookie>>,
+) -> AppResult<(HeaderMap, StatusCode)> {
+    let mut conn = state.db()?;
+    let now = Utc::now().naive_utc();
+    let mut rows_affected = 0;
+
+    if let Some(cookies) = jar {
+        if let Some(value) = cookies.get(REFRESH_COOKIE_NAME) {
+            let hashed = hash_refresh_token(value);
+            rows_affected = diesel::update(
+                refresh_dsl::refresh_tokens
+                    .filter(refresh_dsl::token_hash.eq(hashed))
+                    .filter(refresh_dsl::user_id.eq(user.user_id))
+                    .filter(refresh_dsl::revoked_at.is_null()),
+            )
+            .set((
+                refresh_dsl::revoked_at.eq(now),
+                refresh_dsl::updated_at.eq(now),
+            ))
+            .execute(&mut conn)
+            .unwrap_or(0);
+        }
+    }
+
+    if rows_affected == 0 {
+        let _ = diesel::update(
+            refresh_dsl::refresh_tokens
+                .filter(refresh_dsl::user_id.eq(user.user_id))
+                .filter(refresh_dsl::revoked_at.is_null()),
+        )
+        .set((
+            refresh_dsl::revoked_at.eq(now),
+            refresh_dsl::updated_at.eq(now),
+        ))
+        .execute(&mut conn);
+    }
+
+    let mut headers = HeaderMap::new();
+    headers.insert(SET_COOKIE, build_clear_refresh_cookie(&state));
+    Ok((headers, StatusCode::NO_CONTENT))
+}
+
+pub async fn me(user: AuthenticatedUser) -> Json<AuthenticatedUser> {
+    Json(user)
+}
+
+fn hash_refresh_token(token: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(token.as_bytes());
+    hex::encode(hasher.finalize())
+}
+
+fn generate_refresh_token() -> String {
+    let mut bytes = [0u8; 32];
+    OsRng.fill_bytes(&mut bytes);
+    hex::encode(bytes)
+}
+
+fn build_refresh_cookie(
+    state: &AppState,
+    token: &str,
+    expires_at: chrono::DateTime<Utc>,
+) -> HeaderValue {
+    let max_age = ChronoDuration::days(state.config.refresh_token_expiry_days).num_seconds();
+
+    let mut parts = vec![format!("{}={}", REFRESH_COOKIE_NAME, token)];
+    parts.push("Path=/".into());
+    parts.push("HttpOnly".into());
+    parts.push("SameSite=Strict".into());
+    parts.push(format!("Max-Age={}", max_age));
+    parts.push(format!("Expires={}", expires_at.to_rfc2822()));
+    if state.config.refresh_cookie_secure {
+        parts.push("Secure".into());
+    }
+    if let Some(domain) = &state.config.refresh_cookie_domain {
+        parts.push(format!("Domain={}", domain));
+    }
+
+    HeaderValue::from_str(&parts.join("; ")).expect("valid refresh cookie")
+}
+
+fn build_clear_refresh_cookie(state: &AppState) -> HeaderValue {
+    let mut parts = vec![format!("{}=", REFRESH_COOKIE_NAME)];
+    parts.push("Path=/".into());
+    parts.push("HttpOnly".into());
+    parts.push("SameSite=Strict".into());
+    parts.push("Max-Age=0".into());
+    parts.push("Expires=Thu, 01 Jan 1970 00:00:00 GMT".into());
+    if state.config.refresh_cookie_secure {
+        parts.push("Secure".into());
+    }
+    if let Some(domain) = &state.config.refresh_cookie_domain {
+        parts.push(format!("Domain={}", domain));
+    }
+
+    HeaderValue::from_str(&parts.join("; ")).expect("valid refresh cookie")
+}

backend/src/routes/correspondents.rs

@@ -0,0 +1,259 @@
+use std::collections::{BTreeMap, HashMap};
+
+use axum::{
+    extract::{Path, State},
+    http::StatusCode,
+    response::IntoResponse,
+    Json,
+};
+use chrono::Utc;
+use diesel::{dsl::count_star, prelude::*, result::DatabaseErrorKind, PgConnection};
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use uuid::Uuid;
+
+use crate::{
+    error::{AppError, AppResult},
+    models::{Correspondent, NewCorrespondent},
+    schema::{correspondents, document_correspondents},
+    state::AppState,
+};
+
+use super::documents::to_iso;
+
+#[derive(Serialize)]
+pub struct CorrespondentUsage {
+    pub total: i64,
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub by_role: BTreeMap<String, i64>,
+}
+
+#[derive(Serialize)]
+pub struct CorrespondentSummary {
+    pub id: Uuid,
+    pub name: String,
+    pub metadata: Value,
+    pub created_at: String,
+    pub updated_at: String,
+    pub usage: CorrespondentUsage,
+}
+
+#[derive(Deserialize)]
+pub struct CreateCorrespondentRequest {
+    pub name: String,
+    #[serde(default)]
+    pub metadata: Option<Value>,
+}
+
+#[derive(Deserialize)]
+pub struct UpdateCorrespondentRequest {
+    pub name: Option<String>,
+    pub metadata: Option<Value>,
+}
+
+#[derive(AsChangeset, Default)]
+#[diesel(table_name = correspondents)]
+struct CorrespondentChangeset<'a> {
+    name: Option<&'a str>,
+    metadata: Option<&'a Value>,
+}
+
+pub async fn list_correspondents(
+    State(state): State<AppState>,
+) -> AppResult<Json<Vec<CorrespondentSummary>>> {
+    let mut conn = state.db()?;
+
+    let correspondents_list: Vec<Correspondent> = correspondents::table
+        .order(correspondents::name.asc())
+        .load(&mut conn)?;
+
+    let usage_rows: Vec<(Uuid, String, i64)> = document_correspondents::table
+        .group_by((
+            document_correspondents::correspondent_id,
+            document_correspondents::role,
+        ))
+        .select((
+            document_correspondents::correspondent_id,
+            document_correspondents::role,
+            count_star(),
+        ))
+        .load(&mut conn)?;
+
+    let mut usage_map: HashMap<Uuid, BTreeMap<String, i64>> = HashMap::new();
+    for (correspondent_id, role, count) in usage_rows {
+        usage_map
+            .entry(correspondent_id)
+            .or_default()
+            .insert(role, count);
+    }
+
+    let mut response = Vec::with_capacity(correspondents_list.len());
+    for correspondent in correspondents_list {
+        let role_counts = usage_map.remove(&correspondent.id).unwrap_or_default();
+        response.push(build_summary(correspondent, role_counts));
+    }
+
+    Ok(Json(response))
+}
+
+pub async fn create_correspondent(
+    State(state): State<AppState>,
+    Json(payload): Json<CreateCorrespondentRequest>,
+) -> AppResult<Json<CorrespondentSummary>> {
+    let name = payload.name.trim();
+    if name.is_empty() {
+        return Err(AppError::bad_request("name must not be empty"));
+    }
+
+    let metadata_value = normalize_metadata(payload.metadata);
+    let new_id = Uuid::new_v4();
+    let new_correspondent = NewCorrespondent {
+        id: new_id,
+        name: name.to_string(),
+        metadata: metadata_value,
+    };
+
+    let mut conn = state.db()?;
+    match diesel::insert_into(correspondents::table)
+        .values(&new_correspondent)
+        .execute(&mut conn)
+    {
+        Ok(_) => {}
+        Err(diesel::result::Error::DatabaseError(DatabaseErrorKind::UniqueViolation, _)) => {
+            return Err(AppError::bad_request("correspondent name already exists"));
+        }
+        Err(err) => return Err(AppError::from(err)),
+    }
+
+    let correspondent: Correspondent = correspondents::table.find(new_id).first(&mut conn)?;
+    Ok(Json(build_summary(correspondent, BTreeMap::new())))
+}
+
+pub async fn update_correspondent(
+    State(state): State<AppState>,
+    Path(correspondent_id): Path<Uuid>,
+    Json(payload): Json<UpdateCorrespondentRequest>,
+) -> AppResult<Json<CorrespondentSummary>> {
+    let mut conn = state.db()?;
+    let existing: Correspondent = correspondents::table
+        .find(correspondent_id)
+        .first(&mut conn)?;
+
+    let mut new_name: Option<String> = None;
+    if let Some(ref candidate) = payload.name {
+        let trimmed = candidate.trim();
+        if trimmed.is_empty() {
+            return Err(AppError::bad_request("name must not be empty"));
+        }
+        if trimmed != existing.name {
+            let duplicate = correspondents::table
+                .filter(correspondents::name.eq(trimmed))
+                .filter(correspondents::id.ne(correspondent_id))
+                .first::<Correspondent>(&mut conn)
+                .optional()?;
+            if duplicate.is_some() {
+                return Err(AppError::bad_request("correspondent name already exists"));
+            }
+            new_name = Some(trimmed.to_string());
+        }
+    }
+
+    let mut new_metadata: Option<Value> = None;
+    if let Some(metadata) = payload.metadata.clone() {
+        let candidate = normalize_metadata(Some(metadata));
+        if candidate != existing.metadata {
+            new_metadata = Some(candidate);
+        }
+    }
+
+    if new_name.is_none() && new_metadata.is_none() {
+        let usage = load_usage_for_correspondent(&mut conn, correspondent_id)?;
+        return Ok(Json(build_summary(existing.clone(), usage)));
+    }
+
+    let mut changeset = CorrespondentChangeset::default();
+    if let Some(ref name) = new_name {
+        changeset.name = Some(name.as_str());
+    }
+    if let Some(ref metadata) = new_metadata {
+        changeset.metadata = Some(metadata);
+    }
+
+    let now = Utc::now().naive_utc();
+    diesel::update(correspondents::table.find(correspondent_id))
+        .set((&changeset, correspondents::updated_at.eq(now)))
+        .execute(&mut conn)?;
+
+    let updated: Correspondent = correspondents::table
+        .find(correspondent_id)
+        .first(&mut conn)?;
+    let usage = load_usage_for_correspondent(&mut conn, correspondent_id)?;
+    Ok(Json(build_summary(updated, usage)))
+}
+
+pub async fn delete_correspondent(
+    State(state): State<AppState>,
+    Path(correspondent_id): Path<Uuid>,
+) -> AppResult<impl IntoResponse> {
+    let mut conn = state.db()?;
+
+    let usage: i64 = document_correspondents::table
+        .filter(document_correspondents::correspondent_id.eq(correspondent_id))
+        .select(count_star())
+        .first(&mut conn)?;
+
+    if usage > 0 {
+        return Err(AppError::bad_request(
+            "cannot delete correspondent that is still assigned to documents",
+        ));
+    }
+
+    let deleted =
+        diesel::delete(correspondents::table.find(correspondent_id)).execute(&mut conn)?;
+    if deleted == 0 {
+        return Err(AppError::not_found());
+    }
+    Ok(StatusCode::NO_CONTENT)
+}
+
+fn build_summary(
+    correspondent: Correspondent,
+    role_counts: BTreeMap<String, i64>,
+) -> CorrespondentSummary {
+    let total = role_counts.values().copied().sum();
+    CorrespondentSummary {
+        id: correspondent.id,
+        name: correspondent.name,
+        metadata: correspondent.metadata,
+        created_at: to_iso(correspondent.created_at),
+        updated_at: to_iso(correspondent.updated_at),
+        usage: CorrespondentUsage {
+            total,
+            by_role: role_counts,
+        },
+    }
+}
+
+fn normalize_metadata(input: Option<Value>) -> Value {
+    match input {
+        None | Some(Value::Null) => Value::Object(Default::default()),
+        Some(value) => value,
+    }
+}
+
+fn load_usage_for_correspondent(
+    conn: &mut PgConnection,
+    correspondent_id: Uuid,
+) -> AppResult<BTreeMap<String, i64>> {
+    let rows: Vec<(String, i64)> = document_correspondents::table
+        .filter(document_correspondents::correspondent_id.eq(correspondent_id))
+        .group_by(document_correspondents::role)
+        .select((document_correspondents::role, count_star()))
+        .load(conn)?;
+
+    let mut map = BTreeMap::new();
+    for (role, count) in rows {
+        map.insert(role, count);
+    }
+    Ok(map)
+}

backend/src/routes/folders.rs

@@ -0,0 +1,401 @@
+use axum::{
+    extract::{Json, Path, Query, State},
+    http::StatusCode,
+};
+use diesel::{dsl::exists, prelude::*, PgConnection};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::models::{Document, Folder, NewFolder};
+use crate::schema::{documents, folders};
+use crate::state::AppState;
+use crate::{
+    auth::AuthenticatedUser,
+    error::{AppError, AppResult},
+};
+
+use super::documents::{
+    load_correspondents_for_documents, load_primary_assets, load_tags_for_documents,
+    to_document_response, to_iso, DocumentResponse,
+};
+
+#[derive(Deserialize)]
+pub struct CreateFolderRequest {
+    pub name: String,
+    pub parent_id: Option<Uuid>,
+}
+
+#[derive(Deserialize)]
+pub struct EnsureFolderPathRequest {
+    pub parent_id: Option<Uuid>,
+    pub segments: Vec<String>,
+}
+
+#[derive(Deserialize)]
+pub struct UpdateFolderRequest {
+    #[serde(default)]
+    pub parent_id: Option<Option<Uuid>>,
+    pub name: Option<String>,
+}
+
+#[derive(Serialize)]
+pub struct FolderResponse {
+    pub folder: FolderInfo,
+}
+
+#[derive(Serialize)]
+pub struct FolderContentsResponse {
+    pub folder: Option<FolderInfo>,
+    pub subfolders: Vec<FolderInfo>,
+    pub documents: Vec<DocumentResponse>,
+}
+
+#[derive(Deserialize)]
+pub struct FolderContentsQuery {
+    #[serde(default = "default_include_documents")]
+    pub include_documents: bool,
+}
+
+const fn default_include_documents() -> bool {
+    true
+}
+
+#[derive(Serialize)]
+pub struct FolderInfo {
+    pub id: Uuid,
+    pub name: String,
+    pub parent_id: Option<Uuid>,
+    pub created_at: String,
+    pub updated_at: String,
+}
+
+pub async fn ensure_folder_path(
+    State(state): State<AppState>,
+    Json(payload): Json<EnsureFolderPathRequest>,
+) -> AppResult<Json<FolderResponse>> {
+    if payload.segments.is_empty() {
+        return Err(AppError::bad_request("segments must not be empty"));
+    }
+
+    let mut conn = state.db()?;
+
+    let target_folder = conn.transaction::<Folder, AppError, _>(|conn| {
+        let mut current_parent = payload.parent_id;
+        let mut last_folder: Option<Folder> = None;
+
+        for raw_name in &payload.segments {
+            let name = raw_name.trim();
+            if name.is_empty() {
+                return Err(AppError::bad_request("folder names must not be empty"));
+            }
+
+            let existing: Option<Folder> = if let Some(parent_id) = current_parent {
+                folders::table
+                    .filter(folders::parent_id.eq(Some(parent_id)))
+                    .filter(folders::name.eq(name))
+                    .first(conn)
+                    .optional()?
+            } else {
+                folders::table
+                    .filter(folders::parent_id.is_null())
+                    .filter(folders::name.eq(name))
+                    .first(conn)
+                    .optional()?
+            };
+
+            let folder = if let Some(folder) = existing {
+                folder
+            } else {
+                let new_folder = NewFolder {
+                    id: Uuid::new_v4(),
+                    name: name.to_string(),
+                    parent_id: current_parent,
+                };
+
+                diesel::insert_into(folders::table)
+                    .values(&new_folder)
+                    .execute(conn)?;
+
+                folders::table.find(new_folder.id).first(conn)?
+            };
+
+            current_parent = Some(folder.id);
+            last_folder = Some(folder);
+        }
+
+        last_folder.ok_or_else(|| AppError::internal("failed to resolve folder path".to_string()))
+    })?;
+
+    Ok(Json(FolderResponse {
+        folder: folder_to_info(target_folder),
+    }))
+}
+
+pub async fn create_folder(
+    State(state): State<AppState>,
+    Json(payload): Json<CreateFolderRequest>,
+) -> AppResult<Json<FolderResponse>> {
+    if payload.name.trim().is_empty() {
+        return Err(AppError::bad_request("name must not be empty"));
+    }
+
+    let mut conn = state.db()?;
+
+    let new_folder = NewFolder {
+        id: Uuid::new_v4(),
+        name: payload.name.trim().to_string(),
+        parent_id: payload.parent_id,
+    };
+
+    diesel::insert_into(folders::table)
+        .values(&new_folder)
+        .execute(&mut conn)?;
+
+    let folder: Folder = folders::table.find(new_folder.id).first(&mut conn)?;
+    Ok(Json(FolderResponse {
+        folder: folder_to_info(folder),
+    }))
+}
+
+pub async fn list_folder_contents(
+    State(state): State<AppState>,
+    Path(folder_identifier): Path<String>,
+    Query(query): Query<FolderContentsQuery>,
+    user: AuthenticatedUser,
+) -> AppResult<Json<FolderContentsResponse>> {
+    let mut conn = state.db()?;
+
+    let folder_id = if folder_identifier.eq_ignore_ascii_case("root") {
+        None
+    } else {
+        Some(
+            Uuid::parse_str(&folder_identifier)
+                .map_err(|_| AppError::bad_request("folder identifier must be 'root' or a UUID"))?,
+        )
+    };
+
+    let folder = match folder_id {
+        Some(id) => Some(folder_to_info(
+            folders::table.find(id).first::<Folder>(&mut conn)?,
+        )),
+        None => None,
+    };
+
+    let child_folders: Vec<Folder> = if let Some(parent_id) = folder_id {
+        folders::table
+            .filter(folders::parent_id.eq(parent_id))
+            .order(folders::name.asc())
+            .load(&mut conn)?
+    } else {
+        folders::table
+            .filter(folders::parent_id.is_null())
+            .order(folders::name.asc())
+            .load(&mut conn)?
+    };
+    let subfolders = child_folders.into_iter().map(folder_to_info).collect();
+
+    let documents = if query.include_documents {
+        let docs_query = documents::table
+            .filter(documents::deleted_at.is_null())
+            .order(documents::uploaded_at.desc());
+
+        let docs: Vec<Document> = if let Some(current_folder) = folder_id {
+            docs_query
+                .filter(documents::folder_id.eq(current_folder))
+                .load(&mut conn)?
+        } else {
+            docs_query
+                .filter(documents::folder_id.is_null())
+                .load(&mut conn)?
+        };
+
+        let doc_ids: Vec<Uuid> = docs.iter().map(|doc| doc.id).collect();
+        let tags_map = load_tags_for_documents(&mut conn, &doc_ids)?;
+        let mut correspondents_map = load_correspondents_for_documents(&mut conn, &doc_ids)?;
+        drop(conn);
+
+        let primary_versions = load_primary_assets(&state, &docs).await?;
+
+        let mut documents = Vec::with_capacity(doc_ids.len());
+        for doc in docs {
+            let tags = tags_map.get(&doc.id).cloned();
+            let correspondents = correspondents_map.remove(&doc.id).unwrap_or_default();
+            let current_version = primary_versions.get(&doc.id).cloned();
+            documents.push(to_document_response(
+                &state,
+                user.user_id,
+                doc,
+                tags,
+                correspondents,
+                current_version,
+            )?);
+        }
+
+        documents
+    } else {
+        Vec::new()
+    };
+
+    Ok(Json(FolderContentsResponse {
+        folder,
+        subfolders,
+        documents,
+    }))
+}
+
+pub async fn delete_folder(
+    State(state): State<AppState>,
+    Path(folder_id): Path<Uuid>,
+) -> AppResult<StatusCode> {
+    let mut conn = state.db()?;
+
+    conn.transaction::<_, AppError, _>(|conn| {
+        folders::table.find(folder_id).first::<Folder>(conn)?;
+
+        let has_child_folders: bool = diesel::select(exists(
+            folders::table.filter(folders::parent_id.eq(Some(folder_id))),
+        ))
+        .get_result(conn)?;
+
+        if has_child_folders {
+            return Err(AppError::bad_request(
+                "folder must be empty before deletion",
+            ));
+        }
+
+        let has_documents: bool = diesel::select(exists(
+            documents::table
+                .filter(documents::folder_id.eq(Some(folder_id)))
+                .filter(documents::deleted_at.is_null()),
+        ))
+        .get_result(conn)?;
+
+        if has_documents {
+            return Err(AppError::bad_request(
+                "folder must be empty before deletion",
+            ));
+        }
+
+        diesel::delete(folders::table.find(folder_id)).execute(conn)?;
+
+        Ok(())
+    })?;
+
+    Ok(StatusCode::NO_CONTENT)
+}
+
+pub async fn update_folder(
+    State(state): State<AppState>,
+    Path(folder_id): Path<Uuid>,
+    Json(payload): Json<UpdateFolderRequest>,
+) -> AppResult<StatusCode> {
+    let mut conn = state.db()?;
+
+    conn.transaction::<(), AppError, _>(|conn| {
+        let folder: Folder = folders::table.find(folder_id).first(conn)?;
+
+        let mut next_parent = folder.parent_id;
+        let mut parent_changed = false;
+
+        if let Some(parent_request) = payload.parent_id {
+            if parent_request == Some(folder_id) {
+                return Err(AppError::bad_request("folder cannot be its own parent"));
+            }
+
+            if let Some(parent_id) = parent_request {
+                let _parent: Folder = folders::table.find(parent_id).first(conn)?;
+
+                let descendant_ids = gather_descendant_folder_ids(conn, folder_id)?;
+                if descendant_ids.contains(&parent_id) {
+                    return Err(AppError::bad_request(
+                        "cannot move folder into itself or a descendant",
+                    ));
+                }
+            }
+
+            parent_changed = parent_request != folder.parent_id;
+            next_parent = parent_request;
+        }
+
+        let mut new_name = folder.name.clone();
+        let mut name_changed = false;
+
+        if let Some(name) = payload.name {
+            let trimmed = name.trim();
+            if trimmed.is_empty() {
+                return Err(AppError::bad_request("name must not be empty"));
+            }
+
+            if trimmed != folder.name {
+                new_name = trimmed.to_string();
+                name_changed = true;
+            }
+        }
+
+        if !parent_changed && !name_changed {
+            return Ok(());
+        }
+
+        let conflict = if let Some(parent_id) = next_parent {
+            folders::table
+                .filter(folders::parent_id.eq(Some(parent_id)))
+                .filter(folders::name.eq(&new_name))
+                .filter(folders::id.ne(folder_id))
+                .first::<Folder>(conn)
+                .optional()?
+        } else {
+            folders::table
+                .filter(folders::parent_id.is_null())
+                .filter(folders::name.eq(&new_name))
+                .filter(folders::id.ne(folder_id))
+                .first::<Folder>(conn)
+                .optional()?
+        };
+
+        if conflict.is_some() {
+            return Err(AppError::bad_request(
+                "a folder with the same name already exists in the target",
+            ));
+        }
+
+        diesel::update(folders::table.find(folder_id))
+            .set((
+                folders::parent_id.eq(next_parent),
+                folders::name.eq(&new_name),
+            ))
+            .execute(conn)?;
+
+        Ok(())
+    })?;
+
+    Ok(StatusCode::NO_CONTENT)
+}
+
+fn folder_to_info(folder: Folder) -> FolderInfo {
+    FolderInfo {
+        id: folder.id,
+        name: folder.name,
+        parent_id: folder.parent_id,
+        created_at: to_iso(folder.created_at),
+        updated_at: to_iso(folder.updated_at),
+    }
+}
+
+pub(super) fn gather_descendant_folder_ids(
+    conn: &mut PgConnection,
+    folder_id: Uuid,
+) -> AppResult<Vec<Uuid>> {
+    let mut ids = vec![folder_id];
+    let mut queue = vec![folder_id];
+
+    while let Some(current) = queue.pop() {
+        let child_ids: Vec<Uuid> = folders::table
+            .filter(folders::parent_id.eq(Some(current)))
+            .select(folders::id)
+            .load(conn)?;
+        queue.extend(child_ids.iter().copied());
+        ids.extend(child_ids);
+    }
+
+    Ok(ids)
+}

backend/src/routes/health.rs

@@ -0,0 +1,6 @@
+use axum::{http::StatusCode, response::Json};
+use serde_json::json;
+
+pub async fn health_check() -> (StatusCode, Json<serde_json::Value>) {
+    (StatusCode::OK, Json(json!({ "status": "ok" })))
+}

backend/src/routes/mod.rs

@@ -0,0 +1,138 @@
+use axum::http::HeaderValue;
+use axum::{
+    extract::DefaultBodyLimit,
+    middleware,
+    routing::{delete, get, patch, post},
+    Router,
+};
+use tower_http::cors::{AllowOrigin, CorsLayer};
+
+use crate::{auth::AuthenticatedUser, state::AppState};
+
+pub mod auth;
+pub mod correspondents;
+pub mod documents;
+pub mod folders;
+pub mod health;
+pub mod tags;
+pub mod webdav;
+
+pub fn create_router(state: AppState) -> Router<()> {
+    let cors = if let Some(origins) = state.config.cors_allowed_origin.as_ref() {
+        let headers: Vec<HeaderValue> = origins
+            .split(',')
+            .filter_map(|value| {
+                let trimmed = value.trim();
+                (!trimmed.is_empty()).then(|| {
+                    trimmed
+                        .parse::<HeaderValue>()
+                        .expect("invalid CORS allowed origin")
+                })
+            })
+            .collect();
+
+        let allow_origin = AllowOrigin::list(headers);
+
+        CorsLayer::new()
+            .allow_origin(allow_origin)
+            .allow_methods(tower_http::cors::AllowMethods::mirror_request())
+            .allow_headers(tower_http::cors::AllowHeaders::mirror_request())
+            .allow_credentials(true)
+    } else {
+        CorsLayer::new()
+            .allow_origin(AllowOrigin::mirror_request())
+            .allow_methods(tower_http::cors::AllowMethods::mirror_request())
+            .allow_headers(tower_http::cors::AllowHeaders::mirror_request())
+            .allow_credentials(true)
+    };
+
+    let auth_routes = Router::new()
+        .route("/login", post(auth::login))
+        .route("/refresh", post(auth::refresh))
+        .route("/logout", post(auth::logout))
+        .route("/me", get(auth::me));
+
+    let documents_routes = Router::new()
+        .route(
+            "/",
+            get(documents::list_documents).post(documents::upload_document),
+        )
+        .route("/reanalyze", post(documents::reanalyze_all_documents))
+        .route("/bulk/move", post(documents::bulk_move_documents))
+        .route("/bulk/tags", post(documents::bulk_update_tags))
+        .route(
+            "/bulk/correspondents",
+            post(documents::bulk_assign_correspondents),
+        )
+        .route(
+            "/bulk/reanalyze",
+            post(documents::reanalyze_selected_documents),
+        )
+        .route(
+            "/:id",
+            get(documents::get_document)
+                .delete(documents::delete_document)
+                .patch(documents::update_document),
+        )
+        .route("/:id/download", get(documents::download_document))
+        .route("/:id/assets/:asset_id", get(documents::get_document_asset))
+        .route(
+            "/:id/assets",
+            get(documents::list_document_assets).post(documents::request_document_assets),
+        )
+        .route("/:id/folder", patch(documents::move_document))
+        .route("/:id/tags", post(documents::assign_tags))
+        .route("/:id/tags/:tag_id", delete(documents::remove_tag))
+        .route(
+            "/:id/correspondents",
+            post(documents::assign_correspondents),
+        )
+        .route(
+            "/:id/correspondents/:correspondent_id",
+            delete(documents::remove_correspondent),
+        );
+
+    let download_routes =
+        Router::new().route("/download/:token", get(documents::download_with_token));
+
+    let folders_routes = Router::new()
+        .route("/", post(folders::create_folder))
+        .route("/path", post(folders::ensure_folder_path))
+        .route(
+            "/:id",
+            delete(folders::delete_folder).patch(folders::update_folder),
+        )
+        .route("/:id/contents", get(folders::list_folder_contents));
+
+    let tags_routes = Router::new()
+        .route("/", get(tags::list_tags).post(tags::create_tag))
+        .route("/:id", patch(tags::update_tag).delete(tags::delete_tag));
+
+    let correspondents_routes = Router::new()
+        .route(
+            "/",
+            get(correspondents::list_correspondents).post(correspondents::create_correspondent),
+        )
+        .route(
+            "/:id",
+            patch(correspondents::update_correspondent)
+                .delete(correspondents::delete_correspondent),
+        );
+
+    let protected_state = state.clone();
+    let protected_routes = Router::new()
+        .nest("/api/documents", documents_routes)
+        .nest("/api/folders", folders_routes)
+        .nest("/api/tags", tags_routes)
+        .nest("/api/correspondents", correspondents_routes)
+        .layer(middleware::from_extractor_with_state::<AuthenticatedUser, _>(protected_state));
+
+    Router::new()
+        .merge(download_routes)
+        .merge(protected_routes)
+        .nest("/api/auth", auth_routes)
+        .route("/api/health", get(health::health_check))
+        .with_state(state)
+        .layer(cors)
+        .layer(DefaultBodyLimit::max(1024 * 1024 * 512))
+}

backend/src/routes/tags.rs

@@ -0,0 +1,235 @@
+use crate::utils::json::{classify_nullable, NullableValue};
+use axum::{
+    extract::{Path, State},
+    http::StatusCode,
+    Json,
+};
+use diesel::{dsl::count_star, prelude::*};
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use std::collections::HashMap;
+use uuid::Uuid;
+
+use crate::error::{AppError, AppResult};
+use crate::models::{NewTag, Tag};
+use crate::schema::{document_tags, tags};
+use crate::state::AppState;
+
+#[derive(Deserialize)]
+pub struct CreateTagRequest {
+    pub label: String,
+    pub color: Option<String>,
+}
+
+#[derive(AsChangeset, Default)]
+#[diesel(table_name = tags)]
+struct UpdateTagChangeset<'a> {
+    label: Option<&'a str>,
+    color: Option<Option<&'a str>>,
+}
+
+#[derive(Serialize)]
+pub struct TagCatalogEntry {
+    pub id: Uuid,
+    pub label: String,
+    pub color: Option<String>,
+    pub usage_count: i64,
+}
+
+pub async fn list_tags(State(state): State<AppState>) -> AppResult<Json<Vec<TagCatalogEntry>>> {
+    let mut conn = state.db()?;
+
+    let tag_list: Vec<Tag> = tags::table.order(tags::label.asc()).load(&mut conn)?;
+
+    let usage_rows: Vec<(Uuid, i64)> = document_tags::table
+        .group_by(document_tags::tag_id)
+        .select((document_tags::tag_id, count_star()))
+        .load(&mut conn)?;
+
+    let usage_map: HashMap<Uuid, i64> = usage_rows.into_iter().collect();
+
+    let response = tag_list
+        .into_iter()
+        .map(|tag| TagCatalogEntry {
+            id: tag.id,
+            label: tag.label,
+            color: tag.color,
+            usage_count: *usage_map.get(&tag.id).unwrap_or(&0),
+        })
+        .collect();
+
+    Ok(Json(response))
+}
+
+pub async fn create_tag(
+    State(state): State<AppState>,
+    Json(payload): Json<CreateTagRequest>,
+) -> AppResult<Json<TagCatalogEntry>> {
+    if payload.label.trim().is_empty() {
+        return Err(AppError::bad_request("label must not be empty"));
+    }
+
+    let mut conn = state.db()?;
+    let new_tag = NewTag {
+        id: Uuid::new_v4(),
+        label: payload.label.trim().to_string(),
+        color: payload.color,
+    };
+
+    match diesel::insert_into(tags::table)
+        .values(&new_tag)
+        .execute(&mut conn)
+    {
+        Ok(_) => {}
+        Err(diesel::result::Error::DatabaseError(
+            diesel::result::DatabaseErrorKind::UniqueViolation,
+            _,
+        )) => {
+            return Err(AppError::bad_request("tag label already exists"));
+        }
+        Err(err) => return Err(AppError::from(err)),
+    }
+
+    let tag: Tag = tags::table.find(new_tag.id).first(&mut conn)?;
+    Ok(Json(TagCatalogEntry {
+        id: tag.id,
+        label: tag.label,
+        color: tag.color,
+        usage_count: 0,
+    }))
+}
+
+pub async fn update_tag(
+    State(state): State<AppState>,
+    Path(tag_id): Path<Uuid>,
+    Json(body): Json<Value>,
+) -> AppResult<Json<TagCatalogEntry>> {
+    let mut conn = state.db()?;
+    let existing: Tag = tags::table.find(tag_id).first(&mut conn)?;
+    let label_class = classify_nullable(body.get("label")).map_err(AppError::bad_request)?;
+    let color_class = classify_nullable(body.get("color")).map_err(AppError::bad_request)?;
+
+    if matches!(label_class, NullableValue::Omitted)
+        && matches!(color_class, NullableValue::Omitted)
+    {
+        let usage_count: i64 = document_tags::table
+            .filter(document_tags::tag_id.eq(tag_id))
+            .select(count_star())
+            .first(&mut conn)?;
+        return Ok(Json(TagCatalogEntry {
+            id: existing.id,
+            label: existing.label.clone(),
+            color: existing.color.clone(),
+            usage_count,
+        }));
+    }
+
+    let mut new_label: Option<String> = None;
+    let mut label_changed = false;
+    match label_class {
+        NullableValue::Omitted => {}
+        NullableValue::Null => {
+            return Err(AppError::bad_request("label cannot be null"));
+        }
+        NullableValue::String(value) => {
+            let trimmed = value.trim();
+            if trimmed.is_empty() {
+                return Err(AppError::bad_request("label must not be empty"));
+            }
+            if trimmed != existing.label {
+                let duplicate = tags::table
+                    .filter(tags::label.eq(trimmed))
+                    .filter(tags::id.ne(tag_id))
+                    .first::<Tag>(&mut conn)
+                    .optional()?;
+                if duplicate.is_some() {
+                    return Err(AppError::bad_request("tag label already exists"));
+                }
+                new_label = Some(trimmed.to_string());
+                label_changed = true;
+            }
+        }
+    }
+
+    let mut color_change: Option<Option<String>> = None;
+    let mut color_changed = false;
+    match color_class {
+        NullableValue::Omitted => {}
+        NullableValue::Null => {
+            color_change = Some(None);
+            color_changed = true;
+        }
+        NullableValue::String(value) => {
+            let trimmed = value.trim();
+            if trimmed.is_empty() {
+                return Err(AppError::bad_request("color must not be empty"));
+            }
+            if existing.color.as_deref() != Some(trimmed) {
+                color_change = Some(Some(trimmed.to_string()));
+                color_changed = true;
+            }
+        }
+    }
+
+    if !label_changed && !color_changed {
+        let usage_count: i64 = document_tags::table
+            .filter(document_tags::tag_id.eq(tag_id))
+            .select(count_star())
+            .first(&mut conn)?;
+        return Ok(Json(TagCatalogEntry {
+            id: existing.id,
+            label: existing.label.clone(),
+            color: existing.color.clone(),
+            usage_count,
+        }));
+    }
+
+    let changeset = UpdateTagChangeset {
+        label: new_label.as_deref(),
+        color: color_change
+            .as_ref()
+            .map(|opt| opt.as_ref().map(|value| value.as_str())),
+    };
+
+    diesel::update(tags::table.find(tag_id))
+        .set(&changeset)
+        .execute(&mut conn)?;
+
+    let updated: Tag = tags::table.find(tag_id).first(&mut conn)?;
+    let usage_count: i64 = document_tags::table
+        .filter(document_tags::tag_id.eq(tag_id))
+        .select(count_star())
+        .first(&mut conn)?;
+
+    Ok(Json(TagCatalogEntry {
+        id: updated.id,
+        label: updated.label,
+        color: updated.color,
+        usage_count,
+    }))
+}
+
+pub async fn delete_tag(
+    State(state): State<AppState>,
+    Path(tag_id): Path<Uuid>,
+) -> AppResult<impl axum::response::IntoResponse> {
+    let mut conn = state.db()?;
+
+    let usage: i64 = document_tags::table
+        .filter(document_tags::tag_id.eq(tag_id))
+        .select(count_star())
+        .first(&mut conn)?;
+
+    if usage > 0 {
+        return Err(AppError::bad_request(
+            "cannot delete tag that is still assigned to documents",
+        ));
+    }
+
+    let deleted = diesel::delete(tags::table.find(tag_id)).execute(&mut conn)?;
+    if deleted == 0 {
+        return Err(AppError::not_found());
+    }
+
+    Ok(StatusCode::NO_CONTENT)
+}

backend/src/routes/webdav/mod.rs

@@ -0,0 +1,808 @@
+use std::time::Duration;
+
+use axum::body::Body;
+use axum::extract::State;
+use axum::http::{header, HeaderMap, Method, StatusCode};
+use axum::response::Response;
+use axum::Router;
+use base64::engine::general_purpose::STANDARD as BASE64;
+use base64::Engine;
+use diesel::prelude::*;
+use diesel::PgConnection;
+use futures_util::StreamExt;
+use percent_encoding::{percent_decode_str, utf8_percent_encode, NON_ALPHANUMERIC};
+use quick_xml::events::{BytesDecl, BytesEnd, BytesStart, BytesText, Event};
+use quick_xml::Writer;
+use uuid::Uuid;
+
+use crate::auth::password;
+use crate::error::{AppError, AppResult};
+use crate::models::{Document, DocumentVersion, Folder, User};
+use crate::schema::{
+    document_versions::dsl as document_versions_dsl, documents::dsl as documents_dsl,
+    folders::dsl as folders_dsl, users::dsl as users_dsl,
+};
+use crate::state::AppState;
+
+const REALM: &str = "Papercrate WebDAV";
+const DOWNLOAD_URL_TTL_SECONDS: u64 = 300;
+
+#[derive(Clone, Debug)]
+struct WebDavUser {
+    _user_id: Uuid,
+    _username: String,
+}
+
+pub fn create_router() -> Router<AppState> {
+    Router::new().fallback(webdav_entrypoint)
+}
+
+async fn webdav_entrypoint(
+    State(state): State<AppState>,
+    req: axum::http::Request<axum::body::Body>,
+) -> Result<Response, AppError> {
+    let method = req.method().clone();
+    let headers = req.headers().clone();
+    let path = req.uri().path().trim_start_matches('/').to_string();
+
+    tracing::debug!(method = %method, %path, "webdav entrypoint" );
+
+    match method {
+        ref m if m == Method::OPTIONS => Ok(handle_options()),
+        ref m if m == Method::GET => handle_get_or_head(&state, &path, headers, Method::GET).await,
+        ref m if m == Method::HEAD => {
+            handle_get_or_head(&state, &path, headers, Method::HEAD).await
+        }
+        _ => {
+            if method.as_str() == "PROPFIND" {
+                handle_propfind(&state, &path, headers).await
+            } else {
+                Ok(method_not_allowed())
+            }
+        }
+    }
+}
+
+async fn handle_propfind(
+    state: &AppState,
+    path: &str,
+    headers: HeaderMap,
+) -> Result<Response, AppError> {
+    let _user = match authenticate(state, &headers)? {
+        Some(user) => user,
+        None => return Ok(unauthorized_response()),
+    };
+
+    let depth = match parse_depth(&headers) {
+        Ok(value) => value,
+        Err(response) => return Ok(response),
+    };
+
+    let segments = parse_segments(path)?;
+    let resolution = match resolve_path(state, &segments)? {
+        Some(resolved) => resolved,
+        None => return Ok(not_found_response()),
+    };
+
+    let resources = match resolution {
+        ResolvedPath::Root => {
+            let contents = fetch_folder_contents(state, None)?;
+            build_resources_for_folder(None, &[], &contents, depth)
+        }
+        ResolvedPath::Folder { folder, chain } => {
+            let contents = fetch_folder_contents(state, Some(folder.id))?;
+            build_resources_for_folder(Some(&folder), &chain, &contents, depth)
+        }
+        ResolvedPath::Document {
+            document,
+            version,
+            chain,
+        } => build_resources_for_document(&chain, &document, &version),
+    };
+
+    let body = render_multistatus(&resources)
+        .map_err(|err| AppError::internal(format!("failed to render WebDAV response: {err}")))?;
+
+    let response = Response::builder()
+        .status(multi_status())
+        .header(header::CONTENT_TYPE, "application/xml; charset=utf-8")
+        .body(Body::from(body))
+        .expect("valid response");
+
+    Ok(response)
+}
+
+async fn handle_get_or_head(
+    state: &AppState,
+    path: &str,
+    headers: HeaderMap,
+    method: Method,
+) -> Result<Response, AppError> {
+    let _user = match authenticate(state, &headers)? {
+        Some(user) => user,
+        None => return Ok(unauthorized_response()),
+    };
+
+    let segments = parse_segments(path)?;
+    let resolution = match resolve_path(state, &segments)? {
+        Some(resolved) => resolved,
+        None => return Ok(not_found_response()),
+    };
+
+    let (document, version, chain) = match resolution {
+        ResolvedPath::Document {
+            document,
+            version,
+            chain,
+        } => (document, version, chain),
+        _ => return Ok(method_not_allowed()),
+    };
+
+    stream_document(state, &document, &version, &chain, headers, method).await
+}
+
+fn handle_options() -> Response {
+    Response::builder()
+        .status(StatusCode::OK)
+        .header("DAV", "1,2")
+        .header(header::ALLOW, "OPTIONS, PROPFIND, GET, HEAD")
+        .header("Accept-Ranges", "bytes")
+        .body(Body::empty())
+        .expect("valid OPTIONS response")
+}
+
+fn method_not_allowed() -> Response {
+    Response::builder()
+        .status(StatusCode::METHOD_NOT_ALLOWED)
+        .body(Body::empty())
+        .expect("valid response")
+}
+
+fn not_found_response() -> Response {
+    Response::builder()
+        .status(StatusCode::NOT_FOUND)
+        .body(Body::empty())
+        .expect("valid response")
+}
+
+fn unauthorized_response() -> Response {
+    Response::builder()
+        .status(StatusCode::UNAUTHORIZED)
+        .header(
+            header::WWW_AUTHENTICATE,
+            format!("Basic realm=\"{REALM}\", charset=\"UTF-8\""),
+        )
+        .body(Body::empty())
+        .expect("valid response")
+}
+
+fn multi_status() -> StatusCode {
+    StatusCode::from_u16(207).expect("valid multi-status")
+}
+
+fn parse_depth(headers: &HeaderMap) -> Result<u8, Response> {
+    match headers.get("Depth") {
+        None => Ok(1),
+        Some(value) => match value.to_str() {
+            Ok("0") => Ok(0),
+            Ok("1") => Ok(1),
+            Ok("infinity") => Err(Response::builder()
+                .status(StatusCode::FORBIDDEN)
+                .body(Body::empty())
+                .expect("valid response")),
+            _ => Err(Response::builder()
+                .status(StatusCode::BAD_REQUEST)
+                .body(Body::empty())
+                .expect("valid response")),
+        },
+    }
+}
+
+fn parse_segments(path: &str) -> AppResult<Vec<String>> {
+    if path.trim_matches('/').is_empty() {
+        return Ok(vec![]);
+    }
+
+    let segments = path
+        .split('/')
+        .filter(|segment| !segment.is_empty())
+        .map(|segment| {
+            percent_decode_str(segment)
+                .decode_utf8()
+                .map(|cow| cow.into_owned())
+                .map_err(|_| AppError::bad_request("invalid UTF-8 in path"))
+        })
+        .collect::<Result<Vec<_>, _>>()?;
+
+    Ok(segments)
+}
+
+fn fetch_folder_contents(
+    state: &AppState,
+    folder_id: Option<Uuid>,
+) -> AppResult<WebDavFolderContents> {
+    let mut conn = state.db()?;
+
+    let folder = match folder_id {
+        Some(id) => Some(folders_dsl::folders.find(id).first::<Folder>(&mut conn)?),
+        None => None,
+    };
+
+    let subfolders: Vec<Folder> = match folder_id {
+        Some(id) => folders_dsl::folders
+            .filter(folders_dsl::parent_id.eq(Some(id)))
+            .order(folders_dsl::name.asc())
+            .load(&mut conn)?,
+        None => folders_dsl::folders
+            .filter(folders_dsl::parent_id.is_null())
+            .order(folders_dsl::name.asc())
+            .load(&mut conn)?,
+    };
+
+    let mut docs_query = documents_dsl::documents
+        .filter(documents_dsl::deleted_at.is_null())
+        .into_boxed();
+
+    docs_query = match folder_id {
+        Some(id) => docs_query.filter(documents_dsl::folder_id.eq(Some(id))),
+        None => docs_query.filter(documents_dsl::folder_id.is_null()),
+    };
+
+    let documents: Vec<Document> = docs_query
+        .order(documents_dsl::uploaded_at.desc())
+        .load(&mut conn)?;
+
+    let version_ids: Vec<Uuid> = documents.iter().map(|doc| doc.current_version_id).collect();
+    let versions: Vec<DocumentVersion> = if version_ids.is_empty() {
+        Vec::new()
+    } else {
+        document_versions_dsl::document_versions
+            .filter(document_versions_dsl::id.eq_any(&version_ids))
+            .load(&mut conn)?
+    };
+
+    let mut version_map = versions
+        .into_iter()
+        .map(|version| (version.id, version))
+        .collect::<std::collections::HashMap<_, _>>();
+
+    let mut entries = Vec::with_capacity(documents.len());
+    for document in documents {
+        if let Some(version) = version_map.remove(&document.current_version_id) {
+            entries.push(DocumentEntry { document, version });
+        }
+    }
+
+    Ok(WebDavFolderContents {
+        _folder: folder,
+        subfolders,
+        documents: entries,
+    })
+}
+
+async fn stream_document(
+    state: &AppState,
+    document: &Document,
+    version: &DocumentVersion,
+    _chain: &[String],
+    headers: HeaderMap,
+    method: Method,
+) -> Result<Response, AppError> {
+    let range_header = headers.get(header::RANGE).cloned();
+
+    let url = state
+        .storage
+        .presign_get_object(
+            &version.s3_key,
+            Duration::from_secs(DOWNLOAD_URL_TTL_SECONDS),
+        )
+        .await
+        .map_err(|err| AppError::internal(format!("failed to presign document download: {err}")))?;
+
+    let client = reqwest::Client::new();
+    let mut request = client.request(method.clone(), url.clone());
+
+    if let Some(range) = range_header.clone() {
+        request = request.header(header::RANGE, range.clone());
+    }
+
+    let upstream = request
+        .send()
+        .await
+        .map_err(|err| AppError::internal(format!("failed to fetch document stream: {err}")))?;
+
+    let status =
+        StatusCode::from_u16(upstream.status().as_u16()).unwrap_or(StatusCode::BAD_GATEWAY);
+
+    if !(status.is_success() || status == StatusCode::PARTIAL_CONTENT) {
+        return Err(AppError::internal(format!(
+            "upstream download returned status {status}"
+        )));
+    }
+
+    let mut builder = Response::builder().status(status);
+
+    if let Some(content_type) = upstream.headers().get(header::CONTENT_TYPE) {
+        builder = builder.header(header::CONTENT_TYPE, content_type);
+    } else if let Some(ref typ) = document.content_type {
+        builder = builder.header(header::CONTENT_TYPE, typ);
+    }
+
+    if let Some(content_length) = upstream.headers().get(header::CONTENT_LENGTH) {
+        builder = builder.header(header::CONTENT_LENGTH, content_length);
+    }
+
+    if let Some(range) = upstream.headers().get(header::CONTENT_RANGE) {
+        builder = builder.header(header::CONTENT_RANGE, range);
+    }
+
+    builder = builder.header("Accept-Ranges", "bytes");
+
+    if let Some(disposition) = content_disposition(&document.filename) {
+        builder = builder.header(header::CONTENT_DISPOSITION, disposition);
+    }
+
+    builder = builder.header(header::ETAG, format!("\"{}\"", version.id));
+
+    if method == Method::HEAD {
+        return builder
+            .body(Body::empty())
+            .map_err(|err| AppError::internal(format!("failed to build response: {err}")));
+    }
+
+    let stream = upstream
+        .bytes_stream()
+        .map(|chunk| chunk.map_err(|err| std::io::Error::new(std::io::ErrorKind::Other, err)));
+    let body = Body::from_stream(stream);
+
+    builder
+        .body(body)
+        .map_err(|err| AppError::internal(format!("failed to build response: {err}")))
+}
+
+fn authenticate(state: &AppState, headers: &HeaderMap) -> Result<Option<WebDavUser>, AppError> {
+    tracing::debug!("webdav authenticate invoked");
+    let authorization = match headers.get(header::AUTHORIZATION) {
+        Some(value) => match value.to_str() {
+            Ok(header) if header.starts_with("Basic ") => {
+                tracing::debug!("authorization header present");
+                &header[6..]
+            }
+            Ok(other) => {
+                tracing::warn!(header = %other, "non-basic authorization header");
+                return Ok(None);
+            }
+            Err(err) => {
+                tracing::warn!(error = %err, "invalid authorization header");
+                return Ok(None);
+            }
+        },
+        None => {
+            tracing::debug!("no authorization header");
+            return Ok(None);
+        }
+    };
+
+    let decoded = match BASE64.decode(authorization) {
+        Ok(bytes) => bytes,
+        Err(err) => {
+            tracing::warn!(error = %err, "failed to decode basic credentials");
+            return Ok(None);
+        }
+    };
+
+    let credential_str = match String::from_utf8(decoded) {
+        Ok(value) => value,
+        Err(err) => {
+            tracing::warn!(error = %err, "invalid utf-8 basic credentials");
+            return Ok(None);
+        }
+    };
+
+    let (username, password) = match credential_str.split_once(':') {
+        Some((username, password)) if !username.is_empty() => (username, password),
+        _ => return Ok(None),
+    };
+
+    tracing::debug!(%username, "attempting webdav login");
+    let mut conn = state.db()?;
+
+    let user: User = match users_dsl::users
+        .filter(users_dsl::username.eq(username))
+        .first(&mut conn)
+    {
+        Ok(user) => user,
+        Err(diesel::result::Error::NotFound) => {
+            tracing::warn!(%username, "webdav user not found");
+            return Ok(None);
+        }
+        Err(err) => return Err(AppError::from(err)),
+    };
+
+    let valid = password::verify_password(password, &user.password_hash)
+        .map_err(|_| AppError::internal("failed to verify password"))?;
+
+    if !valid {
+        tracing::warn!(%username, "webdav password invalid");
+        return Ok(None);
+    }
+
+    tracing::debug!(%username, "webdav login success");
+    Ok(Some(WebDavUser {
+        _user_id: user.id,
+        _username: user.username,
+    }))
+}
+
+fn build_resources_for_folder(
+    folder: Option<&Folder>,
+    chain: &[String],
+    contents: &WebDavFolderContents,
+    depth: u8,
+) -> Vec<DavResource> {
+    let mut resources = Vec::new();
+
+    let display_name = folder
+        .map(|folder| folder.name.clone())
+        .unwrap_or_else(|| "/".to_string());
+
+    let href = build_href(chain, true);
+    let last_modified = folder.map(|folder| format_http_date(folder.updated_at));
+
+    resources.push(DavResource {
+        href,
+        display_name,
+        is_collection: true,
+        content_length: None,
+        content_type: None,
+        last_modified,
+    });
+
+    if depth == 0 {
+        return resources;
+    }
+
+    for subfolder in &contents.subfolders {
+        let mut child_chain = chain.to_vec();
+        child_chain.push(subfolder.name.clone());
+        resources.push(DavResource {
+            href: build_href(&child_chain, true),
+            display_name: subfolder.name.clone(),
+            is_collection: true,
+            content_length: None,
+            content_type: None,
+            last_modified: Some(format_http_date(subfolder.updated_at)),
+        });
+    }
+
+    for entry in &contents.documents {
+        let mut child_chain = chain.to_vec();
+        child_chain.push(entry.document.filename.clone());
+        resources.push(document_to_resource(
+            &child_chain,
+            &entry.document,
+            &entry.version,
+        ));
+    }
+
+    resources
+}
+
+fn build_resources_for_document(
+    chain: &[String],
+    document: &Document,
+    version: &DocumentVersion,
+) -> Vec<DavResource> {
+    vec![document_to_resource(chain, document, version)]
+}
+
+fn document_to_resource(
+    chain: &[String],
+    document: &Document,
+    version: &DocumentVersion,
+) -> DavResource {
+    let href = build_href(chain, false);
+
+    DavResource {
+        href,
+        display_name: document.title.clone(),
+        is_collection: false,
+        content_length: Some(version.size_bytes),
+        content_type: document.content_type.clone(),
+        last_modified: Some(format_http_date(document.updated_at)),
+    }
+}
+
+fn build_href(names: &[String], is_collection: bool) -> String {
+    if names.is_empty() {
+        return "/".to_string();
+    }
+
+    let encoded = names
+        .iter()
+        .map(|name| utf8_percent_encode(name, NON_ALPHANUMERIC).to_string())
+        .collect::<Vec<_>>();
+
+    let mut path = format!("/{}", encoded.join("/"));
+    if is_collection && !path.ends_with('/') {
+        path.push('/');
+    }
+    path
+}
+
+fn render_multistatus(resources: &[DavResource]) -> Result<Vec<u8>, quick_xml::Error> {
+    let mut writer = Writer::new(Vec::new());
+    writer.write_event(Event::Decl(BytesDecl::new("1.0", Some("UTF-8"), None)))?;
+
+    let mut multistatus = BytesStart::new("D:multistatus");
+    multistatus.push_attribute(("xmlns:D", "DAV:"));
+    writer.write_event(Event::Start(multistatus))?;
+
+    for resource in resources {
+        writer.write_event(Event::Start(BytesStart::new("D:response")))?;
+
+        writer.write_event(Event::Start(BytesStart::new("D:href")))?;
+        writer.write_event(Event::Text(BytesText::new(&resource.href)))?;
+        writer.write_event(Event::End(BytesEnd::new("D:href")))?;
+
+        writer.write_event(Event::Start(BytesStart::new("D:propstat")))?;
+        writer.write_event(Event::Start(BytesStart::new("D:prop")))?;
+
+        writer.write_event(Event::Start(BytesStart::new("D:displayname")))?;
+        writer.write_event(Event::Text(BytesText::new(&resource.display_name)))?;
+        writer.write_event(Event::End(BytesEnd::new("D:displayname")))?;
+
+        writer.write_event(Event::Start(BytesStart::new("D:resourcetype")))?;
+        if resource.is_collection {
+            writer.write_event(Event::Empty(BytesStart::new("D:collection")))?;
+        }
+        writer.write_event(Event::End(BytesEnd::new("D:resourcetype")))?;
+
+        if let Some(length) = resource.content_length {
+            writer.write_event(Event::Start(BytesStart::new("D:getcontentlength")))?;
+            writer.write_event(Event::Text(BytesText::new(&length.to_string())))?;
+            writer.write_event(Event::End(BytesEnd::new("D:getcontentlength")))?;
+        }
+
+        if let Some(content_type) = &resource.content_type {
+            writer.write_event(Event::Start(BytesStart::new("D:getcontenttype")))?;
+            writer.write_event(Event::Text(BytesText::new(content_type)))?;
+            writer.write_event(Event::End(BytesEnd::new("D:getcontenttype")))?;
+        }
+
+        if let Some(last_modified) = &resource.last_modified {
+            writer.write_event(Event::Start(BytesStart::new("D:getlastmodified")))?;
+            writer.write_event(Event::Text(BytesText::new(last_modified)))?;
+            writer.write_event(Event::End(BytesEnd::new("D:getlastmodified")))?;
+        }
+
+        writer.write_event(Event::End(BytesEnd::new("D:prop")))?;
+
+        writer.write_event(Event::Start(BytesStart::new("D:status")))?;
+        writer.write_event(Event::Text(BytesText::new("HTTP/1.1 200 OK")))?;
+        writer.write_event(Event::End(BytesEnd::new("D:status")))?;
+
+        writer.write_event(Event::End(BytesEnd::new("D:propstat")))?;
+        writer.write_event(Event::End(BytesEnd::new("D:response")))?;
+    }
+
+    writer.write_event(Event::End(BytesEnd::new("D:multistatus")))?;
+    Ok(writer.into_inner())
+}
+
+fn format_http_date(value: chrono::NaiveDateTime) -> String {
+    let datetime = chrono::DateTime::<chrono::Utc>::from_naive_utc_and_offset(value, chrono::Utc);
+    datetime.format("%a, %d %b %Y %H:%M:%S GMT").to_string()
+}
+
+fn content_disposition(filename: &str) -> Option<String> {
+    if filename.is_empty() {
+        return None;
+    }
+
+    let sanitized: String = filename
+        .chars()
+        .map(|ch| match ch {
+            '"' | '\\' => '_',
+            _ => ch,
+        })
+        .collect();
+
+    let encoded =
+        percent_encoding::utf8_percent_encode(&sanitized, percent_encoding::NON_ALPHANUMERIC);
+    Some(format!(
+        "inline; filename=\"{}\"; filename*=UTF-8''{}",
+        sanitized, encoded
+    ))
+}
+
+struct WebDavFolderContents {
+    _folder: Option<Folder>,
+    subfolders: Vec<Folder>,
+    documents: Vec<DocumentEntry>,
+}
+
+struct DocumentEntry {
+    document: Document,
+    version: DocumentVersion,
+}
+
+struct DavResource {
+    href: String,
+    display_name: String,
+    is_collection: bool,
+    content_length: Option<i64>,
+    content_type: Option<String>,
+    last_modified: Option<String>,
+}
+
+enum ResolvedPath {
+    Root,
+    Folder {
+        folder: Folder,
+        chain: Vec<String>,
+    },
+    Document {
+        document: Document,
+        version: DocumentVersion,
+        chain: Vec<String>,
+    },
+}
+
+fn resolve_path(state: &AppState, segments: &[String]) -> AppResult<Option<ResolvedPath>> {
+    if segments.is_empty() {
+        return Ok(Some(ResolvedPath::Root));
+    }
+
+    let mut conn = state.db()?;
+    let mut parent_id: Option<Uuid> = None;
+    let mut chain: Vec<String> = Vec::new();
+    let mut current_folder: Option<Folder> = None;
+
+    for (index, segment) in segments.iter().enumerate() {
+        let is_last = index == segments.len() - 1;
+
+        match find_folder_by_name(&mut conn, parent_id, segment)? {
+            Some(folder) => {
+                if is_last {
+                    chain.push(folder.name.clone());
+                    return Ok(Some(ResolvedPath::Folder { folder, chain }));
+                }
+
+                parent_id = Some(folder.id);
+                chain.push(folder.name.clone());
+                current_folder = Some(folder);
+                continue;
+            }
+            None => {}
+        }
+
+        if is_last {
+            if let Some((document, version)) =
+                find_document_by_filename(&mut conn, parent_id, segment)?
+            {
+                chain.push(document.filename.clone());
+                return Ok(Some(ResolvedPath::Document {
+                    document,
+                    version,
+                    chain,
+                }));
+            }
+        }
+
+        if let Ok(uuid) = Uuid::parse_str(segment) {
+            if let Some(folder) = folders_dsl::folders
+                .find(uuid)
+                .first::<Folder>(&mut conn)
+                .optional()?
+            {
+                if folder.parent_id != parent_id {
+                    return Ok(None);
+                }
+                if !is_last {
+                    parent_id = Some(folder.id);
+                    chain.push(folder.name.clone());
+                    current_folder = Some(folder);
+                    continue;
+                } else {
+                    chain.push(folder.name.clone());
+                    return Ok(Some(ResolvedPath::Folder { folder, chain }));
+                }
+            }
+
+            if let Some((document, version)) = find_document_by_id(&mut conn, uuid)? {
+                if document.folder_id != parent_id {
+                    return Ok(None);
+                }
+                chain.push(document.filename.clone());
+                return Ok(Some(ResolvedPath::Document {
+                    document,
+                    version,
+                    chain,
+                }));
+            }
+        }
+
+        if is_last {
+            if let Some((document, version)) =
+                find_document_by_filename(&mut conn, parent_id, segment)?
+            {
+                chain.push(document.filename.clone());
+                return Ok(Some(ResolvedPath::Document {
+                    document,
+                    version,
+                    chain,
+                }));
+            }
+        }
+
+        return Ok(None);
+    }
+
+    Ok(current_folder.map(|folder| ResolvedPath::Folder { folder, chain }))
+}
+
+fn find_folder_by_name(
+    conn: &mut PgConnection,
+    parent_id: Option<Uuid>,
+    name: &str,
+) -> AppResult<Option<Folder>> {
+    let result = match parent_id {
+        Some(parent) => folders_dsl::folders
+            .filter(folders_dsl::parent_id.eq(Some(parent)))
+            .filter(folders_dsl::name.eq(name))
+            .first::<Folder>(conn)
+            .optional()?,
+        None => folders_dsl::folders
+            .filter(folders_dsl::parent_id.is_null())
+            .filter(folders_dsl::name.eq(name))
+            .first::<Folder>(conn)
+            .optional()?,
+    };
+
+    Ok(result)
+}
+
+fn find_document_by_filename(
+    conn: &mut PgConnection,
+    parent_id: Option<Uuid>,
+    filename: &str,
+) -> AppResult<Option<(Document, DocumentVersion)>> {
+    let mut query = documents_dsl::documents
+        .filter(documents_dsl::deleted_at.is_null())
+        .filter(documents_dsl::filename.eq(filename))
+        .into_boxed();
+
+    query = match parent_id {
+        Some(parent) => query.filter(documents_dsl::folder_id.eq(Some(parent))),
+        None => query.filter(documents_dsl::folder_id.is_null()),
+    };
+
+    if let Some(document) = query.first::<Document>(conn).optional()? {
+        let version = document_versions_dsl::document_versions
+            .find(document.current_version_id)
+            .first::<DocumentVersion>(conn)?;
+        return Ok(Some((document, version)));
+    }
+
+    Ok(None)
+}
+
+fn find_document_by_id(
+    conn: &mut PgConnection,
+    document_id: Uuid,
+) -> AppResult<Option<(Document, DocumentVersion)>> {
+    if let Some(document) = documents_dsl::documents
+        .filter(documents_dsl::deleted_at.is_null())
+        .find(document_id)
+        .first::<Document>(conn)
+        .optional()?
+    {
+        let version = document_versions_dsl::document_versions
+            .find(document.current_version_id)
+            .first::<DocumentVersion>(conn)?;
+        return Ok(Some((document, version)));
+    }
+
+    Ok(None)
+}

backend/src/s3.rs

@@ -0,0 +1,38 @@
+use anyhow::Result;
+use aws_config::meta::region::RegionProviderChain;
+use aws_credential_types::Credentials;
+use aws_sdk_s3::{
+    config::{Builder as S3ConfigBuilder, Region},
+    Client as S3Client,
+};
+
+use crate::config::AppConfig;
+
+pub async fn build_client(config: &AppConfig) -> Result<S3Client> {
+    let region = Region::new(config.aws_region.clone());
+    let region_provider = RegionProviderChain::first_try(Some(region))
+        .or_default_provider()
+        .or_else("us-east-1");
+
+    #[allow(deprecated)]
+    let mut loader = aws_config::from_env().region(region_provider);
+
+    if let Some(endpoint) = &config.aws_endpoint_url {
+        loader = loader.endpoint_url(endpoint);
+    }
+
+    if let (Some(access_key), Some(secret_key)) = (
+        config.aws_access_key_id.clone(),
+        config.aws_secret_access_key.clone(),
+    ) {
+        let credentials = Credentials::new(access_key, secret_key, None, None, "static");
+        loader = loader.credentials_provider(credentials);
+    }
+
+    let base_config = loader.load().await;
+    let s3_config = S3ConfigBuilder::from(&base_config)
+        .force_path_style(true)
+        .build();
+
+    Ok(S3Client::from_conf(s3_config))
+}

backend/src/schema.rs

@@ -0,0 +1,168 @@
+// @generated automatically by Diesel CLI.
+
+diesel::table! {
+    correspondents (id) {
+        id -> Uuid,
+        #[max_length = 255]
+        name -> Varchar,
+        metadata -> Jsonb,
+        created_at -> Timestamptz,
+        updated_at -> Timestamptz,
+    }
+}
+
+diesel::table! {
+    document_assets (id) {
+        id -> Uuid,
+        document_version_id -> Uuid,
+        asset_type -> Text,
+        s3_key -> Text,
+        mime_type -> Text,
+        metadata -> Jsonb,
+        created_at -> Timestamptz,
+    }
+}
+
+diesel::table! {
+    document_correspondents (document_id, correspondent_id, role) {
+        document_id -> Uuid,
+        correspondent_id -> Uuid,
+        #[max_length = 32]
+        role -> Varchar,
+        assigned_at -> Timestamptz,
+        assigned_by -> Nullable<Uuid>,
+    }
+}
+
+diesel::table! {
+    document_tags (document_id, tag_id) {
+        document_id -> Uuid,
+        tag_id -> Uuid,
+        assigned_at -> Timestamptz,
+        assigned_by -> Nullable<Uuid>,
+    }
+}
+
+diesel::table! {
+    document_versions (id) {
+        id -> Uuid,
+        document_id -> Uuid,
+        version_number -> Int4,
+        #[max_length = 500]
+        s3_key -> Varchar,
+        size_bytes -> Int8,
+        #[max_length = 64]
+        checksum -> Varchar,
+        created_at -> Timestamptz,
+        operations_summary -> Jsonb,
+        metadata -> Jsonb,
+    }
+}
+
+diesel::table! {
+    documents (id) {
+        id -> Uuid,
+        #[max_length = 255]
+        filename -> Varchar,
+        #[max_length = 255]
+        original_name -> Varchar,
+        #[max_length = 100]
+        content_type -> Nullable<Varchar>,
+        folder_id -> Nullable<Uuid>,
+        uploaded_at -> Timestamptz,
+        updated_at -> Timestamptz,
+        deleted_at -> Nullable<Timestamptz>,
+        metadata -> Jsonb,
+        issued_at -> Nullable<Timestamptz>,
+        #[max_length = 255]
+        title -> Varchar,
+        current_version_id -> Uuid,
+    }
+}
+
+diesel::table! {
+    folders (id) {
+        id -> Uuid,
+        #[max_length = 255]
+        name -> Varchar,
+        parent_id -> Nullable<Uuid>,
+        created_at -> Timestamptz,
+        updated_at -> Timestamptz,
+    }
+}
+
+diesel::table! {
+    jobs (id) {
+        id -> Uuid,
+        job_type -> Text,
+        payload -> Jsonb,
+        status -> Text,
+        attempts -> Int4,
+        run_after -> Timestamptz,
+        last_error -> Nullable<Text>,
+        created_at -> Timestamptz,
+        updated_at -> Timestamptz,
+    }
+}
+
+diesel::table! {
+    refresh_tokens (id) {
+        id -> Uuid,
+        user_id -> Uuid,
+        token_hash -> Text,
+        issued_at -> Timestamptz,
+        expires_at -> Timestamptz,
+        revoked_at -> Nullable<Timestamptz>,
+        created_at -> Timestamptz,
+        updated_at -> Timestamptz,
+    }
+}
+
+diesel::table! {
+    tags (id) {
+        id -> Uuid,
+        #[max_length = 100]
+        label -> Varchar,
+        #[max_length = 7]
+        color -> Nullable<Varchar>,
+        created_at -> Timestamptz,
+    }
+}
+
+diesel::table! {
+    users (id) {
+        id -> Uuid,
+        #[max_length = 100]
+        username -> Varchar,
+        #[max_length = 255]
+        password_hash -> Varchar,
+        #[max_length = 16]
+        role -> Varchar,
+        created_at -> Timestamptz,
+        updated_at -> Timestamptz,
+    }
+}
+
+diesel::joinable!(document_assets -> document_versions (document_version_id));
+diesel::joinable!(document_correspondents -> correspondents (correspondent_id));
+diesel::joinable!(document_correspondents -> documents (document_id));
+diesel::joinable!(document_correspondents -> users (assigned_by));
+diesel::joinable!(document_tags -> documents (document_id));
+diesel::joinable!(document_tags -> tags (tag_id));
+diesel::joinable!(document_tags -> users (assigned_by));
+diesel::joinable!(documents -> folders (folder_id));
+diesel::joinable!(refresh_tokens -> users (user_id));
+
+diesel::allow_tables_to_appear_in_same_query!(
+    correspondents,
+    document_assets,
+    document_correspondents,
+    document_tags,
+    document_versions,
+    documents,
+    folders,
+    jobs,
+    refresh_tokens,
+    tags,
+    users,
+);

backend/src/state.rs

@@ -0,0 +1,46 @@
+use std::sync::Arc;
+
+use diesel::{
+    pg::PgConnection,
+    r2d2::{ConnectionManager, PooledConnection},
+};
+
+use crate::{
+    auth::jwt::JwtService,
+    config::AppConfig,
+    db::PgPool,
+    error::{AppError, AppResult},
+    storage::ObjectStorage,
+};
+
+type PgPooledConnection = PooledConnection<ConnectionManager<PgConnection>>;
+
+#[derive(Clone)]
+pub struct AppState {
+    pub pool: PgPool,
+    pub config: Arc<AppConfig>,
+    pub storage: Arc<dyn ObjectStorage>,
+    pub jwt: JwtService,
+}
+
+impl AppState {
+    pub fn new(
+        pool: PgPool,
+        config: AppConfig,
+        storage: Arc<dyn ObjectStorage>,
+        jwt: JwtService,
+    ) -> Self {
+        Self {
+            pool,
+            config: Arc::new(config),
+            storage,
+            jwt,
+        }
+    }
+
+    pub fn db(&self) -> AppResult<PgPooledConnection> {
+        self.pool
+            .get()
+            .map_err(|err| AppError::internal(format!("database pool error: {err}")))
+    }
+}

backend/src/storage.rs

@@ -0,0 +1,121 @@
+use std::time::Duration;
+
+use anyhow::{Context, Result};
+use async_trait::async_trait;
+use aws_sdk_s3::presigning::PresigningConfig;
+use aws_sdk_s3::primitives::ByteStream;
+use aws_sdk_s3::Client as S3Client;
+
+#[async_trait]
+pub trait ObjectStorage: Send + Sync + 'static {
+    async fn put_object(
+        &self,
+        key: &str,
+        bytes: Vec<u8>,
+        content_type: Option<String>,
+        content_disposition: Option<String>,
+    ) -> Result<()>;
+
+    async fn presign_get_object(&self, key: &str, expires_in: Duration) -> Result<String>;
+
+    async fn get_object(&self, key: &str) -> Result<Vec<u8>>;
+
+    async fn delete_object(&self, key: &str) -> Result<()>;
+}
+
+pub struct S3Storage {
+    client: S3Client,
+    bucket: String,
+}
+
+impl S3Storage {
+    pub fn new(client: S3Client, bucket: impl Into<String>) -> Self {
+        Self {
+            client,
+            bucket: bucket.into(),
+        }
+    }
+}
+
+#[async_trait]
+impl ObjectStorage for S3Storage {
+    async fn put_object(
+        &self,
+        key: &str,
+        bytes: Vec<u8>,
+        content_type: Option<String>,
+        content_disposition: Option<String>,
+    ) -> Result<()> {
+        let mut request = self
+            .client
+            .put_object()
+            .bucket(&self.bucket)
+            .key(key)
+            .body(ByteStream::from(bytes));
+
+        if let Some(content_type) = content_type {
+            request = request.content_type(content_type);
+        }
+
+        if let Some(content_disposition) = content_disposition {
+            request = request.content_disposition(content_disposition);
+        }
+
+        request
+            .send()
+            .await
+            .context("failed to upload object to S3")?;
+
+        Ok(())
+    }
+
+    async fn presign_get_object(&self, key: &str, expires_in: Duration) -> Result<String> {
+        let presign_config = PresigningConfig::builder()
+            .expires_in(expires_in)
+            .build()
+            .context("failed to build S3 presigning config")?;
+
+        let presigned = self
+            .client
+            .get_object()
+            .bucket(&self.bucket)
+            .key(key)
+            .presigned(presign_config)
+            .await
+            .context("failed to generate presigned download URL")?;
+
+        Ok(presigned.uri().to_string())
+    }
+
+    async fn get_object(&self, key: &str) -> Result<Vec<u8>> {
+        let response = self
+            .client
+            .get_object()
+            .bucket(&self.bucket)
+            .key(key)
+            .send()
+            .await
+            .context("failed to download object from S3")?;
+
+        let bytes = response
+            .body
+            .collect()
+            .await
+            .context("failed to read object stream")?
+            .into_bytes()
+            .to_vec();
+
+        Ok(bytes)
+    }
+
+    async fn delete_object(&self, key: &str) -> Result<()> {
+        self.client
+            .delete_object()
+            .bucket(&self.bucket)
+            .key(key)
+            .send()
+            .await
+            .context("failed to delete object from S3")?;
+        Ok(())
+    }
+}

backend/src/utils/json.rs

@@ -0,0 +1,16 @@
+use serde_json::Value;
+
+pub enum NullableValue {
+    Omitted,
+    Null,
+    String(String),
+}
+
+pub fn classify_nullable(optional_value: Option<&Value>) -> Result<NullableValue, String> {
+    match optional_value {
+        None => Ok(NullableValue::Omitted),
+        Some(Value::Null) => Ok(NullableValue::Null),
+        Some(Value::String(s)) => Ok(NullableValue::String(s.to_owned())),
+        Some(other) => Err(format!("expected string or null, got {other}")),
+    }
+}

backend/src/utils/mod.rs

@@ -0,0 +1 @@
+pub mod json;

backend/src/workers/analyze.rs

@@ -0,0 +1,203 @@
+use std::{collections::HashSet, sync::Arc, time::Duration};
+
+use async_trait::async_trait;
+use diesel::prelude::*;
+use serde::Deserialize;
+use serde_json::{json, Map, Value};
+use tokio::task;
+use tracing::{error, warn};
+use uuid::Uuid;
+
+use super::ocr::{document_is_pdf, OCR_TEXT_ASSET_TYPE};
+use crate::{
+    jobs::{enqueue_job, JOB_ANALYZE_DOCUMENT, JOB_GENERATE_OCR_TEXT, JOB_GENERATE_THUMBNAILS},
+    models::{Document, DocumentAsset, DocumentVersion},
+    schema::{document_assets, document_versions, documents},
+    state::AppState,
+};
+
+use super::{JobExecution, JobHandler};
+
+#[derive(Debug, Deserialize)]
+struct AnalyzePayload {
+    document_id: Uuid,
+    document_version_id: Uuid,
+    #[serde(default)]
+    force: bool,
+}
+
+pub struct AnalyzeDocumentJob;
+
+impl AnalyzeDocumentJob {
+    pub fn new() -> Self {
+        Self
+    }
+}
+
+#[async_trait]
+impl JobHandler for AnalyzeDocumentJob {
+    fn job_type(&self) -> &'static str {
+        JOB_ANALYZE_DOCUMENT
+    }
+
+    async fn handle(&self, state: Arc<AppState>, job: crate::models::Job) -> JobExecution {
+        let payload: AnalyzePayload = match serde_json::from_value(job.payload.clone()) {
+            Ok(payload) => payload,
+            Err(err) => {
+                return JobExecution::Failed {
+                    error: format!("invalid analyze payload: {err}"),
+                }
+            }
+        };
+
+        let state_clone = state.clone();
+        match task::spawn_blocking(move || analyze_document(state_clone, payload)).await {
+            Ok(Ok(execution)) => execution,
+            Ok(Err(err)) => {
+                warn!(job_id = %job.id, error = %err, "analyze job will retry");
+                JobExecution::Retry {
+                    delay: Duration::from_secs(30),
+                    error: err,
+                }
+            }
+            Err(join_err) => {
+                error!(job_id = %job.id, error = %join_err, "analyze task panicked");
+                JobExecution::Retry {
+                    delay: Duration::from_secs(60),
+                    error: format!("worker panicked: {join_err}"),
+                }
+            }
+        }
+    }
+}
+
+fn analyze_document(state: Arc<AppState>, payload: AnalyzePayload) -> Result<JobExecution, String> {
+    let mut conn = state.db().map_err(|err| format!("{err:?}"))?;
+
+    let version: DocumentVersion = document_versions::table
+        .find(payload.document_version_id)
+        .first(&mut conn)
+        .map_err(|err| format!("{err:?}"))?;
+
+    if version.document_id != payload.document_id {
+        return Err("document/version mismatch".into());
+    }
+
+    let document: Document = documents::table
+        .find(payload.document_id)
+        .first(&mut conn)
+        .map_err(|err| format!("{err:?}"))?;
+
+    let (supported, reason) = determine_thumbnail_support(&document);
+    let ocr_supported = document_is_pdf(&document);
+
+    let existing_ocr: Option<DocumentAsset> = document_assets::table
+        .filter(document_assets::document_version_id.eq(payload.document_version_id))
+        .filter(document_assets::asset_type.eq(OCR_TEXT_ASSET_TYPE))
+        .first(&mut conn)
+        .optional()
+        .map_err(|err| format!("{err:?}"))?;
+
+    let skip_ocr = existing_ocr.is_some() && !payload.force;
+
+    let mut summary_map = match version.operations_summary {
+        Value::Object(map) => map,
+        _ => Map::new(),
+    };
+    summary_map.insert("thumbnail_supported".to_string(), Value::Bool(supported));
+    if let Some(reason) = reason {
+        summary_map.insert("thumbnail_reason".to_string(), Value::String(reason));
+    } else {
+        summary_map.remove("thumbnail_reason");
+    }
+
+    summary_map.insert("ocr_supported".to_string(), Value::Bool(ocr_supported));
+    if ocr_supported {
+        summary_map.remove("ocr_reason");
+    } else {
+        summary_map.insert(
+            "ocr_reason".to_string(),
+            Value::String("document is not a PDF".into()),
+        );
+    }
+
+    diesel::update(document_versions::table.find(version.id))
+        .set(document_versions::operations_summary.eq(Value::Object(summary_map)))
+        .execute(&mut conn)
+        .map_err(|err| format!("{err:?}"))?;
+
+    if supported {
+        let enqueue_result = enqueue_job(
+            &mut conn,
+            JOB_GENERATE_THUMBNAILS,
+            json!({
+                "document_id": payload.document_id,
+                "document_version_id": payload.document_version_id,
+                "force": payload.force,
+            }),
+            None,
+        );
+
+        if let Err(err) = enqueue_result {
+            return Err(err.to_string());
+        }
+    }
+
+    if ocr_supported && !skip_ocr {
+        let enqueue_result = enqueue_job(
+            &mut conn,
+            JOB_GENERATE_OCR_TEXT,
+            json!({
+                "document_id": payload.document_id,
+                "document_version_id": payload.document_version_id,
+                "force": payload.force,
+            }),
+            None,
+        );
+
+        if let Err(err) = enqueue_result {
+            return Err(err.to_string());
+        }
+    }
+
+    Ok(JobExecution::Success)
+}
+
+pub(crate) fn determine_thumbnail_support(document: &Document) -> (bool, Option<String>) {
+    let supported_mimes: HashSet<&'static str> = [
+        "image/jpeg",
+        "image/png",
+        "image/gif",
+        "image/tiff",
+        "image/bmp",
+        "image/webp",
+        "application/pdf",
+    ]
+    .into_iter()
+    .collect();
+
+    if let Some(ref content_type) = document.content_type {
+        if supported_mimes.contains(content_type.as_str()) {
+            return (true, None);
+        }
+    }
+
+    if let Some(ext) = document
+        .original_name
+        .rsplit('.')
+        .next()
+        .map(|ext| ext.to_ascii_lowercase())
+    {
+        let supported_exts = [
+            "jpg", "jpeg", "png", "gif", "tif", "tiff", "bmp", "webp", "pdf",
+        ];
+        if supported_exts.contains(&ext.as_str()) {
+            return (true, None);
+        }
+    }
+
+    (
+        false,
+        Some("content type not supported for thumbnails".into()),
+    )
+}

backend/src/workers/index.rs

@@ -0,0 +1,204 @@
+use std::sync::Arc;
+use std::time::Duration;
+
+use async_trait::async_trait;
+use diesel::prelude::*;
+use reqwest::Client;
+use serde::Deserialize;
+use serde_json::json;
+use tokio::task;
+use tracing::{error, warn};
+use uuid::Uuid;
+
+use crate::{
+    jobs::JOB_INDEX_DOCUMENT_TEXT,
+    models::{Document, DocumentAsset, DocumentVersion},
+    schema::{document_assets, document_versions, documents},
+    state::AppState,
+};
+
+use super::{ocr::OCR_TEXT_ASSET_TYPE, JobExecution, JobHandler};
+
+#[derive(Debug, Deserialize)]
+struct IndexPayload {
+    document_id: Uuid,
+    document_version_id: Uuid,
+}
+
+pub struct IndexDocumentTextJob;
+
+impl IndexDocumentTextJob {
+    pub fn new() -> Self {
+        Self
+    }
+}
+
+#[async_trait]
+impl JobHandler for IndexDocumentTextJob {
+    fn job_type(&self) -> &'static str {
+        JOB_INDEX_DOCUMENT_TEXT
+    }
+
+    async fn handle(&self, state: Arc<AppState>, job: crate::models::Job) -> JobExecution {
+        let payload: IndexPayload = match serde_json::from_value(job.payload.clone()) {
+            Ok(payload) => payload,
+            Err(err) => {
+                return JobExecution::Failed {
+                    error: format!("invalid index payload: {err}"),
+                }
+            }
+        };
+
+        let quickwit_endpoint = match &state.config.quickwit_endpoint {
+            Some(endpoint) => endpoint.clone(),
+            None => {
+                warn!("quickwit endpoint missing; skipping indexing");
+                return JobExecution::Success;
+            }
+        };
+
+        let quickwit_index = match &state.config.quickwit_index {
+            Some(index) => index.clone(),
+            None => {
+                warn!("quickwit index missing; skipping indexing");
+                return JobExecution::Success;
+            }
+        };
+
+        let client = Client::new();
+
+        let state_clone = state.clone();
+        let context = match task::spawn_blocking(move || load_context(state_clone, &payload)).await
+        {
+            Ok(Ok(ctx)) => ctx,
+            Ok(Err(err)) => {
+                warn!(job_id = %job.id, error = %err, "index job will retry");
+                return JobExecution::Retry {
+                    delay: Duration::from_secs(30),
+                    error: err,
+                };
+            }
+            Err(join_err) => {
+                error!(job_id = %job.id, error = %join_err, "index task panicked");
+                return JobExecution::Retry {
+                    delay: Duration::from_secs(60),
+                    error: format!("worker panicked: {join_err}"),
+                };
+            }
+        };
+
+        if context.text_asset.is_none() {
+            warn!(job_id = %job.id, "missing OCR text asset; failing indexing job");
+            return JobExecution::Failed {
+                error: "missing OCR text asset".into(),
+            };
+        }
+
+        let asset = context.text_asset.unwrap();
+        let text = match state.storage.get_object(&asset.s3_key).await {
+            Ok(bytes) => match String::from_utf8(bytes) {
+                Ok(text) => text,
+                Err(err) => {
+                    warn!(job_id = %job.id, error = %err, "ocr text not valid UTF-8");
+                    return JobExecution::Failed {
+                        error: "ocr text not valid UTF-8".into(),
+                    };
+                }
+            },
+            Err(err) => {
+                warn!(job_id = %job.id, error = %err, "failed to download ocr text");
+                return JobExecution::Retry {
+                    delay: Duration::from_secs(30),
+                    error: err.to_string(),
+                };
+            }
+        };
+
+        if text.trim().is_empty() {
+            warn!(job_id = %job.id, "ocr text empty; skipping");
+            return JobExecution::Failed {
+                error: "ocr text empty".into(),
+            };
+        }
+
+        let client = client;
+        let url = format!(
+            "{}/api/v1/{}/ingest?commit=auto",
+            quickwit_endpoint, quickwit_index
+        );
+        let payload = json!({
+            "document_id": context.document.id,
+            "version_id": context.version.id,
+            "title": context.document.title.to_lowercase(),
+            "text": text.to_lowercase()
+        });
+
+        let body = serde_json::to_string(&payload).unwrap();
+
+        match client
+            .post(&url)
+            .header("content-type", "application/x-ndjson")
+            .body(format!("{}\n", body))
+            .send()
+            .await
+        {
+            Ok(response) => {
+                if response.status().is_success() {
+                    JobExecution::Success
+                } else {
+                    let status = response.status();
+                    let body = response.text().await.unwrap_or_default();
+                    warn!(job_id = %job.id, %status, %body, "quickwit ingest failed");
+                    JobExecution::Retry {
+                        delay: Duration::from_secs(30),
+                        error: format!("quickwit ingest failed with status {status}"),
+                    }
+                }
+            }
+            Err(err) => {
+                warn!(job_id = %job.id, error = %err, "quickwit request failed");
+                JobExecution::Retry {
+                    delay: Duration::from_secs(30),
+                    error: err.to_string(),
+                }
+            }
+        }
+    }
+}
+
+struct IndexContext {
+    document: Document,
+    version: DocumentVersion,
+    text_asset: Option<DocumentAsset>,
+}
+
+fn load_context(state: Arc<AppState>, payload: &IndexPayload) -> Result<IndexContext, String> {
+    let mut conn = state.db().map_err(|err| format!("{err:?}"))?;
+
+    let version: DocumentVersion = document_versions::table
+        .find(payload.document_version_id)
+        .first(&mut conn)
+        .map_err(|err| format!("{err:?}"))?;
+
+    if version.document_id != payload.document_id {
+        return Err("document/version mismatch".into());
+    }
+
+    let document: Document = documents::table
+        .find(payload.document_id)
+        .first(&mut conn)
+        .map_err(|err| format!("{err:?}"))?;
+
+    let text_asset: Option<DocumentAsset> = document_assets::table
+        .filter(document_assets::document_version_id.eq(payload.document_version_id))
+        .filter(document_assets::asset_type.eq(OCR_TEXT_ASSET_TYPE))
+        .first(&mut conn)
+        .optional()
+        .map_err(|err| format!("{err:?}"))?;
+
+    Ok(IndexContext {
+        document,
+        version,
+        text_asset,
+    })
+}

backend/src/workers/mod.rs

@@ -0,0 +1,136 @@
+use std::{collections::HashMap, sync::Arc, time::Duration};
+
+use async_trait::async_trait;
+use tokio::time::sleep;
+use tracing::{error, info, warn};
+
+use crate::{
+    jobs::{mark_job_failed, mark_job_succeeded, reserve_job, retry_job_after, JobQueueError},
+    models::Job,
+    state::AppState,
+};
+
+pub mod analyze;
+pub mod index;
+pub mod ocr;
+pub mod thumbnails;
+
+#[derive(Debug)]
+pub enum JobExecution {
+    Success,
+    Retry { delay: Duration, error: String },
+    Failed { error: String },
+}
+
+#[async_trait]
+pub trait JobHandler: Send + Sync {
+    fn job_type(&self) -> &'static str;
+    async fn handle(&self, state: Arc<AppState>, job: Job) -> JobExecution;
+}
+
+pub struct Worker {
+    state: Arc<AppState>,
+    handlers: HashMap<&'static str, Arc<dyn JobHandler>>,
+    poll_interval: Duration,
+}
+
+impl Worker {
+    pub fn new(
+        state: Arc<AppState>,
+        handlers: Vec<Arc<dyn JobHandler>>,
+        poll_interval: Duration,
+    ) -> Self {
+        let map = handlers
+            .into_iter()
+            .map(|handler| (handler.job_type(), handler))
+            .collect();
+        Self {
+            state,
+            handlers: map,
+            poll_interval,
+        }
+    }
+
+    pub async fn run(&self) {
+        info!("worker started");
+        loop {
+            match self.tick().await {
+                Ok(true) => {}
+                Ok(false) => sleep(self.poll_interval).await,
+                Err(err) => {
+                    error!(error = %err, "worker tick failed");
+                    sleep(self.poll_interval).await;
+                }
+            }
+        }
+    }
+
+    async fn tick(&self) -> Result<bool, JobQueueError> {
+        let job_types: Vec<&str> = self.handlers.keys().copied().collect();
+        if job_types.is_empty() {
+            return Ok(false);
+        }
+
+        let mut conn = match self.state.db() {
+            Ok(conn) => conn,
+            Err(err) => {
+                error!(?err, "failed to obtain database connection in worker");
+                return Ok(false);
+            }
+        };
+
+        let job_opt = reserve_job(&mut conn, &job_types)?;
+        drop(conn);
+
+        if let Some(job) = job_opt {
+            if let Some(handler) = self.handlers.get(job.job_type.as_str()) {
+                let result = handler.handle(self.state.clone(), job.clone()).await;
+                match result {
+                    JobExecution::Success => {
+                        if let Ok(mut conn) = self.state.db() {
+                            mark_job_succeeded(&mut conn, job.id)?;
+                            info!(job_id = %job.id, job_type = %job.job_type, "job completed successfully");
+                        } else {
+                            error!("failed to mark job succeeded due to pool error");
+                        }
+                    }
+                    JobExecution::Retry { delay, error } => {
+                        warn!(job_id = %job.id, job_type = %job.job_type, %error, "job will retry");
+                        if let Ok(mut conn) = self.state.db() {
+                            retry_job_after(&mut conn, job.id, delay, &error)?;
+                        } else {
+                            error!("failed to requeue job for retry due to pool error");
+                        }
+                    }
+                    JobExecution::Failed { error } => {
+                        error!(job_id = %job.id, job_type = %job.job_type, %error, "job failed");
+                        if let Ok(mut conn) = self.state.db() {
+                            mark_job_failed(&mut conn, job.id, &error)?;
+                        } else {
+                            error!("failed to mark job failed due to pool error");
+                        }
+                    }
+                }
+            } else {
+                error!(job_type = %job.job_type, "no handler registered for job type");
+                if let Ok(mut conn) = self.state.db() {
+                    mark_job_failed(&mut conn, job.id, "no handler registered")?;
+                } else {
+                    error!("failed to mark job failed for missing handler due to pool error");
+                }
+            }
+            Ok(true)
+        } else {
+            Ok(false)
+        }
+    }
+}
+
+pub fn default_handlers() -> Vec<Arc<dyn JobHandler>> {
+    vec![
+        Arc::new(analyze::AnalyzeDocumentJob::new()),
+        Arc::new(thumbnails::GenerateThumbnailsJob::new()),
+        Arc::new(ocr::GenerateOcrTextJob::new()),
+        Arc::new(index::IndexDocumentTextJob::new()),
+    ]
+}

backend/src/workers/ocr.rs

@@ -0,0 +1,438 @@
+use std::{
+    fmt, fs,
+    io::{ErrorKind, Write},
+    process::Command,
+    sync::Arc,
+    time::Duration,
+};
+
+use async_trait::async_trait;
+use chrono::Utc;
+use diesel::{pg::upsert::excluded, prelude::*};
+use pdfium_render::prelude::*;
+use serde::Deserialize;
+use serde_json::json;
+use tempfile::NamedTempFile;
+use tokio::task;
+use tracing::{error, info, warn};
+use uuid::Uuid;
+
+use crate::{
+    jobs::{enqueue_job, JOB_GENERATE_OCR_TEXT, JOB_INDEX_DOCUMENT_TEXT},
+    models::{Document, DocumentAsset, DocumentVersion, NewDocumentAsset},
+    schema::{document_assets, document_versions, documents},
+    state::AppState,
+};
+
+use super::{JobExecution, JobHandler};
+
+pub const OCR_TEXT_ASSET_TYPE: &str = "ocr-text";
+const MIN_TEXT_LENGTH: usize = 50;
+
+#[derive(Clone, Debug, Deserialize)]
+struct OcrPayload {
+    document_id: Uuid,
+    document_version_id: Uuid,
+    #[serde(default)]
+    force: bool,
+}
+
+pub struct GenerateOcrTextJob;
+
+impl GenerateOcrTextJob {
+    pub fn new() -> Self {
+        Self
+    }
+}
+
+#[async_trait]
+impl JobHandler for GenerateOcrTextJob {
+    fn job_type(&self) -> &'static str {
+        JOB_GENERATE_OCR_TEXT
+    }
+
+    async fn handle(&self, state: Arc<AppState>, job: crate::models::Job) -> JobExecution {
+        let payload: OcrPayload = match serde_json::from_value(job.payload.clone()) {
+            Ok(payload) => payload,
+            Err(err) => {
+                return JobExecution::Failed {
+                    error: format!("invalid OCR payload: {err}"),
+                }
+            }
+        };
+
+        let state_clone = state.clone();
+        let payload_clone = payload.clone();
+        let context =
+            match task::spawn_blocking(move || load_ocr_context(state_clone, &payload_clone)).await
+            {
+                Ok(Ok(ctx)) => ctx,
+                Ok(Err(err)) => {
+                    warn!(job_id = %job.id, error = %err, "ocr job will retry");
+                    return JobExecution::Retry {
+                        delay: Duration::from_secs(30),
+                        error: err,
+                    };
+                }
+                Err(join_err) => {
+                    error!(job_id = %job.id, error = %join_err, "ocr task panicked");
+                    return JobExecution::Retry {
+                        delay: Duration::from_secs(60),
+                        error: format!("worker panicked: {join_err}"),
+                    };
+                }
+            };
+
+        if context.skip {
+            info!(job_id = %job.id, "ocr already present; skipping");
+            return JobExecution::Success;
+        }
+
+        let bytes = match state.storage.get_object(&context.version.s3_key).await {
+            Ok(bytes) => bytes,
+            Err(err) => {
+                warn!(job_id = %job.id, error = %err, "failed to fetch document for ocr");
+                return JobExecution::Retry {
+                    delay: Duration::from_secs(30),
+                    error: err.to_string(),
+                };
+            }
+        };
+
+        let doc_meta = PdfDocumentMeta {
+            content_type: context.document.content_type.clone(),
+            original_name: context.document.original_name.clone(),
+        };
+
+        let generation =
+            match task::spawn_blocking(move || generate_ocr_text(&doc_meta, &bytes)).await {
+                Ok(result) => result,
+                Err(join_err) => {
+                    error!(job_id = %job.id, error = %join_err, "ocr text task panicked");
+                    return JobExecution::Retry {
+                        delay: Duration::from_secs(60),
+                        error: format!("worker panicked: {join_err}"),
+                    };
+                }
+            };
+
+        let Some(generation) = generation else {
+            warn!(job_id = %job.id, "no text extracted from document; failing job");
+            return JobExecution::Failed {
+                error: "no text extracted and OCR unavailable".into(),
+            };
+        };
+
+        let asset_id = context
+            .existing_asset
+            .as_ref()
+            .map(|asset| asset.id)
+            .unwrap_or_else(Uuid::new_v4);
+
+        let s3_key = format!(
+            "documents/{}/v{}/assets/{}/{}",
+            context.document.id, context.version.version_number, OCR_TEXT_ASSET_TYPE, asset_id
+        );
+
+        if let Err(err) = state
+            .storage
+            .put_object(
+                &s3_key,
+                generation.text.into_bytes(),
+                Some("text/plain".into()),
+                None,
+            )
+            .await
+        {
+            warn!(job_id = %job.id, error = %err, "failed to upload ocr text");
+            return JobExecution::Retry {
+                delay: Duration::from_secs(30),
+                error: err.to_string(),
+            };
+        }
+
+        let state_clone = state.clone();
+        match task::spawn_blocking(move || {
+            persist_ocr_metadata(state_clone, &context, asset_id, &s3_key, generation.source)
+        })
+        .await
+        {
+            Ok(Ok(())) => {
+                if state.config.quickwit_endpoint.is_some() && state.config.quickwit_index.is_some()
+                {
+                    if let Err(err) = enqueue_index_job(&state, &payload) {
+                        warn!(job_id = %job.id, error = %err, "failed to enqueue index job");
+                    }
+                }
+                JobExecution::Success
+            }
+            Ok(Err(err)) => {
+                warn!(job_id = %job.id, error = %err, "failed to persist ocr metadata");
+                JobExecution::Retry {
+                    delay: Duration::from_secs(30),
+                    error: err,
+                }
+            }
+            Err(join_err) => {
+                error!(job_id = %job.id, error = %join_err, "ocr metadata task panicked");
+                JobExecution::Retry {
+                    delay: Duration::from_secs(30),
+                    error: format!("metadata update panic: {join_err}"),
+                }
+            }
+        }
+    }
+}
+
+struct PdfDocumentMeta {
+    content_type: Option<String>,
+    original_name: String,
+}
+
+struct OcrContext {
+    document: Document,
+    version: DocumentVersion,
+    existing_asset: Option<DocumentAsset>,
+    skip: bool,
+}
+
+struct OcrGeneration {
+    text: String,
+    source: &'static str,
+}
+
+fn load_ocr_context(state: Arc<AppState>, payload: &OcrPayload) -> Result<OcrContext, String> {
+    let mut conn = state.db().map_err(|err| format!("{err:?}"))?;
+
+    let version: DocumentVersion = document_versions::table
+        .find(payload.document_version_id)
+        .first(&mut conn)
+        .map_err(|err| format!("{err:?}"))?;
+
+    if version.document_id != payload.document_id {
+        return Err("document/version mismatch".into());
+    }
+
+    let document: Document = documents::table
+        .find(payload.document_id)
+        .first(&mut conn)
+        .map_err(|err| format!("{err:?}"))?;
+
+    let existing: Option<DocumentAsset> = document_assets::table
+        .filter(document_assets::document_version_id.eq(payload.document_version_id))
+        .filter(document_assets::asset_type.eq(OCR_TEXT_ASSET_TYPE))
+        .first(&mut conn)
+        .optional()
+        .map_err(|err| format!("{err:?}"))?;
+
+    let is_pdf = document_is_pdf(&document);
+    if !is_pdf {
+        return Ok(OcrContext {
+            document,
+            version,
+            existing_asset: existing,
+            skip: true,
+        });
+    }
+
+    let skip = existing.is_some() && !payload.force;
+
+    Ok(OcrContext {
+        document,
+        version,
+        existing_asset: existing,
+        skip,
+    })
+}
+
+fn generate_ocr_text(meta: &PdfDocumentMeta, bytes: &[u8]) -> Option<OcrGeneration> {
+    if !document_meta_is_pdf(meta) {
+        return None;
+    }
+
+    if let Ok(text) = extract_pdf_text(bytes) {
+        if text.trim().chars().count() >= MIN_TEXT_LENGTH {
+            return Some(OcrGeneration {
+                text,
+                source: "pdf-text",
+            });
+        }
+    }
+
+    match run_ocr(bytes) {
+        Ok(Some(text)) => Some(OcrGeneration {
+            text,
+            source: "ocr",
+        }),
+        Ok(None) => None,
+        Err(OcrError::BinaryMissing) => {
+            warn!("ocrmypdf not installed; cannot perform OCR");
+            None
+        }
+        Err(err) => {
+            warn!(error = ?err, "ocr command failed");
+            None
+        }
+    }
+}
+
+fn extract_pdf_text(bytes: &[u8]) -> Result<String, String> {
+    let pdfium = Pdfium::default();
+    let document = pdfium
+        .load_pdf_from_byte_slice(bytes, None)
+        .map_err(|err| format!("load pdf: {err}"))?;
+
+    let mut combined = String::new();
+    let pages = document.pages();
+    for page_index in 0..pages.len() {
+        let page = pages
+            .get(page_index)
+            .map_err(|err| format!("load page {page_index}: {err}"))?;
+        if let Ok(page_text) = page.text() {
+            for segment in page_text.segments().iter() {
+                combined.push_str(&segment.text());
+                combined.push('\n');
+            }
+        };
+    }
+
+    Ok(combined)
+}
+
+#[derive(Debug)]
+enum OcrError {
+    BinaryMissing,
+    Failed(String),
+}
+
+impl fmt::Display for OcrError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            OcrError::BinaryMissing => write!(f, "ocrmypdf binary not found"),
+            OcrError::Failed(msg) => write!(f, "ocr failed: {msg}"),
+        }
+    }
+}
+
+fn run_ocr(bytes: &[u8]) -> Result<Option<String>, OcrError> {
+    let mut input = NamedTempFile::new().map_err(|err| OcrError::Failed(err.to_string()))?;
+    input
+        .write_all(bytes)
+        .map_err(|err| OcrError::Failed(err.to_string()))?;
+    input
+        .flush()
+        .map_err(|err| OcrError::Failed(err.to_string()))?;
+
+    let output_pdf = NamedTempFile::new().map_err(|err| OcrError::Failed(err.to_string()))?;
+    let sidecar = NamedTempFile::new().map_err(|err| OcrError::Failed(err.to_string()))?;
+
+    let status = Command::new("ocrmypdf")
+        .arg("--sidecar")
+        .arg(sidecar.path())
+        .arg("--skip-text")
+        .arg(input.path())
+        .arg(output_pdf.path())
+        .output();
+
+    match status {
+        Ok(output) => {
+            if !output.status.success() {
+                return Err(OcrError::Failed(format!(
+                    "ocrmypdf failed: exit={} stderr={}",
+                    output.status,
+                    String::from_utf8_lossy(&output.stderr)
+                )));
+            }
+
+            let text = fs::read_to_string(sidecar.path())
+                .map_err(|err| OcrError::Failed(err.to_string()))?;
+            if text.trim().chars().count() >= MIN_TEXT_LENGTH {
+                Ok(Some(text))
+            } else {
+                Ok(None)
+            }
+        }
+        Err(err) => {
+            if err.kind() == ErrorKind::NotFound {
+                Err(OcrError::BinaryMissing)
+            } else {
+                Err(OcrError::Failed(err.to_string()))
+            }
+        }
+    }
+}
+
+fn persist_ocr_metadata(
+    state: Arc<AppState>,
+    context: &OcrContext,
+    asset_id: Uuid,
+    s3_key: &str,
+    source: &'static str,
+) -> Result<(), String> {
+    let mut conn = state.db().map_err(|err| format!("{err:?}"))?;
+
+    let new_asset = NewDocumentAsset {
+        id: asset_id,
+        document_version_id: context.version.id,
+        asset_type: OCR_TEXT_ASSET_TYPE.to_string(),
+        s3_key: s3_key.to_string(),
+        mime_type: "text/plain".to_string(),
+        metadata: json!({
+            "generated_at": Utc::now().to_rfc3339(),
+            "source": source,
+        }),
+    };
+
+    diesel::insert_into(document_assets::table)
+        .values(&new_asset)
+        .on_conflict((
+            document_assets::document_version_id,
+            document_assets::asset_type,
+        ))
+        .do_update()
+        .set((
+            document_assets::s3_key.eq(excluded(document_assets::s3_key)),
+            document_assets::mime_type.eq(excluded(document_assets::mime_type)),
+            document_assets::metadata.eq(excluded(document_assets::metadata)),
+        ))
+        .execute(&mut conn)
+        .map_err(|err| format!("{err:?}"))?;
+
+    Ok(())
+}
+
+fn enqueue_index_job(state: &AppState, payload: &OcrPayload) -> Result<(), String> {
+    let mut conn = state.db().map_err(|err| format!("{err:?}"))?;
+    enqueue_job(
+        &mut conn,
+        JOB_INDEX_DOCUMENT_TEXT,
+        json!({
+            "document_id": payload.document_id,
+            "document_version_id": payload.document_version_id,
+        }),
+        None,
+    )
+    .map(|_| ())
+    .map_err(|err| err.to_string())
+}
+
+pub fn document_is_pdf(document: &Document) -> bool {
+    document_meta_is_pdf(&PdfDocumentMeta {
+        content_type: document.content_type.clone(),
+        original_name: document.original_name.clone(),
+    })
+}
+
+fn document_meta_is_pdf(meta: &PdfDocumentMeta) -> bool {
+    if let Some(content_type) = &meta.content_type {
+        if content_type.eq_ignore_ascii_case("application/pdf") {
+            return true;
+        }
+    }
+
+    meta.original_name
+        .rsplit('.')
+        .next()
+        .map(|ext| ext.eq_ignore_ascii_case("pdf"))
+        .unwrap_or(false)
+}

backend/src/workers/thumbnails.rs

@@ -0,0 +1,535 @@
+use std::{convert::TryInto, io::Cursor, panic, sync::Arc, time::Duration};
+
+use async_trait::async_trait;
+use chrono::Utc;
+use diesel::{pg::upsert::excluded, prelude::*};
+use image::{GenericImageView, ImageFormat, ImageReader};
+use pdfium_render::prelude::*;
+use serde::Deserialize;
+use serde_json::{json, Map, Value};
+use tokio::task;
+use tracing::{error, info, warn};
+use uuid::Uuid;
+
+use crate::{
+    jobs::JOB_GENERATE_THUMBNAILS,
+    models::{Document, DocumentAsset, DocumentVersion, NewDocumentAsset},
+    schema::{document_assets, document_versions, documents},
+    state::AppState,
+};
+
+use super::{analyze::determine_thumbnail_support, JobExecution, JobHandler};
+
+const THUMBNAIL_WIDTH: u32 = 512;
+const THUMBNAIL_HEIGHT: u32 = 512;
+const PREVIEW_WIDTH: u32 = THUMBNAIL_WIDTH * 4;
+const PREVIEW_HEIGHT: u32 = THUMBNAIL_HEIGHT * 4;
+const THUMBNAIL_ASSET_TYPE: &str = "thumbnail";
+const PREVIEW_ASSET_TYPE: &str = "preview";
+
+#[derive(Debug, Deserialize)]
+struct ThumbnailPayload {
+    document_id: Uuid,
+    document_version_id: Uuid,
+    #[serde(default)]
+    force: bool,
+}
+
+pub struct GenerateThumbnailsJob;
+
+impl GenerateThumbnailsJob {
+    pub fn new() -> Self {
+        Self
+    }
+}
+
+#[async_trait]
+impl JobHandler for GenerateThumbnailsJob {
+    fn job_type(&self) -> &'static str {
+        JOB_GENERATE_THUMBNAILS
+    }
+
+    async fn handle(&self, state: Arc<AppState>, job: crate::models::Job) -> JobExecution {
+        let payload: ThumbnailPayload = match serde_json::from_value(job.payload.clone()) {
+            Ok(p) => p,
+            Err(err) => {
+                return JobExecution::Failed {
+                    error: format!("invalid thumbnail payload: {err}"),
+                }
+            }
+        };
+
+        let state_clone = state.clone();
+        let initial =
+            match task::spawn_blocking(move || load_thumbnail_context(state_clone, &payload)).await
+            {
+                Ok(Ok(ctx)) => ctx,
+                Ok(Err(err)) => {
+                    warn!(job_id = %job.id, error = %err, "thumbnail job will retry");
+                    return JobExecution::Retry {
+                        delay: Duration::from_secs(30),
+                        error: err,
+                    };
+                }
+                Err(join_err) => {
+                    error!(job_id = %job.id, error = %join_err, "thumbnail task panicked");
+                    return JobExecution::Retry {
+                        delay: Duration::from_secs(60),
+                        error: format!("worker panicked: {join_err}"),
+                    };
+                }
+            };
+
+        if initial.skip {
+            info!(job_id = %job.id, "thumbnails already exist; skipping");
+            return JobExecution::Success;
+        }
+
+        let bytes = match state.storage.get_object(&initial.version.s3_key).await {
+            Ok(bytes) => bytes,
+            Err(err) => {
+                warn!(job_id = %job.id, error = %err, "thumbnail fetch failed; will retry");
+                return JobExecution::Retry {
+                    delay: Duration::from_secs(30),
+                    error: err.to_string(),
+                };
+            }
+        };
+
+        let generation = match generate_preview_and_thumbnail(&initial.document, &bytes) {
+            Ok(result) => result,
+            Err(err) => {
+                return JobExecution::Failed { error: err };
+            }
+        };
+
+        if let Some(page_count) = generation.page_count {
+            let state_clone = state.clone();
+            let document_id = initial.document.id;
+            let version_id = initial.version.id;
+            match task::spawn_blocking(move || {
+                persist_document_page_count(state_clone, document_id, version_id, page_count)
+            })
+            .await
+            {
+                Ok(Ok(())) => {}
+                Ok(Err(err)) => {
+                    warn!(
+                        job_id = %job.id,
+                        document_id = %document_id,
+                        version_id = %version_id,
+                        error = %err,
+                        "failed to update document page count metadata; retrying"
+                    );
+                    return JobExecution::Retry {
+                        delay: Duration::from_secs(30),
+                        error: err,
+                    };
+                }
+                Err(join_err) => {
+                    error!(
+                        job_id = %job.id,
+                        document_id = %document_id,
+                        version_id = %version_id,
+                        error = %join_err,
+                        "page count metadata task panicked"
+                    );
+                    return JobExecution::Retry {
+                        delay: Duration::from_secs(60),
+                        error: format!("metadata panic: {join_err}"),
+                    };
+                }
+            }
+        }
+
+        let thumbnail_asset_id = initial
+            .existing_thumbnail
+            .as_ref()
+            .map(|asset| asset.id)
+            .unwrap_or_else(Uuid::new_v4);
+        let thumbnail_s3_key = format!(
+            "documents/{}/v{}/assets/{}/{}",
+            initial.document.id,
+            initial.version.version_number,
+            THUMBNAIL_ASSET_TYPE,
+            thumbnail_asset_id
+        );
+
+        let preview_asset_id = initial
+            .existing_preview
+            .as_ref()
+            .map(|asset| asset.id)
+            .unwrap_or_else(Uuid::new_v4);
+        let preview_s3_key = format!(
+            "documents/{}/v{}/assets/{}/{}",
+            initial.document.id,
+            initial.version.version_number,
+            PREVIEW_ASSET_TYPE,
+            preview_asset_id
+        );
+
+        if let Err(err) = state
+            .storage
+            .put_object(
+                &preview_s3_key,
+                generation.preview.image_bytes.clone(),
+                Some("image/png".into()),
+                None,
+            )
+            .await
+        {
+            warn!(job_id = %job.id, error = %err, "failed to upload preview; retrying");
+            return JobExecution::Retry {
+                delay: Duration::from_secs(30),
+                error: err.to_string(),
+            };
+        }
+
+        if let Err(err) = state
+            .storage
+            .put_object(
+                &thumbnail_s3_key,
+                generation.thumbnail.image_bytes.clone(),
+                Some("image/png".into()),
+                None,
+            )
+            .await
+        {
+            warn!(job_id = %job.id, error = %err, "failed to upload thumbnail; retrying");
+            return JobExecution::Retry {
+                delay: Duration::from_secs(30),
+                error: err.to_string(),
+            };
+        }
+
+        let state_clone = state.clone();
+        match task::spawn_blocking(move || {
+            persist_assets_metadata(
+                state_clone,
+                &initial,
+                &[
+                    AssetPersistence {
+                        asset_type: PREVIEW_ASSET_TYPE,
+                        asset_id: preview_asset_id,
+                        s3_key: &preview_s3_key,
+                        generated: &generation.preview,
+                    },
+                    AssetPersistence {
+                        asset_type: THUMBNAIL_ASSET_TYPE,
+                        asset_id: thumbnail_asset_id,
+                        s3_key: &thumbnail_s3_key,
+                        generated: &generation.thumbnail,
+                    },
+                ],
+            )
+        })
+        .await
+        {
+            Ok(Ok(())) => {}
+            Ok(Err(err)) => {
+                warn!(job_id = %job.id, error = %err, "failed to persist thumbnail metadata; retrying");
+                return JobExecution::Retry {
+                    delay: Duration::from_secs(30),
+                    error: err,
+                };
+            }
+            Err(join_err) => {
+                error!(job_id = %job.id, error = %join_err, "thumbnail metadata update panicked");
+                return JobExecution::Retry {
+                    delay: Duration::from_secs(30),
+                    error: format!("metadata update panic: {join_err}"),
+                };
+            }
+        }
+
+        JobExecution::Success
+    }
+}
+
+struct ThumbnailContext {
+    document: Document,
+    version: DocumentVersion,
+    existing_thumbnail: Option<DocumentAsset>,
+    existing_preview: Option<DocumentAsset>,
+    skip: bool,
+}
+
+struct GeneratedImage {
+    image_bytes: Vec<u8>,
+    width: Option<i32>,
+    height: Option<i32>,
+}
+
+struct GeneratedAssets {
+    thumbnail: GeneratedImage,
+    preview: GeneratedImage,
+    page_count: Option<u32>,
+}
+
+struct AssetPersistence<'a> {
+    asset_type: &'static str,
+    asset_id: Uuid,
+    s3_key: &'a str,
+    generated: &'a GeneratedImage,
+}
+
+fn load_thumbnail_context(
+    state: Arc<AppState>,
+    payload: &ThumbnailPayload,
+) -> Result<ThumbnailContext, String> {
+    let mut conn = state.db().map_err(|err| format!("{err:?}"))?;
+
+    let version: DocumentVersion = document_versions::table
+        .find(payload.document_version_id)
+        .first(&mut conn)
+        .map_err(|err| format!("{err:?}"))?;
+
+    if version.document_id != payload.document_id {
+        return Err("document/version mismatch".into());
+    }
+
+    let document: Document = documents::table
+        .find(payload.document_id)
+        .first(&mut conn)
+        .map_err(|err| format!("{err:?}"))?;
+
+    let existing_assets: Vec<DocumentAsset> = document_assets::table
+        .filter(document_assets::document_version_id.eq(payload.document_version_id))
+        .filter(document_assets::asset_type.eq_any(vec![
+            THUMBNAIL_ASSET_TYPE.to_string(),
+            PREVIEW_ASSET_TYPE.to_string(),
+        ]))
+        .load(&mut conn)
+        .map_err(|err| format!("{err:?}"))?;
+
+    let mut existing_thumbnail = None;
+    let mut existing_preview = None;
+    for asset in existing_assets {
+        match asset.asset_type.as_str() {
+            THUMBNAIL_ASSET_TYPE => existing_thumbnail = Some(asset),
+            PREVIEW_ASSET_TYPE => existing_preview = Some(asset),
+            _ => {}
+        }
+    }
+
+    let (supported, _) = determine_thumbnail_support(&document);
+    if !supported {
+        return Err("thumbnail generation not supported for this document".into());
+    }
+
+    let skip = existing_thumbnail.is_some() && existing_preview.is_some() && !payload.force;
+
+    Ok(ThumbnailContext {
+        document,
+        version,
+        existing_thumbnail,
+        existing_preview,
+        skip,
+    })
+}
+
+fn generate_preview_and_thumbnail(
+    document: &Document,
+    bytes: &[u8],
+) -> Result<GeneratedAssets, String> {
+    let is_pdf = document
+        .content_type
+        .as_deref()
+        .map(|mime| mime == "application/pdf")
+        .unwrap_or_else(|| {
+            document
+                .original_name
+                .rsplit('.')
+                .next()
+                .map(|ext| ext.eq_ignore_ascii_case("pdf"))
+                .unwrap_or(false)
+        });
+
+    if is_pdf {
+        let pdf_assets = generate_pdf_assets(bytes)?;
+        Ok(GeneratedAssets {
+            preview: pdf_assets.preview,
+            thumbnail: pdf_assets.thumbnail,
+            page_count: Some(pdf_assets.page_count),
+        })
+    } else {
+        let (preview, thumbnail) = generate_image_assets(bytes)?;
+        Ok(GeneratedAssets {
+            preview,
+            thumbnail,
+            page_count: None,
+        })
+    }
+}
+
+fn generate_image_assets(bytes: &[u8]) -> Result<(GeneratedImage, GeneratedImage), String> {
+    let reader = ImageReader::new(Cursor::new(bytes))
+        .with_guessed_format()
+        .map_err(|err| err.to_string())?;
+    let image = reader.decode().map_err(|err| err.to_string())?;
+
+    let preview_image = if image.width() > PREVIEW_WIDTH || image.height() > PREVIEW_HEIGHT {
+        image.thumbnail(PREVIEW_WIDTH, PREVIEW_HEIGHT)
+    } else {
+        image.clone()
+    };
+
+    let thumbnail_image =
+        if preview_image.width() > THUMBNAIL_WIDTH || preview_image.height() > THUMBNAIL_HEIGHT {
+            preview_image.thumbnail(THUMBNAIL_WIDTH, THUMBNAIL_HEIGHT)
+        } else {
+            preview_image.clone()
+        };
+
+    let preview = encode_dynamic_image(preview_image)?;
+    let thumbnail = encode_dynamic_image(thumbnail_image)?;
+
+    Ok((preview, thumbnail))
+}
+
+struct PdfGeneratedAssets {
+    preview: GeneratedImage,
+    thumbnail: GeneratedImage,
+    page_count: u32,
+}
+
+fn generate_pdf_assets(bytes: &[u8]) -> Result<PdfGeneratedAssets, String> {
+    let pdfium = panic::catch_unwind(|| Pdfium::default())
+        .map_err(|_| "failed to initialize PDFium".to_string())?;
+
+    let document = pdfium
+        .load_pdf_from_byte_slice(bytes, None)
+        .map_err(|err| format!("load pdf: {err}"))?;
+
+    let pages = document.pages();
+    let total_pages = pages.len();
+
+    let page = pages
+        .get(0)
+        .map_err(|err| format!("load first page: {err}"))?;
+
+    let render_config = PdfRenderConfig::new()
+        .set_target_width(PREVIEW_WIDTH as i32)
+        .set_maximum_height(PREVIEW_HEIGHT as i32)
+        .render_form_data(true)
+        .rotate_if_landscape(PdfPageRenderRotation::None, true);
+
+    let bitmap = page
+        .render_with_config(&render_config)
+        .map_err(|err| format!("render pdf page: {err}"))?;
+
+    let preview_buffer = bitmap.as_image().to_rgb8();
+    let preview_image = image::DynamicImage::ImageRgb8(preview_buffer);
+
+    let thumbnail_image =
+        if preview_image.width() > THUMBNAIL_WIDTH || preview_image.height() > THUMBNAIL_HEIGHT {
+            preview_image.thumbnail(THUMBNAIL_WIDTH, THUMBNAIL_HEIGHT)
+        } else {
+            preview_image.clone()
+        };
+
+    let preview = encode_dynamic_image(preview_image)?;
+    let thumbnail = encode_dynamic_image(thumbnail_image)?;
+
+    let page_count: u32 = total_pages
+        .try_into()
+        .map_err(|_| "page count exceeds supported range".to_string())?;
+
+    Ok(PdfGeneratedAssets {
+        preview,
+        thumbnail,
+        page_count,
+    })
+}
+
+fn encode_dynamic_image(image: image::DynamicImage) -> Result<GeneratedImage, String> {
+    let (width, height) = image.dimensions();
+    let mut cursor = Cursor::new(Vec::new());
+    image
+        .write_to(&mut cursor, ImageFormat::Png)
+        .map_err(|err| err.to_string())?;
+    Ok(GeneratedImage {
+        image_bytes: cursor.into_inner(),
+        width: Some(width as i32),
+        height: Some(height as i32),
+    })
+}
+
+fn persist_assets_metadata(
+    state: Arc<AppState>,
+    context: &ThumbnailContext,
+    assets: &[AssetPersistence<'_>],
+) -> Result<(), String> {
+    let mut conn = state.db().map_err(|err| format!("{err:?}"))?;
+
+    for asset in assets {
+        let new_asset = NewDocumentAsset {
+            id: asset.asset_id,
+            document_version_id: context.version.id,
+            asset_type: asset.asset_type.to_string(),
+            s3_key: asset.s3_key.to_string(),
+            mime_type: "image/png".to_string(),
+            metadata: json!({
+                "generated_at": Utc::now().to_rfc3339(),
+                "width": asset.generated.width,
+                "height": asset.generated.height,
+            }),
+        };
+
+        diesel::insert_into(document_assets::table)
+            .values(&new_asset)
+            .on_conflict((
+                document_assets::document_version_id,
+                document_assets::asset_type,
+            ))
+            .do_update()
+            .set((
+                document_assets::s3_key.eq(excluded(document_assets::s3_key)),
+                document_assets::mime_type.eq(excluded(document_assets::mime_type)),
+                document_assets::metadata.eq(excluded(document_assets::metadata)),
+            ))
+            .execute(&mut conn)
+            .map_err(|err| format!("{err:?}"))?;
+    }
+
+    Ok(())
+}
+
+fn persist_document_page_count(
+    state: Arc<AppState>,
+    document_id: Uuid,
+    document_version_id: Uuid,
+    page_count: u32,
+) -> Result<(), String> {
+    let mut conn = state.db().map_err(|err| format!("{err:?}"))?;
+
+    let existing_metadata: Value = document_versions::table
+        .filter(document_versions::id.eq(document_version_id))
+        .filter(document_versions::document_id.eq(document_id))
+        .select(document_versions::metadata)
+        .first(&mut conn)
+        .map_err(|err| format!("{err:?}"))?;
+
+    let updated = match existing_metadata {
+        Value::Object(mut map) => {
+            map.insert("page_count".to_string(), Value::from(page_count));
+            Value::Object(map)
+        }
+        _ => {
+            let mut map = Map::new();
+            map.insert("page_count".to_string(), Value::from(page_count));
+            Value::Object(map)
+        }
+    };
+
+    diesel::update(
+        document_versions::table
+            .filter(document_versions::id.eq(document_version_id))
+            .filter(document_versions::document_id.eq(document_id)),
+    )
+    .set(document_versions::metadata.eq(updated))
+    .execute(&mut conn)
+    .map_err(|err| format!("{err:?}"))?;
+
+    Ok(())
+}