aqda 0.3.1__py3-none-any.whl

aqda/__init__.py

@@ -0,0 +1,3 @@
+"""AQDA - Open-source qualitative data analysis tool."""
+
+__version__ = "0.3.1"

aqda/__main__.py

@@ -0,0 +1,59 @@
+"""Entry point for running AQDA as a module or via the console script."""
+
+import argparse
+import threading
+import webbrowser
+
+import uvicorn
+
+from aqda import __version__
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8765
+
+
+# Build the argument parser for the `aqda` console script.
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="aqda",
+        description="AQDA — Augmented Qualitative Data Analysis. "
+        "Starts the local web app and opens it in your browser.",
+    )
+    parser.add_argument("--version", action="version", version=f"aqda {__version__}")
+    parser.add_argument(
+        "--host", default=DEFAULT_HOST, help=f"Interface to bind (default: {DEFAULT_HOST})"
+    )
+    parser.add_argument(
+        "--port", type=int, default=DEFAULT_PORT, help=f"Port to bind (default: {DEFAULT_PORT})"
+    )
+    parser.add_argument(
+        "--no-browser", action="store_true", help="Do not open a browser window on startup"
+    )
+    return parser
+
+
+def main():
+    args = build_parser().parse_args()
+
+    # Open browser after a short delay to let the server start
+    def open_browser():
+        import time
+
+        time.sleep(1.5)
+        webbrowser.open(f"http://{args.host}:{args.port}")
+
+    if not args.no_browser:
+        threading.Thread(target=open_browser, daemon=True).start()
+
+    print(f"\n  AQDA is running at http://{args.host}:{args.port}\n")
+    from aqda.app import app
+
+    config = uvicorn.Config(app, host=args.host, port=args.port, log_level="warning")
+    server = uvicorn.Server(config)
+    app.state.uvicorn_server = server
+    # uvicorn exits with status 3 itself if the port is already in use.
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

aqda/app.py

@@ -0,0 +1,120 @@
+"""FastAPI application — serves both API and the frontend SPA."""
+
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse, JSONResponse
+
+from aqda import __version__
+from aqda.db import init_db
+from aqda.routers import projects, documents, codes, codings, memos, settings, ai, export, shared, system
+from aqda.services.shared_projects import start_sync_service, stop_sync_service
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await init_db()
+    await start_sync_service()
+    try:
+        yield
+    finally:
+        await stop_sync_service()
+
+
+app = FastAPI(title="AQDA", version=__version__, lifespan=lifespan)
+
+_LOCAL_BROWSER_ORIGINS = {
+    "http://127.0.0.1:8765",
+    "http://localhost:8765",
+    "http://[::1]:8765",
+    # The Vite development server proxies /api requests to the same local app.
+    "http://127.0.0.1:5173",
+    "http://localhost:5173",
+    "http://[::1]:5173",
+}
+_LOCAL_BROWSER_HOSTS = {"127.0.0.1", "localhost", "::1"}
+
+
+def _hostname_from_host_header(value: str) -> str:
+    """Return a normalized hostname while rejecting malformed port syntax."""
+    host = value.strip().lower()
+    if host.startswith("["):
+        closing = host.find("]")
+        suffix = host[closing + 1:] if closing >= 0 else ""
+        if closing < 0 or (
+            suffix and not (suffix.startswith(":") and suffix[1:].isdigit())
+        ):
+            return ""
+        return host[1:closing]
+    if host.count(":") == 1:
+        hostname, port = host.rsplit(":", 1)
+        if not port.isdigit():
+            return ""
+        return hostname
+    return host if ":" not in host else ""
+
+
+@app.middleware("http")
+async def require_local_http_context(request, call_next):
+    """Reject DNS-rebinding reads and browser-driven cross-site writes.
+
+    Every request must retain a localhost Host header. Origin-less local requests
+    remain available to the command line and native folder picker. Browsers attach
+    an Origin to cross-site POST/PUT/PATCH/DELETE requests, which prevents an
+    arbitrary website from closing AQDA or changing its data.
+    """
+    hostname = _hostname_from_host_header(request.headers.get("host", ""))
+    if hostname not in _LOCAL_BROWSER_HOSTS:
+        return JSONResponse(
+            {"detail": "AQDA only accepts requests addressed to localhost"},
+            status_code=400,
+        )
+    if request.method not in {"GET", "HEAD", "OPTIONS"}:
+        origin = request.headers.get("origin")
+        if origin and origin not in _LOCAL_BROWSER_ORIGINS:
+            return JSONResponse(
+                {"detail": "Cross-site requests to AQDA are not allowed"},
+                status_code=403,
+            )
+    return await call_next(request)
+
+# API routes
+app.include_router(projects.router, prefix="/api/projects", tags=["projects"])
+app.include_router(documents.router, prefix="/api/documents", tags=["documents"])
+app.include_router(codes.router, prefix="/api/codes", tags=["codes"])
+app.include_router(codings.router, prefix="/api/codings", tags=["codings"])
+app.include_router(memos.router, prefix="/api/memos", tags=["memos"])
+app.include_router(settings.router, prefix="/api/settings", tags=["settings"])
+app.include_router(ai.router, prefix="/api/ai", tags=["ai"])
+app.include_router(export.router, prefix="/api/export", tags=["export"])
+app.include_router(shared.router, prefix="/api/shared", tags=["shared"])
+app.include_router(system.router, prefix="/api/system", tags=["system"])
+
+
+@app.api_route(
+    "/api/{path:path}",
+    methods=["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"],
+    include_in_schema=False,
+)
+async def api_not_found(path: str):
+    return JSONResponse({"detail": f"API route not found: /api/{path}"}, status_code=404)
+
+# Serve frontend
+FRONTEND_DIR = Path(__file__).parent / "frontend" / "dist"
+
+if FRONTEND_DIR.exists():
+    app.mount("/assets", StaticFiles(directory=FRONTEND_DIR / "assets"), name="static")
+    _FRONTEND_ROOT = FRONTEND_DIR.resolve()
+    _INDEX = _FRONTEND_ROOT / "index.html"
+
+    @app.get("/{path:path}")
+    async def serve_spa(path: str):
+        # Serve index.html for all non-API, non-asset routes (SPA routing).
+        # Resolve the target and confine it to the frontend dir so crafted
+        # paths like "../../db.py" can't escape and serve arbitrary files.
+        target = (_FRONTEND_ROOT / path).resolve()
+        if target.is_relative_to(_FRONTEND_ROOT) and target.is_file():
+            return FileResponse(target)
+        return FileResponse(_INDEX)

