← XeFM crftwr/xefm on GitHub · craftware

XeFM Application Overview

Current Version

The version is single-sourced from xefm/__init__.py’s __version__; run python3 -m xefm --version to see it. Everything else — packaging metadata, the macOS/Windows bundle versions, the DMG/ZIP filenames — derives from that literal, so this document deliberately doesn’t restate the number.

XeFM (Xenolith File Manager) is a sophisticated dual-pane file manager that runs both as a native desktop app (Windows, macOS) and in the terminal (Windows, macOS, Linux), rendering through the external PuiKit framework. It provides comprehensive file operations, cloud storage integration, and extensive customization capabilities.

Core Architecture

flowchart TB
    subgraph APP["Application Layer"]
        XeFMApp["XeFMApp — xefm/app.py<br/>Controller · PuiKit event loop · key→action mapping · pane state"]
    end

    subgraph MGR["Manager Systems"]
        direction LR
        Pane["PaneManager<br/>xefm.pane_manager"]
        FileOps["FileOperationService<br/>xefm.file_operations"]
        Task["TaskManager<br/>xefm.task"]
        Progress["ProgressManager<br/>xefm.progress_manager"]
        State["StateManager<br/>xefm.state_manager"]
        Log["LogManager<br/>xefm.log_manager"]
    end

    subgraph UI["UI Components — XeFM widgets built on PuiKit"]
        direction LR
        Panes["Panes &amp; Status<br/>PaneHeader · PaneFooter · StatusBar · LayoutView"]
        Viewers["Viewers<br/>Text · Diff · DirectoryDiff · Image · JSON/CSV/Markdown"]
        Dialogs["Dialogs<br/>FilterList · Search · BatchRename · Conflict · Jump · Drives"]
    end

    subgraph STORE["Storage Abstraction — Path Polymorphism"]
        direction LR
        Path["Path facade + PathImpl ABC<br/>xefm.path"]
        Local["LocalPathImpl<br/>xefm.path"]
        SSH["SSHPathImpl<br/>xefm.ssh"]
        S3["S3PathImpl<br/>xefm.s3"]
        Archive["ArchivePathImpl<br/>xefm.archive"]
        Path --> Local & SSH & S3 & Archive
    end

    subgraph PUI["PuiKit Framework — external UI toolkit (../puikit)"]
        direction LR
        Events["Event system<br/>puikit.event"]
        Widgets["Widgets<br/>ListView · TextEdit · Menu · Splitter · message box"]
        TextEng["Text · Theme · Font · Layout<br/>puikit.text / theme / font / layout"]
    end

    subgraph BE["PuiKit Backends"]
        direction LR
        Curses["Curses<br/>terminal"]
        MacOS["macOS<br/>native"]
        Windows["Windows<br/>native"]
    end

    XeFMApp --> MGR
    XeFMApp --> UI
    MGR --> STORE
    UI --> STORE
    UI --> PUI
    PUI --> BE

    classDef app fill:#1a5490,stroke:#7fb3d5,color:#ffffff;
    classDef mgr fill:#8b2e24,stroke:#e0897f,color:#ffffff;
    classDef ui fill:#1e7e34,stroke:#7fd39b,color:#ffffff;
    classDef store fill:#9a6308,stroke:#e0b45f,color:#ffffff;
    classDef pui fill:#5e2d70,stroke:#b98fd0,color:#ffffff;
    classDef be fill:#0e7c66,stroke:#5fd0b4,color:#ffffff;

    class XeFMApp app;
    class Pane,FileOps,Task,Progress,State,Log mgr;
    class Panes,Viewers,Dialogs ui;
    class Path,Local,SSH,S3,Archive store;
    class Events,Widgets,TextEng pui;
    class Curses,MacOS,Windows be;

Design principles

XeFM’s UI is assembled from small, reusable components, each owning one aspect of the interface. The principles that recur across them:

Component groups

The architecture diagram above shows how the pieces fit together; the full per-module inventory lives in PROJECT_STRUCTURE.md. The major groups are:

Key Features

File Management

Text Handling

Cloud Storage Integration

System Integration

Customization

Command Line Interface

Basic Usage

python3 -m xefm                    # Start with default settings
xefm                               # If installed via pip

Directory Specification

python3 -m xefm --left /projects --right /documents
python3 -m xefm --left . --right ..

Color Testing

XeFM includes comprehensive color support with multiple color schemes.

Configuration System

Configuration File

Configurable Settings

Development Architecture

Modular Design

Error Handling

Testing Framework

Dependencies

Required

Optional

Platform Support

Performance Characteristics

Optimizations

Scalability

Security Considerations

File Operations

Cloud Integration

Future Extensibility

Plugin Architecture

Integration Points

This overview provides a comprehensive understanding of XeFM’s current architecture, capabilities, and design principles.