Foxel is an open-source private cloud storage platform designed for individuals and teams who need centralized, secure file management with advanced search capabilities. Unlike traditional cloud storage solutions that rely on basic metadata or filename searches, Foxel leverages AI to enable semantic search across unstructured data such as images, documents, and videos. Built with Python and React, it provides a modern web interface while supporting multiple storage backends through an extensible adapter pattern. This makes it ideal for users who want control over their data without relying on third-party cloud services, while still enjoying intelligent search and seamless file previews.
What You Get
- Unified File Management - Centralize files stored across different locations (local filesystem, S3, etc.) into a single interface without moving data.
- Pluggable Storage Backends - Extend storage support via adapter pattern; currently supports local filesystem and can be extended to S3, NFS, or other systems.
- Semantic Search - Use natural language queries (e.g., ‘Show me photos of dogs from last summer’) to find content in images and documents using AI-powered analysis.
- Built-in File Preview - View images, videos, PDFs, Office documents, text files, and code directly in the browser without downloading.
- Permissions and Sharing - Generate public or private shareable links for files and folders with configurable access controls.
- Task Processing Center - Handle file indexing, metadata extraction, and backups asynchronously to maintain UI responsiveness during heavy operations.
Common Use Cases
- Building a personal photo archive with AI search - Users with large collections of photos and videos use Foxel to tag and find images by content (e.g., ‘find pictures with my dog at the beach’) without manual tagging.
- Creating a secure team document repository - Small teams store contracts, reports, and presentations in Foxel to enable semantic search across PDFs and Office files while keeping data on-premises.
- Problem → Solution flow: Manual file hunting → AI-powered discovery - Users tired of scrolling through folders to find a specific document or image use Foxel’s natural language search to locate files by context, reducing time spent searching by up to 70%.
- DevOps teams managing multi-source assets - Teams using local storage, NAS, or cloud buckets consolidate access via Foxel’s pluggable backends to streamline asset retrieval and preview across distributed systems.
Under The Hood
Foxel is a modular, extensible private cloud storage platform that combines a virtual file system abstraction with AI-powered file processing and a rich web-based interface. It is built as a full-stack application using Python and TypeScript, emphasizing plugin architecture and domain-driven organization.
Architecture
Foxel adopts a monolithic yet modular architecture that clearly separates concerns across functional domains such as authentication, AI, and storage adapters.
- The system is organized into domain-specific modules that encapsulate related functionalities like task scheduling and adapter implementations
- A layered structure separates API, domain logic, and data access layers with well-defined boundaries
- Strategy and middleware patterns are consistently applied to support extensibility and manage cross-cutting concerns like error handling
- Component interactions are facilitated through API routers, service layers, and a plugin system that enables flexible integration
Tech Stack
The project leverages modern full-stack technologies with Python for backend services and TypeScript with React for the frontend.
- The backend is built on Python 3.14 with FastAPI and Pydantic, while the frontend uses React, TypeScript, and Vite for development
- Key backend dependencies include FastAPI, Pydantic, and various Python libraries for AI and storage; frontend tools encompass React Router and Ant Design
- Development workflows utilize Vite, Bun, and Docker for build automation and containerization
- Linting and formatting tools are in place, although explicit test configuration details are not evident in the provided files
Code Quality
Foxel presents a moderately structured codebase with clear separation of concerns, though it lacks comprehensive testing and documentation.
- Error handling is extensively implemented across modules with consistent use of try/except blocks and exception propagation
- Testing practices are limited, with no test files identified in the sample, indicating a gap in quality assurance
- Code consistency varies across modules, with some following naming conventions and others showing mixed styles
- Technical debt is visible in the absence of test coverage and minimal documentation, which may affect long-term maintainability
What Makes It Unique
Foxel distinguishes itself through its plugin-driven architecture and unified virtual filesystem abstraction that enables flexible storage integration.
- The platform features a modular adapter system that allows for easy extension and integration with various storage providers
- AI-powered file processing capabilities are seamlessly integrated into the virtual filesystem, offering intelligent content handling
- A rich web UI built with React and TypeScript provides a user-friendly interface for managing cloud storage operations
- The combination of extensibility, AI capabilities, and a unified file abstraction sets it apart from traditional storage solutions