aqda/db.py

@@ -0,0 +1,447 @@
+"""Database setup and connection management using aiosqlite."""
+
+import aiosqlite
+import os
+import sqlite3
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+DATA_DIR = Path(os.environ.get("AQDA_DATA_DIR", Path.home() / ".aqda"))
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS project (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    description TEXT DEFAULT '',
+    created_at TEXT DEFAULT (datetime('now')),
+    modified_at TEXT DEFAULT (datetime('now')),
+    deleted_at TEXT DEFAULT NULL,
+    lineage_id TEXT DEFAULT NULL,
+    revision INTEGER NOT NULL DEFAULT 0,
+    head_snapshot_id TEXT DEFAULT NULL,
+    shared_folder TEXT DEFAULT NULL,
+    shared_previous_folder TEXT DEFAULT NULL,
+    shared_last_published_revision INTEGER DEFAULT NULL,
+    shared_last_snapshot_id TEXT DEFAULT NULL,
+    shared_last_sync_at TEXT DEFAULT NULL,
+    shared_sync_error TEXT DEFAULT NULL
+);
+
+CREATE TABLE IF NOT EXISTS document (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    project_id INTEGER NOT NULL REFERENCES project(id) ON DELETE CASCADE,
+    name TEXT NOT NULL,
+    content TEXT NOT NULL,
+    source_type TEXT DEFAULT 'text',
+    transcript TEXT DEFAULT NULL,
+    label TEXT DEFAULT '',
+    exclude_from_ai INTEGER DEFAULT 0,
+    created_at TEXT DEFAULT (datetime('now')),
+    modified_at TEXT DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS code (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    project_id INTEGER NOT NULL REFERENCES project(id) ON DELETE CASCADE,
+    parent_id INTEGER REFERENCES code(id) ON DELETE CASCADE,
+    name TEXT NOT NULL,
+    description TEXT DEFAULT '',
+    color TEXT DEFAULT '#6366f1',
+    sort_order INTEGER DEFAULT 0,
+    created_at TEXT DEFAULT (datetime('now')),
+    deleted_at TEXT DEFAULT NULL,
+    deletion_batch_id TEXT DEFAULT NULL
+);
+
+CREATE TABLE IF NOT EXISTS coding (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    document_id INTEGER NOT NULL REFERENCES document(id) ON DELETE CASCADE,
+    code_id INTEGER NOT NULL REFERENCES code(id) ON DELETE CASCADE,
+    start_pos INTEGER NOT NULL,
+    end_pos INTEGER NOT NULL,
+    selected_text TEXT NOT NULL,
+    coder TEXT DEFAULT '',
+    created_at TEXT DEFAULT (datetime('now')),
+    deleted_at TEXT DEFAULT NULL,
+    deletion_batch_id TEXT DEFAULT NULL,
+    offset_unit TEXT NOT NULL DEFAULT 'codepoint',
+    repair_status TEXT DEFAULT NULL
+);
+
+CREATE TABLE IF NOT EXISTS memo (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    project_id INTEGER NOT NULL REFERENCES project(id) ON DELETE CASCADE,
+    document_id INTEGER REFERENCES document(id) ON DELETE CASCADE,
+    code_id INTEGER REFERENCES code(id) ON DELETE SET NULL,
+    coding_id INTEGER REFERENCES coding(id) ON DELETE SET NULL,
+    start_pos INTEGER DEFAULT NULL,
+    end_pos INTEGER DEFAULT NULL,
+    title TEXT DEFAULT '',
+    content TEXT DEFAULT '',
+    created_at TEXT DEFAULT (datetime('now')),
+    modified_at TEXT DEFAULT (datetime('now')),
+    offset_unit TEXT NOT NULL DEFAULT 'codepoint',
+    repair_status TEXT DEFAULT NULL
+);
+
+CREATE TABLE IF NOT EXISTS document_variable (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    document_id INTEGER NOT NULL REFERENCES document(id) ON DELETE CASCADE,
+    key TEXT NOT NULL,
+    value TEXT DEFAULT '',
+    UNIQUE(document_id, key)
+);
+
+CREATE TABLE IF NOT EXISTS setting (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+);
+
+-- Default settings
+INSERT OR IGNORE INTO setting (key, value) VALUES
+    ('ollama_url', 'http://localhost:11434'),
+    ('llm_model', ''),
+    ('embedding_model', ''),
+    ('chunk_size', '500'),
+    ('chunk_overlap', '50'),
+    ('filename_pattern', ''),
+    ('filename_variables', ''),
+    ('whisper_model', 'base'),
+    ('coder_name', ''),
+    ('shared_folder', ''),
+    ('shared_folders', '[]'),
+    ('device_id', ''),
+    ('schema_version', '11');
+
+CREATE TABLE IF NOT EXISTS project_snapshot (
+    snapshot_id TEXT PRIMARY KEY,
+    project_id INTEGER NOT NULL REFERENCES project(id) ON DELETE CASCADE,
+    parent_snapshot_id TEXT DEFAULT NULL,
+    revision INTEGER NOT NULL,
+    created_at TEXT NOT NULL,
+    created_by TEXT DEFAULT ''
+);
+CREATE INDEX IF NOT EXISTS idx_snapshot_project ON project_snapshot(project_id, created_at);
+
+CREATE TABLE IF NOT EXISTS code_deletion_batch (
+    id TEXT PRIMARY KEY,
+    project_id INTEGER NOT NULL REFERENCES project(id) ON DELETE CASCADE,
+    root_code_id INTEGER NOT NULL,
+    deleted_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS shared_ignored_head (
+    project_id INTEGER NOT NULL REFERENCES project(id) ON DELETE CASCADE,
+    snapshot_id TEXT NOT NULL,
+    created_at TEXT DEFAULT (datetime('now')),
+    PRIMARY KEY (project_id, snapshot_id)
+);
+
+CREATE TABLE IF NOT EXISTS shared_conflict_branch (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    project_id INTEGER NOT NULL REFERENCES project(id) ON DELETE CASCADE,
+    source_lineage_id TEXT NOT NULL,
+    anchor_snapshot_id TEXT NOT NULL,
+    latest_snapshot_id TEXT NOT NULL,
+    latest_snapshot_path TEXT NOT NULL,
+    conflict_project_id INTEGER REFERENCES project(id) ON DELETE SET NULL,
+    conflict_base_revision INTEGER DEFAULT NULL,
+    status TEXT NOT NULL DEFAULT 'active',
+    created_at TEXT DEFAULT (datetime('now')),
+    updated_at TEXT DEFAULT (datetime('now')),
+    UNIQUE(project_id, anchor_snapshot_id)
+);
+
+CREATE TABLE IF NOT EXISTS embedding_cache (
+    id TEXT PRIMARY KEY,
+    document_id INTEGER NOT NULL REFERENCES document(id) ON DELETE CASCADE,
+    project_id INTEGER NOT NULL,
+    model TEXT NOT NULL,
+    start_pos INTEGER NOT NULL,
+    end_pos INTEGER NOT NULL,
+    chunk_text TEXT NOT NULL,
+    embedding BLOB NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_embedding_project ON embedding_cache(project_id, model);
+CREATE INDEX IF NOT EXISTS idx_embedding_document ON embedding_cache(document_id, model);
+"""
+
+# Migrations keyed by target version. Each runs if schema_version < target.
+MIGRATIONS = {
+    2: [
+        "ALTER TABLE code ADD COLUMN deleted_at TEXT DEFAULT NULL",
+        "ALTER TABLE coding ADD COLUMN deleted_at TEXT DEFAULT NULL",
+    ],
+    3: [
+        """CREATE TABLE IF NOT EXISTS embedding_cache (
+            id TEXT PRIMARY KEY,
+            document_id INTEGER NOT NULL REFERENCES document(id) ON DELETE CASCADE,
+            project_id INTEGER NOT NULL,
+            model TEXT NOT NULL,
+            start_pos INTEGER NOT NULL,
+            end_pos INTEGER NOT NULL,
+            chunk_text TEXT NOT NULL,
+            embedding BLOB NOT NULL
+        )""",
+        "CREATE INDEX IF NOT EXISTS idx_embedding_project ON embedding_cache(project_id, model)",
+        "CREATE INDEX IF NOT EXISTS idx_embedding_document ON embedding_cache(document_id, model)",
+    ],
+    4: [
+        "ALTER TABLE project ADD COLUMN deleted_at TEXT DEFAULT NULL",
+    ],
+    5: [
+        "ALTER TABLE document ADD COLUMN transcript TEXT DEFAULT NULL",
+    ],
+    6: [
+        "ALTER TABLE document ADD COLUMN label TEXT DEFAULT ''",
+        "ALTER TABLE document ADD COLUMN exclude_from_ai INTEGER DEFAULT 0",
+        "ALTER TABLE memo ADD COLUMN start_pos INTEGER DEFAULT NULL",
+        "ALTER TABLE memo ADD COLUMN end_pos INTEGER DEFAULT NULL",
+        "INSERT OR IGNORE INTO setting (key, value) VALUES ('coder_name', '')",
+    ],
+    7: [
+        "ALTER TABLE coding ADD COLUMN coder TEXT DEFAULT ''",
+    ],
+    8: [
+        "ALTER TABLE project ADD COLUMN lineage_id TEXT DEFAULT NULL",
+        "ALTER TABLE project ADD COLUMN revision INTEGER NOT NULL DEFAULT 0",
+        "ALTER TABLE project ADD COLUMN head_snapshot_id TEXT DEFAULT NULL",
+        """CREATE TABLE IF NOT EXISTS project_snapshot (
+            snapshot_id TEXT PRIMARY KEY,
+            project_id INTEGER NOT NULL REFERENCES project(id) ON DELETE CASCADE,
+            parent_snapshot_id TEXT DEFAULT NULL,
+            revision INTEGER NOT NULL,
+            created_at TEXT NOT NULL,
+            created_by TEXT DEFAULT ''
+        )""",
+        "CREATE INDEX IF NOT EXISTS idx_snapshot_project ON project_snapshot(project_id, created_at)",
+    ],
+    9: [
+        "ALTER TABLE project ADD COLUMN shared_folder TEXT DEFAULT NULL",
+        "ALTER TABLE project ADD COLUMN shared_last_published_revision INTEGER DEFAULT NULL",
+        "ALTER TABLE project ADD COLUMN shared_last_snapshot_id TEXT DEFAULT NULL",
+        "ALTER TABLE project ADD COLUMN shared_last_sync_at TEXT DEFAULT NULL",
+        "ALTER TABLE project ADD COLUMN shared_sync_error TEXT DEFAULT NULL",
+        "ALTER TABLE code ADD COLUMN deletion_batch_id TEXT DEFAULT NULL",
+        "ALTER TABLE coding ADD COLUMN deletion_batch_id TEXT DEFAULT NULL",
+        "ALTER TABLE coding ADD COLUMN offset_unit TEXT NOT NULL DEFAULT 'legacy_utf16'",
+        "ALTER TABLE coding ADD COLUMN repair_status TEXT DEFAULT NULL",
+        "ALTER TABLE memo ADD COLUMN offset_unit TEXT NOT NULL DEFAULT 'legacy_utf16'",
+        "ALTER TABLE memo ADD COLUMN repair_status TEXT DEFAULT NULL",
+        "INSERT OR IGNORE INTO setting (key, value) VALUES ('shared_folder', '')",
+        "INSERT OR IGNORE INTO setting (key, value) VALUES ('device_id', '')",
+        """CREATE TABLE IF NOT EXISTS code_deletion_batch (
+            id TEXT PRIMARY KEY,
+            project_id INTEGER NOT NULL REFERENCES project(id) ON DELETE CASCADE,
+            root_code_id INTEGER NOT NULL,
+            deleted_at TEXT NOT NULL
+        )""",
+        """CREATE TABLE IF NOT EXISTS shared_ignored_head (
+            project_id INTEGER NOT NULL REFERENCES project(id) ON DELETE CASCADE,
+            snapshot_id TEXT NOT NULL,
+            created_at TEXT DEFAULT (datetime('now')),
+            PRIMARY KEY (project_id, snapshot_id)
+        )""",
+    ],
+    10: [
+        """CREATE TABLE IF NOT EXISTS shared_conflict_branch (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            project_id INTEGER NOT NULL REFERENCES project(id) ON DELETE CASCADE,
+            source_lineage_id TEXT NOT NULL,
+            anchor_snapshot_id TEXT NOT NULL,
+            latest_snapshot_id TEXT NOT NULL,
+            latest_snapshot_path TEXT NOT NULL,
+            conflict_project_id INTEGER REFERENCES project(id) ON DELETE SET NULL,
+            conflict_base_revision INTEGER DEFAULT NULL,
+            status TEXT NOT NULL DEFAULT 'active',
+            created_at TEXT DEFAULT (datetime('now')),
+            updated_at TEXT DEFAULT (datetime('now')),
+            UNIQUE(project_id, anchor_snapshot_id)
+        )""",
+    ],
+    11: [
+        "ALTER TABLE project ADD COLUMN shared_previous_folder TEXT DEFAULT NULL",
+        "INSERT OR IGNORE INTO setting (key, value) VALUES ('shared_folders', '[]')",
+    ],
+}
+
+LATEST_SCHEMA_VERSION = max(MIGRATIONS)
+
+MAX_UPLOAD_BYTES = 50 * 1024 * 1024  # 50 MB
+
+
+def _db_path(project_id: int | None = None) -> Path:
+    """Get path to the main database."""
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    return DATA_DIR / "aqda.db"
+
+
+async def get_db() -> aiosqlite.Connection:
+    """Get a database connection."""
+    db = await aiosqlite.connect(_db_path(), timeout=15)
+    db.row_factory = aiosqlite.Row
+    await db.execute("PRAGMA busy_timeout=15000")
+    await db.execute("PRAGMA journal_mode=WAL")
+    await db.execute("PRAGMA foreign_keys=ON")
+    return db
+
+
+async def _run_migrations(db: aiosqlite.Connection):
+    """Apply pending schema migrations."""
+    cursor = await db.execute(
+        "SELECT value FROM setting WHERE key='schema_version'"
+    )
+    row = await cursor.fetchone()
+    current = int(row["value"]) if row else 1
+
+    for target in sorted(MIGRATIONS.keys()):
+        if current >= target:
+            continue
+        for sql in MIGRATIONS[target]:
+            try:
+                await db.execute(sql)
+            except Exception as e:
+                # An ALTER that re-adds an existing column is expected (the fresh
+                # schema already has it); anything else is a real failure we must
+                # not hide, or we'd silently bump the version on a broken DB.
+                if "duplicate column name" not in str(e).lower():
+                    raise
+        await db.execute(
+            "INSERT OR REPLACE INTO setting (key, value) VALUES ('schema_version', ?)",
+            (str(target),),
+        )
+        await db.commit()
+
+    # Lineage IDs are application-generated UUIDs. Populate legacy rows after
+    # migration 8 rather than relying on a SQLite expression as a column default.
+    cursor = await db.execute("SELECT id FROM project WHERE lineage_id IS NULL OR lineage_id='' ")
+    for row in await cursor.fetchall():
+        await db.execute(
+            "UPDATE project SET lineage_id=? WHERE id=?",
+            (str(uuid.uuid4()), row["id"]),
+        )
+    await db.execute(
+        "CREATE UNIQUE INDEX IF NOT EXISTS idx_project_lineage ON project(lineage_id)"
+    )
+    cursor = await db.execute("SELECT value FROM setting WHERE key='device_id'")
+    device = await cursor.fetchone()
+    if not device or not device["value"].strip():
+        await db.execute(
+            "INSERT OR REPLACE INTO setting (key, value) VALUES ('device_id', ?)",
+            (str(uuid.uuid4()),),
+        )
+    await db.commit()
+
+
+async def touch_project(db: aiosqlite.Connection, project_id: int | None):
+    """Record a substantive project change for ordering and snapshot conflict checks."""
+    if project_id is None:
+        return
+    await db.execute(
+        "UPDATE project SET revision=revision+1, modified_at=datetime('now') WHERE id=?",
+        (project_id,),
+    )
+
+
+async def touch_projects(db: aiosqlite.Connection, project_ids):
+    """Touch each distinct project ID once within the caller's transaction."""
+    for project_id in sorted({pid for pid in project_ids if pid is not None}):
+        await touch_project(db, project_id)
+
+
+def create_backup(label: str = "backup") -> Path:
+    """Create and verify a consistent backup of the live database.
+
+    The SQLite backup API is safe while other connections are open. Backups use
+    immutable timestamped names so cloud-sync tools never observe a half-replaced
+    database file.
+    """
+    source_path = _db_path()
+    if not source_path.exists():
+        raise FileNotFoundError("AQDA database does not exist")
+
+    backup_dir = DATA_DIR / "backups"
+    backup_dir.mkdir(parents=True, exist_ok=True)
+    safe_label = "".join(ch if ch.isalnum() or ch in "-_" else "-" for ch in label)
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S.%fZ")
+    backup_path = backup_dir / f"aqda-{safe_label}-{stamp}.db"
+
+    source = sqlite3.connect(source_path)
+    destination = sqlite3.connect(backup_path)
+    try:
+        source.backup(destination)
+        result = destination.execute("PRAGMA integrity_check").fetchone()
+        if not result or result[0] != "ok":
+            raise RuntimeError(f"Backup integrity check failed: {result}")
+    except Exception:
+        destination.close()
+        source.close()
+        backup_path.unlink(missing_ok=True)
+        raise
+    else:
+        destination.close()
+        source.close()
+    return backup_path
+
+
+def _existing_schema_version(path: Path) -> int | None:
+    """Read a database version without creating or migrating the database."""
+    if not path.exists() or path.stat().st_size == 0:
+        return None
+    connection = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+    try:
+        row = connection.execute(
+            "SELECT value FROM setting WHERE key='schema_version'"
+        ).fetchone()
+        return int(row[0]) if row else 1
+    except sqlite3.DatabaseError:
+        return 1
+    finally:
+        connection.close()
+
+
+def _prune_backups(prefix: str, keep: int) -> None:
+    backup_dir = DATA_DIR / "backups"
+    if not backup_dir.exists():
+        return
+    matches = sorted(backup_dir.glob(f"aqda-{prefix}-*.db"), reverse=True)
+    for stale in matches[keep:]:
+        stale.unlink(missing_ok=True)
+
+
+def create_daily_backup() -> Path | None:
+    """Create at most one verified rolling backup per UTC day."""
+    backup_dir = DATA_DIR / "backups"
+    day = datetime.now(timezone.utc).strftime("%Y%m%d")
+    already_created = (
+        any(backup_dir.glob(f"aqda-daily-{day}T*.db"))
+        if backup_dir.exists()
+        else False
+    )
+    if already_created:
+        return None
+    path = create_backup("daily")
+    _prune_backups("daily", keep=7)
+    return path
+
+
+async def init_db():
+    """Initialize the database schema and run migrations."""
+    path = _db_path()
+    existing_version = _existing_schema_version(path)
+    if existing_version is not None and existing_version < LATEST_SCHEMA_VERSION:
+        create_backup(f"before-migration-v{LATEST_SCHEMA_VERSION}")
+    db = await get_db()
+    try:
+        await db.executescript(SCHEMA)
+        await db.commit()
+        await _run_migrations(db)
+        from aqda.services.offsets import repair_legacy_offsets
+
+        await repair_legacy_offsets(db)
+        await db.commit()
+    finally:
+        await db.close()
+    if existing_version is not None:
+        create_daily_backup()