# hemna/aprsd-email-plugin architecture

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

- Interactive diagram: https://gitdiagram.com/hemna/aprsd-email-plugin
- Repository: https://github.com/hemna/aprsd-email-plugin

## Overview

##### Project Type and Purpose
- Type: Python plugin (library/extension) for the APRSD (“APRS Daemon”) project
- Purpose:
– Receive APRS frames from the radio network via APRSD
– Parse certain frames as “email” messages and relay them to an SMTP server
– Poll an IMAP inbox for new email and inject them back into APRS as APRS frames
– Acknowledge receipt back to the sender over APRS

##### High-Level File-Structure Analysis
- Top-level files: setup.cfg/pyproject.toml, setup.py, Makefile, tox.ini – standard Python package & CI
- aprsd_email_plugin/
– aprsd_email_plugin.py: plugin entrypoint and core logic
– conf/main.py & conf/opts.py: configuration parsing & CLI integration
- docs/: Sphinx-based documentation
- tests/: unit tests for parsing, send/receive, and main plugin behavior

##### Key Components
A. APRSD Core Daemon
– Plugin Loader / Event Loop
– Radio Interface (TNC/KISS) connecting to the APRS radio network
B. Email Plugin Module
– Initialization & Configuration (conf/main.py, conf/opts.py)
– APRS Message Parser (identify “email” frames)
– Outgoing Email Handler (SMTP client)
– Incoming Email Handler (IMAP client & poller)
– Acknowledgment Generator (builds ack frames)
C. External Services
– SMTP Server (internet email relay)
– IMAP Server (incoming mailbox)
– Amateur-radio network (APRS over RF or internet gateways)

##### Relationships & Data Flows
1. APRS-to-Email (Radio → APRSD → Plugin → SMTP):
- Radio network emits an APRS frame → APRSD Core receives it
- APRSD Core dispatches to loaded Email Plugin
- Plugin’s parser inspects the frame; if marked for email, extracts sender, recipient, payload
- Outgoing Email Handler uses SMTP client library to deliver to the recipient’s SMTP server
- Plugin generates an APRS “ack” frame and hands it back to APRSD to transmit on the radio
2. Email-to-APRS (IMAP → Plugin → APRSD → Radio):
- Plugin’s IMAP poller periodically connects to the IMAP server
- New messages are fetched; plugin formats each as an APRS frame
- Plugin hands frames to APRSD Core for transmission over the radio network
- Incoming APRS “ack” frames are parsed by the plugin to correlate delivery status

##### Architectural Patterns & Principles
- Plugin/Extension pattern: the Email logic is decoupled from APRSD Core, loaded at runtime
- Event-driven design: APRSD’s event loop triggers plugin callbacks on message arrival
- Separation of concerns:
– Configuration parsing (conf/)
– APRS frame parsing/generation (aprsd_email_plugin.py)
– Network I/O (SMTP/IMAP clients vs. TNC interface)
- Retry/Ack mechanism: frameless, stateless ack frames to ensure reliable delivery

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    RadioNetwork(("Radio Network"))
    SMTPServer[(SMTP Server)]
    IMAPServer[(IMAP Server)]

    classDef external fill:#bfb,stroke:#333,stroke-width:1px;
    classDef internal fill:#bbf,stroke:#333,stroke-width:1px;

    %% APRSD Core Daemon
    subgraph "APRSD Core Daemon"
        direction TB
        RadioInterface["Radio Interface (TNC/KISS)"]:::internal
        EventLoop["Event Loop"]:::internal
        PluginLoader["Plugin Loader"]:::internal
    end

    %% Email Plugin Module
    subgraph "Email Plugin Module"
        direction TB
        ConfigInit["Configuration Init & CLI"]:::internal
        Parser["APRS Message Parser"]:::internal
        SMTPSender["Outgoing Email Handler (SMTP)"]:::internal
        IMAPPoller["Incoming Email Handler (IMAP Poller)"]:::internal
        AckGen["Acknowledgment Generator"]:::internal
    end

    %% Flows: APRS-to-Email
    RadioNetwork -->|APRS frame| RadioInterface
    RadioInterface --> EventLoop
    EventLoop --> PluginLoader
    PluginLoader --> Parser
    Parser -->|email frame| SMTPSender
    SMTPSender -->|SMTP DATA| SMTPServer
    Parser --> AckGen
    AckGen -->|ack frame| PluginLoader
    PluginLoader --> RadioInterface
    RadioInterface --> RadioNetwork

    %% Flows: Email-to-APRS
    IMAPPoller -->|IMAP IDLE / Poll| IMAPServer
    IMAPPoller -->|new email| Parser
    Parser -->|APRS frame| PluginLoader
    PluginLoader --> RadioInterface
    RadioInterface --> RadioNetwork

    %% Click Events for mapped components
    click PluginLoader "https://github.com/hemna/aprsd-email-plugin/blob/master/aprsd_email_plugin/aprsd_email_plugin.py"
    click ConfigInit "https://github.com/hemna/aprsd-email-plugin/blob/master/aprsd_email_plugin/conf/main.py"
    click Parser "https://github.com/hemna/aprsd-email-plugin/blob/master/aprsd_email_plugin/aprsd_email_plugin.py"
    click SMTPSender "https://github.com/hemna/aprsd-email-plugin/blob/master/aprsd_email_plugin/aprsd_email_plugin.py"
    click IMAPPoller "https://github.com/hemna/aprsd-email-plugin/blob/master/aprsd_email_plugin/aprsd_email_plugin.py"
    click AckGen "https://github.com/hemna/aprsd-email-plugin/blob/master/aprsd_email_plugin/aprsd_email_plugin.py"
    click PluginLoader "https://github.com/hemna/aprsd-email-plugin/blob/master/tests/test_aprsd_email_plugin.py"
    click Parser "https://github.com/hemna/aprsd-email-plugin/blob/master/tests/test_email.py"
    click ConfigInit "https://github.com/hemna/aprsd-email-plugin/blob/master/tests/test_main.py"
    click IMAPPoller "https://github.com/hemna/aprsd-email-plugin/blob/master/docs/index.rst"

    %% Classes
    class RadioNetwork,SMTPServer,IMAPServer external
    class RadioInterface,EventLoop,PluginLoader,ConfigInit,Parser,SMTPSender,IMAPPoller,AckGen internal
```
