# profanity-im/profanity architecture

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

- Interactive diagram: https://gitdiagram.com/profanity-im/profanity
- Repository: https://github.com/profanity-im/profanity

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["UI: Console\n(src/ui/)"]:::internal
    end

    %% Core Engine
    subgraph "Core Engine"
        CP["Command Parser\n(src/command/)"]:::internal
        ED["Event Dispatcher\n(src/event/)"]:::internal
        CLM["Chat Log Manager\n(src/chatlog.c)"]:::internal
        CM["Config Manager\n(src/config/)"]:::internal
        LG["Logger\n(src/log.c)"]:::internal
        CU["Common Utils\n(src/common.c)"]:::internal
        DBI["Database Interface\n(src/database.c)"]:::internal
    end

    %% Protocol Layer
    subgraph "Protocol Layer"
        XMPP["XMPP Module\n(src/xmpp/)"]:::internal
    end

    %% Encryption Modules
    subgraph "Encryption Modules"
        OMEMO["OMEMO Module\n(src/omemo/)"]:::internal
        OTR["OTR Module\n(src/otr/)"]:::internal
        PGP["PGP/OX Module\n(src/pgp/)"]:::internal
    end

    %% Plugin Subsystem
    subgraph "Plugin Subsystem"
        PL["Plugins\n(src/plugins/)"]:::plugin
    end

    %% Tools Subsystem
    subgraph "Tools Subsystem"
        Tools["Tools\n(src/tools/)"]:::tools
    end

    %% External Services
    subgraph "External Services"
        XSERVER["XMPP Server"]:::external
        CRYPTOLIB["Crypto Libs\n(libgcrypt/OpenSSL)"]:::external
        PYTHON["Python Runtime"]:::external
    end

    %% Tests
    subgraph "Tests"
        FT["Functional Tests\n(tests/functionaltests/)"]:::tests
        UT["Unit Tests\n(tests/unittests/)"]:::tests
    end

    %% Data Flows
    UI -->|"issues commands"| CP
    UI -->|"user input events"| ED
    CP -->|"parses commands"| ED
    ED -->|"dispatch to Config"| CM
    ED -->|"dispatch to ChatLog"| CLM
    ED -->|"dispatch to Logger"| LG
    ED -->|"dispatch to Utils"| CU
    ED -->|"dispatch to DB"| DBI
    ED -->|"builds stanza"| XMPP
    XMPP -->|"send/recv stanzas"| XSERVER
    XMPP -->|"incoming stanzas"| ED
    CP -->|"invoke tools"| Tools
    Tools -->|"results"| ED
    ED -->|"trigger plugins"| PL
    PL -->|"callbacks"| ED
    ED -->|"uses OMEMO"| OMEMO
    ED -->|"uses OTR"| OTR
    ED -->|"uses PGP/OX"| PGP
    OMEMO -->|"crypto ops"| CRYPTOLIB
    OTR -->|"crypto ops"| CRYPTOLIB
    PGP -->|"crypto ops"| CRYPTOLIB
    PL -->|"python hooks"| PYTHON
    CLM -->|"reads/writes"| DBI

    %% Test links
    FT --> UI
    FT --> CP
    FT --> XMPP
    FT --> OMEMO
    FT --> OTR
    FT --> PGP
    UT --> CP
    UT --> ED
    UT --> CM
    UT --> LG

    %% Click Events
    click UI "https://github.com/profanity-im/profanity/tree/master/src/ui/"
    click CP "https://github.com/profanity-im/profanity/tree/master/src/command/"
    click ED "https://github.com/profanity-im/profanity/tree/master/src/event/"
    click CLM "https://github.com/profanity-im/profanity/blob/master/src/chatlog.c"
    click CM "https://github.com/profanity-im/profanity/tree/master/src/config/"
    click LG "https://github.com/profanity-im/profanity/blob/master/src/log.c"
    click CU "https://github.com/profanity-im/profanity/blob/master/src/common.c"
    click DBI "https://github.com/profanity-im/profanity/blob/master/src/database.c"
    click XMPP "https://github.com/profanity-im/profanity/tree/master/src/xmpp/"
    click OMEMO "https://github.com/profanity-im/profanity/tree/master/src/omemo/"
    click OTR "https://github.com/profanity-im/profanity/tree/master/src/otr/"
    click PGP "https://github.com/profanity-im/profanity/tree/master/src/pgp/"
    click PL "https://github.com/profanity-im/profanity/tree/master/src/plugins/"
    click Tools "https://github.com/profanity-im/profanity/tree/master/src/tools/"
    click FT "https://github.com/profanity-im/profanity/tree/master/tests/functionaltests/"
    click UT "https://github.com/profanity-im/profanity/tree/master/tests/unittests/"

    %% Styles
    classDef internal fill:#89CFF0,stroke:#333,stroke-width:1px
    classDef plugin fill:#98FB98,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef tools stroke-dasharray: 5 5,fill:#FFEFD5,stroke:#333,stroke-width:1px
    classDef tests stroke-dasharray: 5 5,fill:#FFEFD5,stroke:#333,stroke-width:1px
```
