Storage Management

Overview#

The Storage Management system provides a unified interface for browsing and managing all files stored across the platform. Files come from multiple features -- email ingestion, bill uploads, CSV imports, and skill generation -- and are organized under a single, secure storage layer with organization-scoped isolation.

The admin dashboard presents these files in a Google Drive-like browser with virtual root folders, breadcrumb navigation, and specialized views for certain file types.

Key Features#

• Unified file browser across all platform features
• Virtual folder structure with clean, consistent naming
• Breadcrumb navigation for easy folder traversal
• Specialized views for bills (with status tracking and upload capability)
• Secure downloads via time-limited presigned URLs
• Organization isolation ensures data separation between organizations

---

Virtual Folder Structure#

The storage browser organizes files into intuitive virtual folders, regardless of how different features store them internally:

Why Virtual Folders?#

Different platform features store files with varying naming conventions. Virtual folders abstract these differences behind clean, user-friendly names. You browse "Emails" and "Imports" rather than navigating raw storage paths.

---

Storage Browser#

Root Level#

At the root level, the storage page displays clickable folder cards in a responsive grid. Each card shows the folder name, description, and an icon representing its contents.

Folder Browsing#

When browsing inside a folder, you see:

• Breadcrumb navigation -- Clickable path segments (e.g., Storage > Emails > {subfolder}) for easy navigation
• File table -- Files listed with name, size, last modified date, and download button
• Folder rows -- Clickable rows with folder icons for navigating deeper
• Pagination -- "Load more" button for large folders

URL-Based Navigation#

The current path is stored in the URL, enabling:

• Browser back/forward navigation
• Direct linking to specific folders
• Bookmarking frequently accessed locations

---

Bills View#

The Bills folder has a specialized view instead of the generic file browser, because bill files have rich metadata beyond just file storage -- status tracking, event processing, and transaction linking.

Bills View Features#

1. Entity selector -- Choose which legal entity's bills to view
2. Upload area -- Drag-and-drop zone for PDF, JPEG, and PNG files (up to 25MB)
3. Inbox table -- Queued and processing files with status badges
4. Processed table -- Completed files with linked transaction numbers

Bill Upload Pipeline#

When a bill is uploaded through the storage browser:

1. The file is validated (content type and size)
2. The legal entity is verified
3. The file is uploaded to secure storage
4. A tracking record is created with status "uploaded"
5. An event is created for the bill processing agent
6. The agent processes the document automatically

Bill Status Lifecycle#

After processing, the bill record links to the created transaction (e.g., an AP invoice) with its transaction number for easy cross-reference.

---

Downloads#

Files are downloaded through time-limited presigned URLs:

• URLs expire after 1 hour
• Each download generates a fresh URL
• No credentials are exposed in the download link
• Files open in a new browser tab

---

Security#

Organization Isolation#

All files are stored with organization-specific prefixes. The storage browser validates that every request stays within the requesting organization's scope. There is no way to browse or access another organization's files.

Upload Validation#

• Content type whitelist: Only PDF, JPEG, PNG, and WebP files are accepted
• Size limit: Maximum 25MB per file
• Entity verification: The target legal entity must exist before upload
• Filename sanitization: Special characters are stripped from filenames

Access Control#

Storage endpoints require server-to-server authentication. Browser requests are proxied through the admin dashboard, which adds the necessary credentials. Users never directly access the storage layer.

---

Adding New Folders#

The virtual folder system is extensible. When new platform features generate files (e.g., generated reports, export archives), they can be added to the storage browser by:

1. Storing files with a consistent naming pattern
2. Registering a new virtual folder with a name, description, and icon

The new folder automatically appears in the storage browser root without any additional configuration.

---

Storage Costs#

Files are stored in Cloudflare R2 (S3-compatible object storage) with competitive pricing:

For most organizations, storage costs are negligible -- typically under $5/month.