Witral

Witral is a self-hosted, modular ingestion framework that enables the efficient capture of ephemeral data from messaging platforms, transforming it into structured Markdown files for easy management. This innovative solution acts as a bridge between fast-paced communication streams, such as messaging services, and robust storage systems, whether local or cloud-based. By utilizing a "fire-and-forget" approach, Witral allows users to capture essential information without the need for context switching, streamlining workflows significantly.

Key Features

• Fire-and-Forget Capture: Effortlessly route messages from chat directly to designated folders using a simple double-comma syntax (,,tag).
• Platform Agnostic: The modular architecture allows for clear separation between data ingestion (source) and storage (destination).
  • Included Source Plugin: WhatsApp integration via Baileys.
  • Included Storage Plugins: Supports both local file systems and Google Drive for cloud synchronization.
• Deterministic Output: Automatically generates standardized Markdown files for organized documentation.
• Self-Hosted & Private: Operates fully within a Docker container on personal machines or servers, ensuring privacy and control over data.

Quick Setup and Usage Guidelines

Witral features an interactive wizard that simplifies the initial setup process. The following steps outline how to begin utilizing Witral:

1. Clone the repository:

   git clone https://github.com/kirlts/witral
   cd witral
   

2. Make the script executable:

   chmod +x scripts/start.sh
   

3. Run the installer:

   ./scripts/start.sh
   

Capture Syntax

Witral actively listens for the ,, trigger within monitored groups for various capture functionalities:

• Basic Capture (New File):

  • Input: ,,idea Rewrite the ingestor logic
  • Output: A new Markdown file created at vault/tags/idea/27-10-2023 - 14-30.md.

• Dynamic Title Capture:

  • Input: ,,idea,,Architecture Rewrite the ingestor logic
  • Output: Custom file vault/tags/idea/Architecture.md.

• Append Mode: Allows messages to be appended to an existing file.

  • Input: ,,log Server restarted
  • Output: Entry added to vault/tags/log.md.

Interactive Menu System

Witral provides an interactive menu directly within messaging platforms. By typing ,,menu in any monitored group, users can access various management options, including:

• Connecting to a service
• Viewing status
• Managing groups and tags
• Exiting the menu

Management & CLI Operations

To interact with Witral once the Docker container is running, the built-in CLI tool is available:

docker exec -it witral node dist/index.js

This command gives access to tools for adding new groups, managing tags, and monitoring real-time logs.

Project Structure

The source structure of Witral is designed for clarity and organization, with distinct directories for core logic, plugins, scripts, and configuration data:

witral/  
├── data/               # Persisted configuration (groups, tags, sessions) - gitignored  
├── vault/              # Default output directory for Markdown files  
├── scripts/            # Helper scripts (start, reset, backup)  
├── src/                # Source files  
│   ├── core/           # Core logic  
│   ├── plugins/        # Modular plugins  
│   └── cli/            # Interactive command-line interface  
└── docker-compose.yml  

For detailed technical information, architecture diagrams, and guidance on development, the full documentation is available.