Files

T

boos e0a5f57793 feat(desktop): embed BoosAPI Desktop client as a subproject

Vendor the rebranded BoosAPI Desktop client (Tauri + Vue) into metapi as
a monorepo subdirectory under desktop/. Source only — node_modules,
dist, Cargo target and the upstream .git history are excluded.

desktop/ keeps its own independent Cargo workspace (desktop/src-tauri
with crates/*); it is not part of the backend boosapi crate, so a
`cargo check` at the metapi root still compiles only the backend. Build
the desktop app from desktop/src-tauri per desktop/README.md.

Note: app icons are still placeholder assets pending the final BoosAPI
logo. The updater signing keys live outside the repo and are not
included.

2026-06-22 11:32:57 +08:00

4.2 KiB

Raw Blame History

BoosApi Storage Policy

Dual-Root Directory Model

BoosApi uses two directory roots with distinct responsibilities:

Root	Platform path	Purpose
Config home	macOS/Linux: `~/.boosapi/` Windows: `%USERPROFILE%\.boosapi\`	Application state, database, encryption keys, SSL, vector DB
Documents root	macOS/Linux: `~/Documents/boosapi/` Windows: `%USERPROFILE%\Documents\boosapi\`	User-visible files: images, documents, backups

Both directories are created automatically on first launch.

Directory Layout

Config home (`~/.boosapi/`)

~/.boosapi/
├── boosapi.db          # SQLite database (all app state, settings, keys, …)
├── master.key        # 32-byte AES-256 master encryption key (mode 0600 on Unix)
├── vector_db/        # sqlite-vec vector store for knowledge-base embeddings
└── ssl/              # Self-signed TLS certificate and private key for the gateway
    ├── cert.pem
    └── key.pem       # mode 0600 on Unix

Documents root (`~/Documents/boosapi/`)

~/Documents/boosapi/
├── images/           # Image attachments (chat uploads, avatars, AI-generated)
├── files/            # Non-image file attachments (documents, code, archives)
└── backups/          # Default location for auto- and manual backups

All paths stored in the database (e.g. messages.attachments, stored_files.storage_path) use relative paths under the documents root (e.g. images/abc123_photo.jpg).

Design Decisions

Dual-Root vs. Single Home

User-created files (images, documents, backups) belong in a user-visible location under ~/Documents/ so users can browse, back up, and share them with standard OS tools. Application internals (database, encryption keys, vector indices) stay hidden in ~/.boosapi/ to avoid clutter and accidental modification.

Single Home vs. Tauri `app_data_dir`

Tauri's app_data_dir() resolves to platform-specific, version-locked paths (e.g. ~/Library/Application Support/top.boosapi.app/ on macOS). Using a user-visible ~/.boosapi/ makes backups, debugging, and cross-version upgrades predictable and independent of the Tauri bundle identifier.

`boosapi.db` + `master.key` — Atomic Migration

The database and its master encryption key are always migrated as a matched pair. During the one-time migration from the legacy app_data_dir:

Both files are copied to ~/.boosapi/*.migrating staging names.
Both staging files are renamed to their final names in a single pass.
If either step fails the staging files are cleaned up and the old location is left intact — no data is ever left in a half-migrated state.

Other Subdirectories

vector_db/ and ssl/ are migrated best-effort (rename, falling back to copy+delete for cross-device moves). A failure to migrate a subdirectory is logged as a warning; the application continues normally and the new subdirectory will be created empty on next use.

Backup Defaults

resolve_backup_dir(None) returns ~/Documents/boosapi/backups/. Users may override this via Settings → Backup → Backup Directory; an absolute path stored there takes precedence.

SSL Certificate Storage

generate_self_signed_cert writes cert.pem and key.pem to ~/.boosapi/ssl/. The private key is written atomically (temp-file + rename) with mode 0600 on Unix.

Agent / Automation Guidance

Application state (database, keys, vector DB): read/write under ~/.boosapi/
User files (images, documents, backups): read/write under ~/Documents/boosapi/
Database paths for files must be relative to the documents root
Do not hard-code paths derived from app_data_dir, bundle identifier, or application version strings
All directory names are lowercase with no spaces

UI Conventions

All antd <Image> components must use blur-mask preview:

<Image preview={{ mask: { blur: true }, scaleStep: 0.5 }} />

mask: { blur: true } — hover shows a blurred overlay (never mask: false or plain text mask)
scaleStep: 0.5 — consistent zoom step across the app
These settings apply to all image previews: chat attachments, file list thumbnails, avatar previews, etc.

4.2 KiB Raw Blame History