Vault Feature
The Vault feature provides a file browser for exploring and editing content within the user's Parachute vault, supporting both local filesystem access and remote server browsing.
Architecture Overview
The Vault feature operates in two modes: local (direct filesystem access) and remote (via Computer server API). The system automatically selects the appropriate mode based on server connectivity.
VaultBrowserScreen (Entry Point)
│
├── Server URL configured? ──Yes──► RemoteFilesScreen
│ │
└── No ──► FilesScreen (local) ▼
│ RemoteFileBrowserService
▼ │
FileBrowserService HTTP API calls
│ /api/ls, /api/read
▼ /api/write
Local Filesystem
Key Files
| File | Purpose | Lines |
|---|---|---|
vault_browser_screen.dart |
Entry point - routes to local or remote browser | ~80 |
files_screen.dart |
Local file browser with folder navigation | ~450 |
remote_files_screen.dart |
Remote file browser via server API | ~400 |
markdown_viewer_screen.dart |
Local markdown viewer/editor with frontmatter | ~600 |
remote_markdown_viewer_screen.dart |
Remote markdown viewer/editor | ~500 |
text_viewer_screen.dart |
Text/code file viewer/editor (local) | ~350 |
remote_text_viewer_screen.dart |
Text/code file viewer/editor (remote) | ~300 |
file_browser_service.dart |
Local filesystem operations | ~300 |
remote_file_browser_service.dart |
Remote API operations | ~250 |
file_item.dart |
File/folder model with type detection | ~150 |
FileItem Model
Represents a file or folder in the vault browser with automatic type detection:
File Types
enum FileItemType {
folder, // Directory
markdown, // .md, .markdown files
text, // Code/config files
audio, // .wav, .mp3, .opus, .m4a, .aac
other // Unsupported types
}
Supported Text Extensions
Config: json, yaml, yml, toml, ini, cfg, conf
Code: dart, js, ts, jsx, tsx, py, rb, go, rs, java, kt, swift,
c, cpp, h, hpp, cs, php, sh, bash, zsh, fish
Web: html, htm, css, scss, sass, less, vue, svelte
Data: xml, csv, tsv, sql
Docs: rst, tex, bib
Text: txt, log, env, gitignore, dockerignore, editorconfig
Local File Browser Service
Handles direct filesystem operations within the vault directory:
Key Methods
| Method | Purpose |
|---|---|
getInitialPath() |
Returns vault root path |
isAtRoot(path) |
Checks if at vault root |
getParentPath(path) |
Navigates up directory tree |
getDisplayPath(path) |
Formats path with ~ prefix |
listFolder(path, includeHidden) |
Lists directory contents (folders first) |
readFileAsString(path) |
Reads file content |
writeFile(path, content) |
Writes/overwrites file |
isWithinVault(path) |
Security check - ensures path is in vault |
Android Permissions: The service detects permission issues when directory listing fails and directs users to grant Storage permission in Settings.
Remote File Browser Service
Handles file operations via the Computer server API:
API Endpoints
| Operation | Endpoint | Method |
|---|---|---|
| List folder | /api/ls?path=... |
GET |
| Read file | /api/read?path=... |
GET |
| Write file | /api/write |
PUT |
API Response Format
{
"entries": [
{
"name": "filename.md",
"relativePath": "Daily/journals/filename.md",
"isDirectory": false,
"lastModified": "2026-01-28T10:30:00",
"size": 1024
}
]
}
Authentication: Includes
X-API-Key header if configured. Uses 10-second timeout on all requests.
State Management
Uses Riverpod providers for reactive state:
Core Providers
| Provider | Type | Purpose |
|---|---|---|
fileBrowserServiceProvider |
Provider | Singleton local browser service |
vaultRootPathProvider |
FutureProvider | Vault root path with refresh trigger |
currentBrowsePathProvider |
StateProvider | Currently browsed directory |
folderContentsProvider |
FutureProvider | List of items in current folder |
isAtRootProvider |
FutureProvider | Whether at vault root |
displayPathProvider |
FutureProvider | User-friendly path display |
Remote Providers
| Provider | Purpose |
|---|---|
remoteFileBrowserServiceProvider |
Remote service (watches server URL + API key) |
remoteCurrentPathProvider |
Remote browse path state |
remoteShowHiddenFilesProvider |
Show/hide hidden files toggle |
remoteFolderContentsProvider |
Remote folder contents |
Markdown Viewer
Full-featured markdown renderer with YAML frontmatter support:
View Mode Features
- Frontmatter Section: Collapsible YAML metadata display with key-value pairs
- Markdown Rendering: Full markdown support via
flutter_markdown - Entry Metadata: Para-ID display (para:abc123 format)
- Selectable Text: Copy any content
Edit Mode Features
- Full-text editor with monospace font
- Real-time change detection
- Save/Cancel buttons in app bar
- Unsaved changes warning on navigation
Supported Markdown Elements
- Headings (h1-h6) with cascade sizing - Bold, italic, strikethrough text - Inline code and fenced code blocks - Bulleted, numbered, and nested lists - Tables with borders and padding - Blockquotes with left border styling - Links (underlined, turquoise color) - Horizontal rules - Theme-aware colors (light/dark mode)
File Navigation Flow
VaultBrowserScreen
│
├──► FilesScreen / RemoteFilesScreen
│ │
│ ├── Folder tap ──► Navigate into folder
│ │
│ ├── Markdown tap ──► MarkdownViewerScreen
│ │
│ ├── Text/Code tap ──► TextViewerScreen
│ │
│ ├── Audio tap ──► (TODO: Audio playback)
│ │
│ └── Other tap ──► File info dialog
│
└── Context Menu (Long Press)
├── "View as Text" (with size warning >1MB)
└── "File Info"
Vault Directory Structure
~/Parachute/ (Vault Root)
├── Daily/ (Local-first module)
│ ├── journals/ (Journal entries)
│ ├── assets/ (Images, audio, files)
│ │ └── YYYY-MM-DD/ (Date-based organization)
│ ├── reflections/ (Agent outputs)
│ └── chat-log/ (Session activity logs)
│
└── Chat/ (Server-managed module)
├── sessions/ (Imported session transcripts)
├── assets/ (Chat-related assets)
├── artifacts/ (Generated files)
├── contexts/ (Context folders)
└── imports/ (External imports)
Local vs Remote Comparison
| Aspect | Local | Remote |
|---|---|---|
| Source | Filesystem | Computer server API |
| Path Type | Absolute (full paths) | Relative (from vault root) |
| Root Path | ~/Parachute/Daily |
Empty string "" |
| Authentication | File system permissions | API key in header |
| Timeout | None (instant) | 10 seconds |
| Hidden Files | Skip by default | API query param toggle |
| Availability | Always (offline-capable) | Requires server connection |
Large File Handling
- Files > 1MB: Warning shown in context menu
- Files > 5MB: Confirmation dialog before opening
- Very large files (100MB+): May cause UI freeze
Performance Note: No pagination for large folders - all contents loaded at once. Consider pagination for folders with 1000+ items.
Known Limitations
- Audio Playback: TODO placeholder - not yet implemented
- Binary Files: Marked as "other" type, cannot be viewed
- Frontmatter: Only YAML supported (no TOML/JSON frontmatter)
- Real-time Sync: No file watching - manual refresh needed
- Conflict Resolution: No handling for concurrent edits on remote
Platform-Specific Notes
macOS
- Security-scoped bookmarks for sandbox compliance
- Bookmark restoration managed by FileSystemService
Android
- Requires
MANAGE_EXTERNAL_STORAGEpermission - Permission detection when directory listing fails
- Directs user to Settings for manual grant
iOS
- App-specific documents directory
- No external storage access