How dullage/flatnotes works
Based on our analysis of the file tree and the README, this project is a self-hosted, database‐less note-taking web application called “flatnotes.” Its primary purpose is to offer a distraction-free environment for creating, editing, and searching markdown files while keeping your data in standard files (instead of a proprietary database). The application is split into a frontend built using Vue (with Vite for bundling and Tailwind CSS for styling) and a backend implemented in Python. The backend handles operations such as authentication, note management (including file-system based storage for both notes and attachments), and search indexing (with Whoosh).
Main Components
• Frontend (Client):
• Built with Vue.js and enhanced by Vite.
• Contains UI components (e.g., App.vue, various components for modals, buttons, text inputs, editor integration, etc.).
• Includes routing (client/router.js) and global store management.
• Uses external libraries like TOAST UI Editor for markdown editing and viewing.
• Backend (Server):
• Python-based server with multiple submodules encapsulating different business logics:
▪ API (server/api_messages.py) for RESTful interactions.
▪ Authentication (server/auth/...) handling different authentication strategies.
▪ Note management (server/notes/...) managing file-based operations.
▪ Attachments (server/attachments/...) dealing with file storage for note attachments.
▪ Logging, configuration, and helper functionalities (server/logger.py, server/global_config.py, etc.).
• Storage and Search Index:
• The core data (notes) is stored as markdown files in a specified folder.
• A search index (using Whoosh) is maintained as a cached file-based index, which updates incrementally.
• Container and Deployment Environment:
• Docker setup (via Dockerfile, docker-compose, and devcontainer configuration) indicates containerized deployment.
• Configuration/environment variables are used to parameterize authentication settings, secret keys, and volume mounts.
Relationships and Interactions
• The Client sends API requests (over HTTP) to the Backend.
• The Backend’s RESTful API processes requests related to note creation, editing, deletion, search, and authentication.
• The note data is stored directly on the server’s file system as markdown files.
• The search functionality is powered by an internal search engine that indexes these markdown files.
• Authentication and file handling (attachments, note files) modules are separate components within the backend, interacting with each other as necessary.
• Docker and container management files (like Dockerfile, docker-compose) ensure that the environment (both for development and production) is consistent and isolated.
Architectural Patterns and Design Principles
• Separation of Concerns – There is a clear division between the frontend and the backend service.
• Modular Design – The backend is split into submodules for authentication, note management, and attachments.
• File-System Based Persistence – Instead of a traditional database, the markdown files in a flat folder structure serve as the storage layer.
• Incremental Search Indexing – Search updates are triggered on access (or during initialization) ensuring that the index remains current without intensive database-like dependencies.
• Containerization – Usage of Docker and dev containers reflects a modern deployment approach with consistent environments.
Technologies, Frameworks, and Libraries
• Frontend: Vue.js, Vite, Tailwind CSS, TOAST UI Editor.
• Backend: Python (with internal modules for API, authentication, and file system operations), Whoosh search library.
• Deployment: Docker, Docker Compose, possibly VS Code devcontainer configuration.
• Build and Configuration: Pipfile for Python dependencies, package.json for JS dependencies, plus configuration files such as tailwind.config.js and postcss.config.js.