Flatnotes is a database-less note-taking application designed for users who want full control over their notes stored as plain Markdown files. It eliminates proprietary formats and complex folder hierarchies, allowing users to edit, search, and link notes directly in a clean web interface while maintaining full file system access. Ideal for developers, researchers, and privacy-conscious users who value portability and open standards.
Built with Vue.js and powered by Whoosh for search and TOAST UI Editor for Markdown rendering, Flatnotes runs via Docker and supports authentication, REST API, and mobile-responsive interfaces. Notes are stored as individual .md files in a configurable directory, with search index cached incrementally to allow external file modifications without restarting the app.
What You Get
- Flat Markdown Storage - Notes are stored as plain .md files in a single folder with no database, enabling direct file system access and portability across tools.
- Wikilink Support - Create bidirectional links between notes using [[Note Title]] syntax, enabling knowledge graph-style connections without external plugins.
- Full-Text Search - Powered by Whoosh, search across all notes instantly with keyboard shortcut ”/”, including partial matches and tag filtering.
- Raw/WYSIWYG Markdown Editor - Toggle between raw Markdown editing and visual WYSIWYG mode using TOAST UI Editor for flexible content creation.
- Customizable Home Page - Set a custom welcome page or dashboard to display frequently accessed notes or static content on app load.
- Multiple Authentication Options - Choose from no auth, read-only mode, username/password, or two-factor authentication (2FA) for secure access.
- RESTful API - Programmatically create, read, update, and delete notes via a documented HTTP API for automation and integration.
- Light/Dark Themes - Native theme switching with system preference detection for comfortable viewing in any lighting environment.
Common Use Cases
- Running a personal knowledge base - A researcher uses Flatnotes to store academic papers and summaries as Markdown files, linking them with wikilinks and searching across decades of notes without vendor lock-in.
- Maintaining a private wiki for team documentation - A DevOps team stores runbooks and system diagrams as .md files in a shared volume, accessible via Flatnotes with password auth and search for quick reference.
- Building a distraction-free journaling system - A writer uses Flatnotes to write daily entries in Markdown, leveraging full-text search to find past entries by topic or date without distractions.
- Syncing notes across devices via Git - A developer commits their Flatnotes folder to a private Git repo, editing on desktop and mobile via synced file storage, with Flatnotes as the unified viewer.
Under The Hood
Architecture
- Clean separation between Python backend and Vue frontend, with distinct responsibilities for API logic, authentication, and file system operations
- Modular service design using base classes to abstract authentication and attachment handling, enabling extensibility without tight coupling
- Dependency injection pattern applied to service instantiation, promoting loose coupling and testability
- RESTful API endpoints aligned with domain entities, using consistent response models and resource-oriented routing
- Configuration-driven paths and environment-aware Docker setup ensure portability and separation of concerns
Tech Stack
- Vue 3 with Pinia and Vue Router powering a rich client-side SPA, enhanced with PrimeVue and ToastUI for editing and UI components
- Vite with Tailwind CSS and PostCSS enabling a modern, optimized frontend build pipeline with SCSS support
- FastAPI backend with Pydantic for robust request validation and structured data handling
- Dockerized multi-stage build using Node.js for frontend compilation and Python for backend runtime, with Pipenv for dependency management
- Markdown-based flat file storage system replacing traditional databases, with custom server-side logic for metadata and file operations
- Health checks and production-grade entrypoint scripts with privilege management via gosu
Code Quality
- Limited testing practices with no verifiable assertions, resulting in minimal test coverage and high risk of regressions
- Poor modular separation in frontend code, leading to entangled components and unclear domain boundaries
- Generic error handling with minimal logging, making failures difficult to diagnose and debug
- Inconsistent naming conventions across components, functions, and variables, reducing code readability
- Absence of type safety or annotations, increasing susceptibility to runtime errors
- No linting or code quality tooling in place, allowing unenforced style and maintainability issues
What Makes It Unique
- Native ToastUI editor integration with custom syntax highlighting and autolinks delivers a self-contained, dependency-free markdown editing experience
- Elegant modal system with built-in keyboard shortcuts and Vue 3’s defineModel for dynamic state binding reduces UI boilerplate
- Human-readable note routing via direct titles (/note/{title}) eliminates ID-based navigation and enhances usability
- Custom SVG icon system with mdi-js integration provides themable, lightweight UI elements without bloated icon libraries
- Theme-aware styling using CSS variables and scoped utilities enables deep theming without complex CSS-in-JS or preprocessors