boos
e0a5f57793
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.
108 lines
4.2 KiB
Markdown
108 lines
4.2 KiB
Markdown
# BoosApi Storage Policy
|
|
|
|
## Dual-Root Directory Model
|
|
|
|
BoosApi uses two directory roots with distinct responsibilities:
|
|
|
|
| Root | Platform path | Purpose |
|
|
|------|---------------|---------|
|
|
| **Config home** | macOS/Linux: `~/.boosapi/`<br>Windows: `%USERPROFILE%\.boosapi\` | Application state, database, encryption keys, SSL, vector DB |
|
|
| **Documents root** | macOS/Linux: `~/Documents/boosapi/`<br>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`:
|
|
|
|
1. Both files are copied to `~/.boosapi/*.migrating` staging names.
|
|
2. Both staging files are renamed to their final names in a single pass.
|
|
3. 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
|
|
|
|
### Image Preview & Modal Rules
|
|
|
|
All antd `<Image>` components **must** use blur-mask preview:
|
|
|
|
```tsx
|
|
<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.
|