🥔 Potato — A Framework for Scalable .NET Backends
Potato is a modular, opinionated framework for building clean, scalable, and domain-driven backend systems using CQRS, DDD*, and tree-structured data. Designed for ASP.NET Core developers, Potato provides out-of-the-box support for MongoDB, S3-compatible file storage, vector search, and Retrieval-Augmented Generation (RAG) pipelines — all optimized for cloud-native and minimal API environments.
🎯 Why Potato?
Potato exists to help teams:
- Eliminate repetitive boilerplate for commands, queries, and event handling
- Model complex, nested data using immutable trees
- Keep domain logic pure and infrastructure-agnostic
- Build file- and document-heavy systems with AI and vector search support
- Generate clean, type-safe OpenAPI docs automatically
Whether you're building a back office portal, document AI backend, or a multi-tenant SaaS API — Potato provides the structure.
📦 Potato Package Ecosystem
| Package | Description |
|---|---|
| Potato | Core DDD + CQRS abstractions: commands, queries, handlers, aggregates, validation |
| Potato.Mongo | MongoDB integration: repositories, tree structures, collection initialization |
| Potato.OpenApi | Automatic OpenAPI schema filters for Potato command/query and tree nodes |
| Potato.Files | Generic file storage abstraction for upload, download, delete |
| Potato.Files.S3 | S3-compatible implementation of Potato.Files (works with MinIO, AWS, etc.) |
| Potato.DocumentChopper | Breaks documents into semantic chunks and can convert PDFs and Word files to simple Markdown |
| Potato.Embeddings | Interfaces for converting document chunks into vector embeddings |
| Potato.Embeddings.Mistral | Mistral-based implementation of Potato.Embeddings (embedding API) |
| Potato.Vectors | Abstractions for storing and querying vectors |
| Potato.Vectors.Qdrant | Qdrant-backed implementation for vector storage and search |
| Potato.RagPipeline | End-to-end pipeline for chunking, embedding, storing, and querying documents for RAG use cases |
🧱 Design Principles
- ✅ CQRS and DDD-first: Command/query segregation by default
- ✅ Immutability and testability: No mutable state in the domain layer
- ✅ MongoDB tree support: Entities modeled hierarchically, persisted with full ancestry info
- ✅ Minimal API-friendly: Works natively with ASP.NET Core route handlers
- ✅ OpenAPI included: Rich schema generation for commands, queries, and nodes
- ✅ Modular and composable: Bring only the packages you need
🚀 Built for Real-World Backends
- 👥 Organizational hierarchies with permission nodes and references
- 📄 Document indexing and embedding using Mistral + Qdrant
- 🔍 AI-powered search and summarization via RAG
- ☁️ Cloud-native file storage with MinIO or S3
- 🌍 REST APIs with automatic documentation
🧭 Where to Start
- Install and Use Templates – Install the Potato .NET templates
- Quick Start – Quick Start
- Modeling Your Domain with Nodes – Modeling Your Domain with Nodes
- Add Your First Command – Add Your First Command — CreateUser
- Search Users with Filters – Search Users with Filters
- Add OpenAPI Support – Document your API
- Implement a Permission System – Restrict access using permissions
- Working with S3 Files – Upload and manage files
- Vector Search with Qdrant – Store and query vectors
- Potato RAG Pipeline Quickstart Guide – Retrieval-Augmented Generation
Welcome to Potato 👋