XNote – Lightweight Personal Note System: Features, Architecture, and Installation Guide

Project Introduction

XNote is a lightweight personal note system designed to help users escape information overload. It offers rich data management capabilities, supports multiple note formats, and can be extended with custom plugins.

Key Features

Rich data management with support for markdown, tables, galleries, and lists.

Cross‑platform support for Windows, macOS, and Linux; can run on cloud services or locally.

100% data ownership; works with various database back‑ends.

Small‑scale multi‑user support (large‑scale collaboration not recommended).

Built‑in tools such as a Python doc viewer, text comparison, encoding utilities, QR/barcode generators, and image processing.

System Architecture

The architecture follows a layered design with a clear separation between the core logic, handlers, and static resources. An illustration of the architecture is provided in the original article.

Program Directory Structure

|-- app.py          # Program entry point
|-- core/
|   |-- xconfig.py      # Configuration
|   |-- xmanager.py     # Handlers manager, URL registration, scheduled tasks
|   |-- xauth.py        # Permission control
|   |-- xtables.py      # Database table definitions
|   |-- xtemplate.py    # View rendering interface
|   \-- autoreload.py   # Hot‑reload for development
|-- xutils/         # Utility collection
|-- lib/            # Third‑party libraries added to sys.path
|-- config/         # Configuration files
|   |-- file/       # File‑related config
|   |-- lang/       # Language packs
|   \-- template/   # Template config
|-- handlers/       # HTTP request handlers
|   |-- api/        # JSON APIs
|   |-- system/     # System functions
|   |-- note/       # Note‑related features
|   |-- fs/         # File management
|   |-- tools/      # Utility tools
|   |-- plugins/    # Plugin directory
|   \-- ...
|-- static/         # Static assets (CSS, JS, images)
\-- tests/          # Test cases

Data Directory Structure

|-- files/     # Uploaded files
|   \-- user01 # Per‑user directory
|       |-- upload   # Date‑based upload folders
|       \-- gallery  # Photo albums
|-- backup/    # Backup data
|-- scripts/   # Custom scripts
|-- storage/   # Application storage
|-- db/        # Database files
|-- log/       # Log files
|-- tmp/       # Temporary files
\-- trash/    # Recycle bin

Development Framework / Libraries

webpy (modified version bundled with XNote)

tornado template (modified version bundled with XNote)

sqlite3 (Python built‑in file‑based DB)

wsgidav (WebDAV support for network disk mounting)

psutil (optional, system metrics collection)

comtypes (optional, Microsoft speech API)

Frontend Dependencies

jQuery

layer (web layer component)

marked (Markdown parser)

CodeMirror (code editor)

jexcel (web spreadsheet)

Font‑Awesome (icon library)

art‑template (template engine)

Vue 2 (MVVM framework)

qrcode (QR code generator)

csv.js (CSV parsing)

jsdiff (text diff)

Adding New Modules

To add a new handler, create a Python file under handlers/ (e.g., test.py ) and define a class with HTTP methods:

class MyHandler:
    def GET(self):
        return "success"

class Handler2:
    def GET(self):
        return "handler2"

xurls = (
    r"/test", MyHandler,
    r"/handler2", Handler2
)

Installation & Running

Install Python and Dependencies

Python 3 (Python 2.7 is no longer maintained)

Install required packages: Linux/macOS: python -m pip install -r config/requirements.txt Windows: python -m pip install -r config/requirements.win.txt

Configuration and Startup

The default configuration file is config/boot/boot.default.properties . To use a custom configuration:

python3 app.py --config config/boot/your_custom.properties

After starting, open http://localhost:1234/ in a browser. The initial admin account is admin with password 123456 .

Main Functionalities

Note Management

Supports markdown, tables, galleries, and list formats.

Organize notes via notebooks, tags, and priority levels.

Share notes with non‑logged‑in users.

Top‑pin and archive capabilities.

Version history and backup.

Full‑text search across the knowledge base.

Commenting and access statistics.

File Management

List and grid views.

Upload, download, create, delete, rename, and move files.

Integrated code editor, text viewer, binary viewer, and content search.

Support for large files with resumable download and multi‑GB upload.

Plugin extensibility.

Toolbox

Python documentation (pydoc).

Text processing utilities (diff, code generation, password generation).

Encoding/decoding tools (base64, MD5, numeral conversions).

Barcode and QR code generators.

Image processing (merge, split, grayscale).

Plugin development framework for custom extensions.

System Extensions

Developers can write plugins to listen to system messages (notes, reminders, files, time, system). Plugins can define a category attribute to appear in various UI entry points, and can be created via templates.

Conclusion

XNote provides a comprehensive, extensible, and cross‑platform solution for personal knowledge management, with clear documentation, code examples, and a plugin system that allows developers to tailor the product to specific needs.