How profanity-im/profanity works
Project type and purpose
• Profanity is a console-based XMPP chat client written in C.
• It provides a text UI (ncurses), connects to XMPP servers, handles messaging, presence, multi-user chats, and supports multiple encryption protocols (OMEMO, OTR, PGP, OX).
• It is a monolithic application with a plugin API (C and Python) and a small tooling subsystem for downloads, uploads, and parsing.
File structure
• Top-level build and configuration: configure.ac, Makefile.am, Dockerfiles, CI workflows, autogen.sh.
• Documentation: README, docs/, apidocs/ for C and Python plugin API.
• Source (src/):
• ui/ – console windows, input/output, status bar, tray integration
• xmpp/ – connection, stanza handling, roster, presence, chat sessions, MUC, avatar, capabilities
• common, config/, database.c, log.c, event/ – core engine, configuration loader, chat log storage, event dispatch
• encryption subdirs: omemo/, otr/, pgp/ – protocol implementations and storage
• command/ – parsing and execution of user commands
• plugins/ – host APIs, plugin loader, callbacks, autocompletion, settings, themes, Python bindings
• tools/ – standalone utilities (http download/upload, plugin download, editor integration)
• profanity.c/h and main.c – entry point and global orchestration
• Tests/: functionaltests/ (end-to-end scripts) and unittests/ (stubs and unit tests per module).
README for additional insights
• It describes the client’s goal: privacy, encryption, decentralization via XMPP.
• Lists supported encryption: OTR, PGP, OMEMO, OX.
• Mentions plugin architecture and user customization (themes, scripts).
Components
a. Main components
• Presentation Layer: Console UI (ncurses windows, input handler, status bar)
• Core Engine: command parser, event dispatcher, chat log manager, config manager, logger
• Protocol Layer: XMPP client module (connection, stanza I/O, session manager)
• Encryption Modules: OMEMO, OTR, PGP/OX (each with crypto routines and storage)
• Plugin Subsystem: C API and Python API, plugin loader, callbacks, extension points
• Tools Subsystem: helper utilities for downloads, uploads, parser, editor integration
• Persistence: local database/chatlog storage, configuration files, TLS certificates
• External Services: XMPP server(s), encryption libraries (libgcrypt/OpenSSL), Python interpreter
b. Relationships and data flow
• UI issues commands → Core Engine
• Core Engine consults Config Manager and Plugins → decides actions
• Engine → XMPP Module: builds stanzas, sends to server
• Incoming stanzas → XMPP Module → Engine → Encryption Module (decrypt) → UI
• Encryption Module uses external crypto library → key stores → back to Engine
• Plugin Subsystem hooks into Engine events (on_message, on_presence, on_command)
• Tools invoked by Engine or user via commands (e.g., http_download)
• All runtime events logged to Chatlog DB via Database Module
c. Architectural patterns and design principles
• Layered architecture: Presentation (UI), Domain/Core, Infrastructure (network, storage)
• Event-driven: central event dispatcher routes XMPP events to handlers and plugins
• Plugin extensibility: clear API contracts for C and Python plugins
• Separation of concerns: distinct modules for config, logging, encryption, commands, UI
• Monolithic executable with dynamically loadable plugins
d. Key technologies and libraries
• C and ncurses (UI)
• POSIX sockets or GLib for networking
• libgcrypt/OpenSSL for crypto
• Python runtime (embeddable) for Python plugins
• XML parsing (e.g., Expat or custom) for XMPP stanzas