Storage

Mix employs a sophisticated two-tier storage architecture with pluggable storage backends that separates user-managed collaborative files from agent-managed private working files. This design enables both file sharing across sessions and private agent workspaces, with support for local filesystem or cloud storage (Supabase).

Storage Overview

Storage Provider Abstraction

Mix uses a pluggable storage provider system that abstracts storage operations behind a common interface. This allows seamless switching between storage backends:

Supported Providers

Local Storage (default): Files stored on local filesystem at ./storage/

• Zero configuration required
• Perfect for development and self-hosted deployments
• Files served directly via HTTP

Supabase Storage: Files stored in Supabase cloud storage

• Simple 4-field configuration (endpoint, bucket, access key, type)
• Automatic thumbnail generation and storage
• Files served via Supabase public URLs
• Ideal for production deployments

Configuration

Storage providers are selected through environment variables, with local storage as the default. The system requires only the storage type and provider-specific credentials (endpoint, bucket, access key for Supabase). All file operations automatically use the configured provider, making the storage backend transparent to application logic.

Rationale

This architecture separates user collaboration from agent workspace needs, solving three key problems:

Workspace Pollution: Agent temp files, logs, and processing outputs don't clutter the user's shared file space.

Processing Isolation: Multiple sessions can process the same shared file independently without conflicts.

Clean UX: Users manage collaborative files; agents handle implementation details in private storage.

Key Design Decisions

Two Storage Tiers: Shared storage for user collaboration + session storage for agent workspace. Single namespace would mix user assets with agent artifacts.

Agent-Managed Sessions: Agents handle session files programmatically. User CRUD access would expose implementation details unnecessarily.

Session-First Priority: Session files override shared files during serving, allowing agents to create processed versions without breaking originals for other sessions.

Two-Tier Architecture

1. Shared Uploads Storage (/storage/uploads/)

Purpose: User-managed collaborative files accessible by all sessions

• Who manages: Users via upload API
• Access: All sessions can read these files
• Use cases: Shared documents, media files, project assets
• API operations: Upload, list, delete, serve

2. Session Storage (/storage/{session-id}/)

Purpose: Agent-managed private working space per session

• Who manages: AI agents programmatically
• Access: Only the owning session can read these files
• Use cases: Temporary files, processed data, agent-generated content
• API operations: Serve only (agents manage via file system)

File Serving Priority

When a file is requested via /api/sessions/{session-id}/files/{filename}, the system uses this priority order:

1. Session storage first: Check /storage/{session-id}/{filename}
2. Shared uploads fallback: Check /storage/uploads/{filename} if not found in session

This allows agents to "override" shared files with session-specific versions while maintaining access to collaborative files.

Agent Workflow

Agents can download files from shared uploads and create session-specific versions:

1. Access shared file: Agent reads from /storage/uploads/{filename}
2. Process/modify: Agent processes the file contents
3. Store in session: Agent writes to /storage/{session-id}/{filename}
4. Serve processed version: Subsequent requests serve the session version

This enables agents to work with user files while maintaining private working copies.

Session Isolation

• Private storage: Session files are inaccessible to other sessions
• Secure serving: Session ID must match to access session-specific files
• Agent-only management: Users cannot directly manipulate session storage

Storage Paths

Local Storage Structure

Local storage uses a three-level directory hierarchy under /storage/: the uploads/ directory for shared user files, thumbnails/ for automatically generated image previews, and individual session directories (named by session UUID) containing agent-managed private files.

Supabase Storage Keys

Supabase storage mirrors this structure using object keys: uploads/{filename} for user files and thumbnails/{hash}_{spec}.jpg for generated previews. Thumbnails are automatically filtered from file listings and remain invisible to users in file selection interfaces.

Key Files

Storage Provider System

• mix_agent/internal/storage/provider.go: Core Provider interface and configuration structures defining storage abstraction
• mix_agent/internal/storage/local_provider.go: Local filesystem implementation of storage provider
• mix_agent/internal/storage/supabase_provider.go: Supabase cloud storage implementation using REST API
• mix_agent/internal/storage/factory.go: Factory for creating storage providers based on configuration
• mix_agent/internal/storage/config.go: Environment variable loading and validation

HTTP Handlers

• mix_agent/internal/http/session_asset_server.go: File serving and thumbnail generation using StorageProvider
• mix_agent/internal/http/rest_files.go: File management REST APIs (upload, list, delete) with thumbnail filtering

Legacy Session Storage

• mix_agent/internal/session/storage.go: Session-specific storage paths (still used for agent workspace)
• mix_agent/internal/app/app.go: Application initialization with StorageProvider setup