Flatnotes is a self-hosted note-taking application designed for users who value simplicity, portability, and control over their data. Unlike traditional note apps that rely on databases or proprietary formats, Flatnotes stores all notes as plain Markdown files in a flat directory structure. This ensures your content remains accessible and portable—no vendor lock-in, no complex migrations. The app provides a clean, distraction-free interface with powerful search and tagging features while maintaining the raw text nature of Markdown. Ideal for developers, writers, and privacy-conscious users who want to avoid cloud dependency or database complexity.
Flatnotes is built with Vue.js and includes a RESTful API, mobile-responsive UI, and support for both raw and WYSIWYG Markdown editing. It supports authentication via username/password or 2FA, and caches only its search index incrementally, allowing external file edits to be reflected in real time. This makes it perfect for those who prefer managing files directly via their file system while still enjoying a modern web interface.
What You Get
- Database-less Markdown storage - All notes are stored as plain .md files in a specified directory, ensuring full portability and compatibility with any text editor or file system.
- Full-text search with incremental indexing - Uses Whoosh to provide fast, real-time search across all notes; the index updates automatically when files change externally.
- Wikilink support - Link between notes using [[Note Title]] syntax, enabling a wiki-style knowledge graph without external dependencies.
- Raw and WYSIWYG Markdown editor - Toggle between raw Markdown editing and a visual WYSIWYG interface powered by TOAST UI Editor.
- Mobile-responsive web interface - Fully functional on phones, tablets, and desktops with a clean, distraction-free layout.
- Multiple authentication options - Choose from no auth, read-only mode, username/password, or 2FA for secure access.
- Customizable homepage - Set a custom Markdown file to display as the landing page upon login.
- RESTful API - Programmatically access, create, update, or delete notes via HTTP endpoints for automation and integration.
- Light and dark themes - Switch between visual themes to suit your environment or preference.
Common Use Cases
- Building a personal knowledge base - Users maintain a collection of research notes, code snippets, and project documentation as Markdown files, leveraging wikilinks to connect related ideas without folders.
- Developers managing technical documentation - Engineers use Flatnotes to store API docs, configuration references, and troubleshooting guides in a single directory that can be version-controlled with Git.
- Privacy-focused note-takers avoiding cloud services - Users who refuse to store sensitive notes on third-party platforms use Flatnotes to self-host their data with full control over storage and access.
- DevOps teams managing internal wikis - Teams deploy Flatnotes on local servers to host runbooks, incident reports, and SOPs with search and tagging—avoiding the overhead of Confluence or Notion.
- Problem → Solution flow: ‘I want to edit my notes in VS Code but still search them easily’ - Flatnotes solves this by letting you edit .md files in any editor, while the web app provides instant search and rich formatting without requiring a database.
- Team workflow: Solo writers with distributed workflows - Writers use Flatnotes to sync notes across devices via synced folders (e.g., Nextcloud or rsync), maintaining a consistent interface regardless of device.
Under The Hood
This project is a full-stack note-taking application that combines a modern Vue.js frontend with a Python backend, emphasizing simplicity and flat-file storage for notes. It provides a modular architecture designed to support extensibility through pluggable systems and unified configuration handling.
Architecture
This project adopts a monolithic architecture with clear separation between frontend and backend components, enabling modular development and maintainability.
- The system follows a flat-file storage model for notes, minimizing external dependencies
- Authentication and attachment handling are implemented using strategy patterns and base classes for extensibility
- Modules are organized to encapsulate distinct concerns such as configuration, user management, and file handling
- A well-defined structure supports scalable growth while maintaining a cohesive system design
Tech Stack
The project leverages modern web technologies to deliver a streamlined and developer-friendly note-taking experience.
- The frontend is built with Vue 3, Pinia, and Vue Router, offering a responsive UI with state management
- The backend is powered by FastAPI, providing fast and reliable API handling for note operations
- Key frontend libraries include PrimeVue, ToastUI Editor, and Axios for rich UI and HTTP communication
- Development tools such as Vite, Tailwind CSS, and Prettier support efficient build and formatting workflows
Code Quality
The codebase reflects a mixed state of quality with some structured components and inconsistent practices.
- Client-side components are well-organized, while server-side Python modules show potential for better consistency
- Error handling exists but is not uniformly applied across all parts of the system
- Type annotations are present, contributing to improved code clarity and maintainability
- Test coverage is limited, with existing scripts failing to execute properly
What Makes It Unique
This application stands out through its integration of Vue and FastAPI, offering a cohesive and extensible note-taking platform.
- Pluggable systems for authentication and attachment management allow custom implementations with shared base classes
- Global configuration is unified across both frontend and backend, ensuring consistent behavior and settings
- Tight integration with Markdown editing tools like ToastUI enhances content creation capabilities
- Docker-based development setup with devcontainer support simplifies local environment configuration and onboarding