# dullage/flatnotes architecture

> Architecture diagram of the GitHub repository dullage/flatnotes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dullage/flatnotes
- Repository: https://github.com/dullage/flatnotes

## Overview

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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Client"
        FE["Vue Frontend (Vue, Vite, TailwindCSS)"]:::frontend
        UI["UI Components & TOAST UI Editor"]:::frontend
        Router["Client Router (router.js)"]:::frontend
        FE -->|"contains"| UI
        FE -->|"routes via"| Router
    end

    %% Backend Layer
    subgraph "Backend Server"
        API["API Layer"]:::backend
        Auth["Authentication Module"]:::backend
        Notes["Note Management Module"]:::backend
        Att["Attachments Module"]:::backend
        Log["Logging (Logger)"]:::backend
        Config["Configuration (Global Config)"]:::backend
        Auth -->|"verifies"| Notes
    end

    %% File Storage Layer
    subgraph "File Storage"
        MD["Markdown Files"]:::storage
        AFiles["Attachment Files"]:::storage
        Index["Search Index (Whoosh)"]:::storage
    end

    %% Deployment Layer
    subgraph "Deployment"
        DF["Dockerfile"]:::deployment
        Dev["DevContainer (.devcontainer)"]:::deployment
    end

    %% Interactions between layers
    FE -->|"HTTP API"| API
    Notes -->|"saves_to"| MD
    Notes -->|"indexes_into"| Index
    Att -->|"stores_in"| AFiles

    %% Deployment influence (containerized environment)
    DF -->|"configures"| API
    Dev -->|"configures"| API

    %% Click Events
    click FE "https://github.com/dullage/flatnotes/tree/develop/client/"
    click API "https://github.com/dullage/flatnotes/blob/develop/server/api_messages.py"
    click Auth "https://github.com/dullage/flatnotes/tree/develop/server/auth/"
    click Notes "https://github.com/dullage/flatnotes/tree/develop/server/notes/"
    click Att "https://github.com/dullage/flatnotes/tree/develop/server/attachments/"
    click Log "https://github.com/dullage/flatnotes/blob/develop/server/logger.py"
    click Config "https://github.com/dullage/flatnotes/blob/develop/server/global_config.py"
    click DF "https://github.com/dullage/flatnotes/tree/develop/Dockerfile"
    click Dev "https://github.com/dullage/flatnotes/tree/develop/.devcontainer/"

    %% Styling
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef storage fill:#FFD700,stroke:#000,stroke-width:2px,stroke-dasharray: 5, 5;
    classDef deployment fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
